DC Sandbox

DC Sandbox Overview

The PayNet Open Finance Platform Sandbox provides a complete simulation of the production environment for testing and development purposes. The Sandbox allows developers to:

• Test all API endpoints without affecting real data
• Experiment with different integration flows
• Validate security implementations
• Test error handling scenarios
• Use test certificates for development

Sandbox Environment URLs

Authorization Server

Sandbox URLs will be furnished to participants on registration.

Resource Server

Sandbox URLs will be furnished to participants on registration.

Key Differences from Production

The Sandbox environment has the following differences to facilitate testing:

Certificate Requirements

• Self-signed certificates: Allowed for testing (not allowed in production)
• Certificate validation: Relaxed validation for development certificates
• Certificate expiry: Accepts certificates with shorter validity periods

Token Lifetimes

• Access tokens: Extended lifetime (60 minutes vs 15 minutes in production)
• Refresh tokens: Extended lifetime for testing convenience
• Authorization codes: Extended lifetime (10 minutes vs 60 seconds in production)

Rate Limits

• Higher limits: More permissive rate limits for testing
• No strict enforcement: Rate limiting is logged but not strictly enforced
• Testing scenarios: Allows rapid testing of multiple scenarios

Error Messages

• Detailed errors: More detailed error messages for debugging
• Stack traces: May include stack traces in development
• Logging: Enhanced logging for troubleshooting

Data

• Test data: Pre-populated with test Data Providers and user accounts
• Synthetic data: All data is synthetic and not real customer information
• Data reset: Test data can be reset upon request

Getting Started with Sandbox

Step 1: Register for Sandbox Access

1. Contact PayNet: Refer to the Contact Us page

2. Provide Information:

   • Organization name
   • Technical contact details
   • all other technical or business information requested by PayNet

3. Receive Credentials:

   • Sandbox client_id
   • Sandbox dc_id
   • Test certificates (or instructions for self-signed)
   • Test user accounts

Step 2: Set Up Test Certificates

Transport Certificate

PayNet will provide you with the transport certificate and key to be used for mutual TLS.

This is a self signed certificate and is for use in the Sandbox only.

Signing & Encryption Keys

For using the DC API, you will need to have a key pair for signing and a key pair for encryption.

You will need to host the public key for signing and encryption on a public JWKS (JSON Web Key Set) endpoint.

Alternatively, PayNet can provide you with test keys and host a JWKS endpoint that you can use for testing.

Please express your preference at the point of registration.

It is possible for participants to begin with a PayNet issued key pair and then transition later to their own key pair. Please raise a support ticket if you would like to make this change.

Step 3: Configure Postman for testing the flows

We recommend that you begin exploring the APIs by using the Postman collection provided by PayNet. The Postman Collection can be downloaded from here

1. Install Postman:

   • Download and install Postman

   Please note that the web version of Postman cannot be used for accessing APIs that use mutual TLS.

2. Import the Collection:

   • Open Postman and import the collection from the downloaded file

3. Import the Environment:

   • PayNet will issue a Postman environment file once you are registered. This file has URLs to the appropriate authorization and resource servers and your identifiers such as client_id and dc_id
   • Import the environment file into Postman
   • Set the selected environment to the environment that you imported

4. Add your signing and encryption private keys to the environment:

   • The postman collection includes some helper APIs to enable signing and decryption of payloads without having to write any code. For this feature to work correctly your signing and encryption keys must be added to the environment in the appropriate fields
   • Set the pem-local field to your signing key. Please ensure that there are no newline characters in the file
   • Set the kid-local field to the kid value with which your signing key is published on your JWKS endpoint
   • Set the enc-local field to your encryption key. Please ensure that newline characters are replaced with \r\n

   Please note that due to the vagaries of the crypto library used, the treatment of newline characters in the signing and encryption files is different.

5. Configure the transport certificate:

   • In order to use the API endpoints that require mutual TLS, you will need to configure the transport certificate and key in Postman
   • Click on the configure icon (top right corner of the Postman window) and select Certificates. Add the sandbox domain with a wildcard prefix

6. Test the Postman flows:

   • Run the test cases in the Postman collection to ensure that the API endpoints are working correctly and to gain an understanding of the APIs

Step 4: Build your Open Finance application

Once you have had a successful test run, using the Postman collections, you will be sufficiently familiar with the OFM DC APIs to develop your own application.

You can continue to connect to the sandbox environment directly through your application, without the need to use Postman.

In order to do so, you will need to setup your one or more of your own redirect_uris. Please contact PayNet to register your redirect_uris as required.

You will also need to develop the code required to sign and decrypt the payloads. The sandbox and postman collection provide you convenience methods for message signing and message decryption that will not be available in a production environment.

Sample Data

Providers

The Sandbox includes several test Data Providers.

Please see this user guide to learn how to Discover the Data Providers.

Test User Accounts

To authorize a consent, you will need to use one of the test user accounts provided by PayNet.

The Sandbox offers three DPs as listed below, each with their own set of test user accounts. Each DP has a different set of accounts and data to allow you to test different scenarios.

The following users can be used to test the consent flow.

Testing Webhook Events

Functionality will shortly be added to the sandbox for DCs to test consent web hooks.

DCs will be able to trigger a test event through the Postman Collection.

They can opt to register a webhook endpoint with PayNet sandbox to receive test events or use Postman to view webhook events.

This section will be updated with further details once this functionality is enabled.

Common Testing Scenarios

This section provides some suggested scenarios for DCs to test out.

DCs will have to modify the postman collections to try out the negative flows

Scenario 1: Complete Consent Flow

1. Create consent via PAR
2. Authorize with test user
3. Receive webhook notification
4. Exchange code for tokens
5. Retrieve account data
6. Test token refresh
7. Revoke consent
8. Suspend consent
9. Reactivate consent
10. Verify id_token
11. Verify JWS responses and decrypt the JWE contained within
12. Use pagination parameters to view paginated transaction responses

Scenario 2: Error Handling

1. Test invalid client_id
2. Test expired authorization code
3. Test invalid access token
4. Test consent not found
5. Test rate limit exceeded
6. Test invalid signature

Scenario 3: Multi-Account Selection

1. Create consent for multiple accounts
2. User selects specific accounts
3. Verify consented accounts in response
4. Test access to selected accounts only

Getting Help

To contact PayNet for support see Contact Us

When reporting issues, please provide as much detail as possible to help us diagnose the problem quickly.

Include in support requests:

• x-fapi-interaction-id for API issues
• Your client_id and dc_id
• Timestamp of the issue
• Request/response details
• The specific error messages received

Migration to Production

Before moving to production:

Checklist

• [ ] All test scenarios passing in sandbox
• [ ] Error handling implemented and tested
• [ ] Webhook endpoint secured and tested
• [ ] Token refresh logic implemented
• [ ] Certificate management process defined
• [ ] Security review completed
• [ ] Logging and monitoring implemented
• [ ] Performance testing completed
• [ ] Production certificates obtained
• [ ] Production client registration completed

Production Differences

When moving to production, update:

1. URLs: Change to production URLs
2. Certificates: Replace with production CA-issued certificates
3. Client ID: Use production client_id
4. Token Lifetimes: Adjust for shorter production lifetimes
5. Rate Limits: Implement production rate limit handling
6. Error Handling: Remove debug logging of sensitive data
7. Monitoring: Enable production monitoring and alerting

For production deployment, see Production Guide.

Sandbox Maintenance

Maintenance Windows

A maintenance schedule will be announced in advance.

Minimum Data Retention

• Logs retained for 30 days
• Webhook events retained for 7 days