Sandbox Guide
Step-by-step instructions for simulating transactions and validating your integration with FlexPay
Note
To get started, you'll need an active FlexPay account and a sandbox API key. Please contact your Customer Success Manager (CSM) or Integration Manager to obtain these credentials.
Before launching your integration with FlexPay, it's crucial to thoroughly test your system by simulating various transaction scenarios without generating a "real" transaction with the Merchant bank. This ensures that your setup can handle real-world situations and is ready for a live environment. FlexPay offers two methods for conducting sandbox testing to help you validate your integration:
- FlexPay Sandbox Gateway: In this method, you'll create a specific gateway tailored for testing purposes. You'll use test cards provided by FlexPay and specific transaction amounts to simulate various scenarios, such as:
- Approved payments
- Soft declines
- Hard declines
- Invalid requests
- Native Gateway in Sandbox Mode:This method involves setting up a native gateway (e.g., Auth.net, Adyen, Stripe) in Sandbox mode. Transactions processed in this mode are routed through FlexPay to the gateway's sandbox endpoint. Refer to the gateway's documentation to obtain the appropriate test cards and/or amounts needed to simulate different scenarios.
Please note that not all gateways are available for sandbox testing. Refer to this page for a list of supported gateways.
Now, let's walk through the steps required to perform some of these tests.
FlexPay Sandbox Gateway
FlexPay offers a sandbox environment to clients to test the new integration setup before going live. The sandbox endpoint is the same as the production endpoint (https://api.flexpay.io/v1/). You can send transactions to the Sandbox gateway by using a Sandbox API Key.
The sandbox gateway provides access as if you were in a live environment allowing you to safely simulate different response codes between FlexPay and the CRM without actually sending transactions to your payment gateway, and as such test transactions do not generate a response error code.
There are predefined inputs that are required to validate gateway response codes by using specified amounts, specific test cards and specific transaction types.
To begin testing transactions, you must first create a FlexPay Sandbox Gateway. This setup is accessible through the Payment Gateways menu. Follow these steps to create the gateway:
- Navigate to the FlexPay login page and enter your credentials to access the portal.
- From the left-side menu, under the ADMIN section, click on Payment Gateways.
- Ensure that the Sandbox environment is selected and verify that you are working under the correct company. This information is located at the top right, next to the account name.
- Click ADD GATEWAY and select FlexPay Sandbox
- Enter Gateway Details:
Name: Choose a descriptive name for your gateway.
Merchant Account Reference ID: This value is crucial as it indicates to FlexPay which transactions to process through this gateway. It acts as a routing identifier.
Merchant Reference: Although this won't be used in your requests, it may be important for internal reference.
- After filling out these details, click ADD GATEWAY to finalize the setup.
- Your gateway is now set up and ready for you to begin running your tests.
Note
For the Test Cards and Amount to use, please refer to https://documentation.flexpay.io/docs/testing-guide
Below is an example of a CHARGE request that will generate an "insufficient funds" response. Be sure to pay close attention to the Credit Card, Amount, and the Merchant Account Reference ID.
{
"transaction": {
"merchantTransactionId": "Test-trx-0088",
"orderId": "Order4934988",
"amount": 2012,
"currencyCode": "USD",
"retryCount": 1,
"paymentMethod": {
"creditCardNumber": "4920201996449560",
"lastFourDigits": "",
"firstSixDigits": "",
"expiryMonth": "07",
"expiryYear": "27",
"firstName": "John",
"lastName": "Doe",
"fullName": "",
"address1": "111 Avenue cool",
"address2": "",
"postalCode": "J7Y3U9",
"city": "Montreal",
"state": "QC",
"country": "CA",
"email": "[email protected]",
"merchantAccountReferenceId": "Test-USD"
},
"dateFirstAttempt": "2024-08-13T10:05:03Z",
"customerId": "APL600021552",
"customerIp": "127.0.0.1"
}
}
{
"transaction": {
"response": {
"avsCode": "S",
"avsMessage": "AVS not supported.",
"cvvCode": "M",
"cvvMessage": "(No Match) – The CVD value provided does not match the CVD value associated with the card.",
"errorCode": null,
"errorDetail": ""
},
"engagedRecoveryState": 0,
"paymentMethod": {
"paymentMethodId": "M6MLY36I5KAUVLSKAGIU2XSVSE",
"creditCardNumber": "492020******9560",
"expiryMonth": "07",
"expiryYear": "27",
"cvv": "",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"customerId": "APL600021552",
"address1": "111 Avenue cool",
"address2": "",
"postalCode": "J7Y3U9",
"city": "Montreal",
"state": "QC",
"country": "CA",
"email": "[email protected]",
"phoneNumber": null,
"paymentMethodType": "CreditCard",
"fingerprint": "M6MLY36I5KAUVLSKAGIU2XSVSE",
"lastFourDigits": "9560",
"firstSixDigits": "492020",
"cardType": "VISA",
"dateCreated": "2024-08-13T20:11:53.617Z",
"storageState": "Cached",
"merchantAccountReferenceId": "Test-USD"
},
"transactionId": "068MTQJMMR0000F1082D0WJ3ZH4ZG",
"transactionDate": "2024-08-13T20:11:53.382Z",
"transactionStatus": 2,
"message": "The card has been declined due to insufficient funds.",
"responseCode": "20023",
"transactionType": "Charge",
"merchantTransactionId": "Test-trx-0088",
"customerId": "APL600021552",
"currencyCode": "USD",
"amount": 2012,
"gatewayToken": "HK7ETLNFNWJE7IDDAGF7KNTNOA",
"gatewayType": "flexpay_sandbox",
"gatewayTransactionId": "9ff7dc26-f36e-4765-822b-01914d5e560e",
"merchantAccountReferenceId": "SUPSandbox",
"assignedGatewayToken": "HK7ETLNFNWJE7IDDAGF7KNTNOA",
"orderId": "Order4934988",
"retryDate": "2024-08-14T00:00:00",
"retryCount": 1,
"dateFirstAttempt": "2024-08-13T10:05:03Z",
"description": null,
"productSku": null,
"subscriptionId": null,
"productCategory": null,
"billingPlan": null,
"customerIp": "127.0.0.1",
"billingCycle": 1,
"shippingAddress": {
"address1": null,
"address2": null,
"postalCode": null,
"city": null,
"state": null,
"country": null
},
"referenceData": "CAABAICxOGZ/u9wIOr5JraVtkk+gYwGL9TZtcNByQ/xJ+OEBAAABkU1eVKY=",
"disableCustomerRecovery": false,
"customVariable1": null,
"customVariable2": null,
"customVariable3": null,
"customVariable4": null,
"customVariable5": null
}
}
Native Gateway in Sandbox Mode
When testing directly with native gateways, you’re performing a comprehensive end-to-end test. FlexPay will function exactly as it would in a live production environment, and all test scenarios will depend on the specific gateway you are using. For this example, we'll walk through the process using Stripe as our gateway
Similar to the FlexPay Sandbox Gateway setup, this configuration can be accessed through the Payment Gateways menu. Follow these steps to create the gateway:
- Navigate to the FlexPay login page and enter your credentials to access the portal.
- From the left-side menu, under the ADMIN section, click on Payment Gateways.
- Ensure that the Sandbox environment is selected and verify that you are working under the correct company. This information is located at the top right, next to the account name.
- Click ADD GATEWAY and select StripePaymentIntents
- Enter Gateway Details:
Name: Choose a descriptive name for your gateway.
Merchant Account Reference ID: This value is crucial as it indicates to FlexPay which transactions to process through this gateway. It acts as a routing identifier.
Api Key: Stripe API Key. It should start with "sk_test_51J5Zom".
Account ID: ID of your Stripe account (How to find it).
- After filling out these details, click ADD GATEWAY to finalize the setup.
- Your gateway is now set up and ready for you to begin running Stripe tests.
You can find Stripe's test cards in the following document.
Below is an example of a CHARGE request that will generate an "insufficient funds" response. Be sure to pay close attention to the Credit Card and the Merchant Account Reference ID.
{
"transaction": {
"merchantTransactionId": "Test-trx-0089",
"orderId": "Order4934989",
"amount": 3000,
"currencyCode": "USD",
"retryCount": 1,
"paymentMethod": {
"creditCardNumber": "4000000000009995",
"lastFourDigits": "",
"firstSixDigits": "",
"expiryMonth": "05",
"expiryYear": "25",
"firstName": "John",
"lastName": "Doe",
"fullName": "",
"address1": "111 Avenue cool",
"address2": "",
"postalCode": "J7Y3U9",
"city": "Montreal",
"state": "QC",
"country": "CA",
"email": "[email protected]",
"merchantAccountReferenceId": "Test-Stripe"
},
"dateFirstAttempt": "2024-08-13T10:05:03Z",
"customerId": "APL600021553",
"customerIp": "127.0.0.1"
}
}
{
"transaction": {
"response": {
"avsCode": null,
"avsMessage": null,
"cvvCode": null,
"cvvMessage": null,
"errorCode": "insufficient_funds",
"errorDetail": "Your card has insufficient funds."
},
"engagedRecoveryState": 0,
"paymentMethod": {
"paymentMethodId": "I5AJYJ7JWFFEDK7UAGIVEIRLJY",
"creditCardNumber": "400000******9995",
"expiryMonth": "05",
"expiryYear": "25",
"cvv": "",
"firstName": "John",
"lastName": "Doe",
"fullName": "John Doe",
"customerId": "APL600021553",
"address1": "111 Avenue cool",
"address2": "",
"postalCode": "J7Y3U9",
"city": "Montreal",
"state": "QC",
"country": "CA",
"email": "[email protected]",
"phoneNumber": null,
"paymentMethodType": "CreditCard",
"fingerprint": null,
"lastFourDigits": "9995",
"firstSixDigits": "400000",
"cardType": "VISA",
"dateCreated": "2024-08-14T18:24:16.718Z",
"storageState": "Cached",
"merchantAccountReferenceId": "Test-Stripe"
},
"transactionId": "068N48HAY00000F1002FJJ7CVRFBE",
"transactionDate": "2024-08-14T18:24:16.624Z",
"transactionStatus": 2,
"message": "The card has been declined due to insufficient funds.",
"responseCode": "20023",
"transactionType": "Charge",
"merchantTransactionId": "Test-trx-0089",
"customerId": "APL600021553",
"currencyCode": "USD",
"amount": 3000,
"gatewayToken": "HGNED4NRRPDUHLFUAGF2ULAT6Q",
"gatewayType": "stripe_payment_intents",
"gatewayTransactionId": "ch_3PnlrpGDZrL0TUCj0IrGTl6u",
"merchantAccountReferenceId": "SUPStripe",
"assignedGatewayToken": "HGNED4NRRPDUHLFUAGF2ULAT6Q",
"orderId": "Order4934989",
"retryDate": "2024-08-15T23:00:00",
"retryCount": 1,
"dateFirstAttempt": "2024-08-13T10:05:03Z",
"description": null,
"productSku": null,
"subscriptionId": null,
"productCategory": null,
"billingPlan": null,
"customerIp": "127.0.0.1",
"billingCycle": 1,
"shippingAddress": {
"address1": null,
"address2": null,
"postalCode": null,
"city": null,
"state": null,
"country": null
},
"referenceData": "MwABAICxOGZ/u9wIOZpB8bGLx0OstAGLqiwT9PlI7N4et+EBAAABkVIiKvA=",
"disableCustomerRecovery": false,
"customVariable1": null,
"customVariable2": null,
"customVariable3": null,
"customVariable4": null,
"customVariable5": null
}
}
This process can be applied to any gateway that FlexPay supports for end-to-end sandbox testing.
Updated about 2 months ago