Testing for Payment API
The payments platform provides a sandbox environment where you can test your code's interaction with the platform.
The sandbox has a few features that are not present in the production environment. These features are designed to help you test your code.
Just like the production environment, the sandbox generates webhooks. To receive webhooks from the sandbox, use the procedure described in Defining a Webhook Endpoint.
The following sections describe testing capabilities of the payments platform.
How-To Procedures
Error Simulation
When you are experimenting in the Payment API sandbox, you can use specific transaction amounts to evoke error responses from the Rapyd platform. Any amount in the given range produces the error. Amounts outside these ranges behave normally. The errors are simulated only with the amount
parameter, and the values of other parameters behave normally.
All Payment Types
Amount | Error Response |
---|---|
4000-4009 | The gateway is not responding. |
Online Payments
Amount | Error Response |
---|---|
2000-2009 | The sandbox detected a simulated error, where the payment could not be processed because settlement was declined. |
2020-2029 | Settlement is pending on the gateway. |
2080-2089 | The processor is unavailable. |
Redirect Payments
Amount | Error Response |
---|---|
2120-2129 | Insufficient funds in the account. |
2180-2189 | Payment expired. |
When the API is triggered, it sends a notification message with payment details to the configured URL. Payments with an amount that matches one of the ranges listed above will have the associated error in the failure_code
parameter.
Card Numbers for Testing
When you make test API calls for card payments, you can use test card numbers.
Numbers for Successful Transactions
You can use any card number that you find in the examples for the API methods, including the following card numbers:
4111111111111111
4462030000000000
You can use any card expiration date in the future, and any 3 digits for the CVV.
Numbers for Error Transactions
Note
In the sandbox, these numbers are valid for all card payment methods in payments created by Create Payment and hosted checkout pages.
Use the following card numbers in the sandbox to simulate rejection of a card payment:
Card Number | Type of Rejection |
---|---|
4111111111111105 | Do Not Honor. |
4111111111111143 | Stolen Card, pick up. |
4111111111111151 | Insufficient Funds. |
Do Not Honor error
{ "status": { "error_code": "ERROR_PROCESSING_CARD - [05]", "status": "ERROR", "message": "Do Not Honor", "response_code": "ERROR_PROCESSING_CARD - [05]", "operation_id": "43c320f4-5f4a-4f89-a874-8da5df13ac82" } }
Stolen Card error
{ "status": { "error_code": "ERROR_PROCESSING_CARD - [43]", "status": "ERROR", "message": "Stolen Card, pick up", "response_code": "ERROR_PROCESSING_CARD - [43]", "operation_id": "6c0830fd-415d-4775-9410-afefd51773c3" } }
Insufficient Funds error
{ "status": { "error_code": "ERROR_PROCESSING_CARD - [51]", "status": "ERROR", "message": "Insufficient Funds", "response_code": "ERROR_PROCESSING_CARD - [51]", "operation_id": "563694e5-3454-474a-92b0-24ae720538b7" } }
You can use any card expiration date in the future, and any 3 digits for the CVV.
Simulating 3DS Authentication - Hosted Page
When a hosted page requires 3DS authentication for a card operation, you can simulate the authentication in the sandbox. Relevant where the payment method category is card.
The 3DS simulator authenticates the card, the operation is completed, and Rapyd sends a webhook.
Card operations with 3DS authentication must be authenticated within 15 minutes.
3DS authentication is available for the following card operations:
Create Checkout Page
Save Card Details
To simulate 3DS authentication in the sandbox:
Method | Description |
---|---|
Set | |
Creates a token that represents the card. Use the token to create payments later. The simulator requires 3DS for all card payment methods. In production, the requirements differ from card to card. |
When authentication is complete, Rapyd returns the following webhooks:
Method | Webhook |
---|---|
Create Checkout Page | PAYMENT_COMPLETED |
Create Card Token | CUSTOMER_UPDATED |
The example below illustrates creating a checkout page for a card payment that requires 3DS authentication, using the checkout page, and simulating the authentication.
Creating a Checkout Page with 3DS Authentication
To create a checkout page for a payment that requires 3DS authentication, specify an amount above 1000. See Create Checkout Page.
Create Checkout Page Request
In this example, the value of amount
is 1050.
Request URL - post https://sandboxapi.rapyd.net/v1/checkout
{ "amount": 1050, "country": "US", "currency": "USD", "payment_method_type": "us_visa_card" }
Create Checkout Page Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "6cb9f46d-2c5b-4efe-8de2-6f19cdafc9f4" }, "data": { "id": "checkout_09fe498440294d5463ea9220c47fda62", "status": "NEW", // ... "redirect_url": "https://sandboxcheckout.rapyd.net?token=checkout_09fe498440294d5463ea9220c47fda62", // ... "country": "US", "currency": "USD", "amount": 1050, // ... "payment_method_type": "us_visa_card", // ... } }
In the data
section:
redirect_url
- The URL for the checkout page.
Simulating Rapyd Verify Application Responses
After a Rapyd Verify application is submitted, it is reviewed. After the review, Rapyd sends one of the following responses to the applicant:
Approved - The application has been approved.
Pending Information - More data is required from the applicant.
Not Approved - The application has been rejected.
You can simulate these responses in the sandbox.
Simulating a Response
Create a Rapyd Verify application as described in Create Rapyd Verify Application.
Open the link for the hosted application in a Web browser. When an authentication code page appears, enter 111111. The Business Details page appears.
In the Business Description field of the Business Details tab, enter one of the following values: approved, rejected, pending.
Fill in all the mandatory fields of the application, and save it.
Submit the application. A confirmation message appears.
Click Submit.
A confirmation page appears.
The APPLICATION_STATUS_CHANGE webhook is sent. The
to_status
value indicates the new status. See Webhook - Application Status Change.
Simulating 3DS Authentication
Certain card operations require 3DS authentication by the cardholder. You can simulate this authentication in the sandbox. Relevant where the payment method type is card.
For details, see the following pages:
Related Information
Simulating 3DS Authentication - API Method
When an API method requires 3DS authentication for a card operation, you can simulate the authentication in the sandbox. Relevant where the payment method category is card.
The 3DS simulator authenticates the card, the operation is completed, and Rapyd sends a webhook.
Card operations with 3DS authentication must be authenticated within 15 minutes.
3DS authentication is available for the following card operations:
Create Payment.
Create Customer with card payment method.
Add card payment method to existing customer.
To simulate 3DS authentication in the sandbox:
Method | Description |
---|---|
Create Payment | Set |
Create Customer | The simulator requires 3DS for all card payment methods. In production, the requirements differ from card to card. |
Add Payment Method to Customer | The simulator requires 3DS for all card payment methods. In production:
|
The API response includes the following fields:
Field | Description |
---|---|
| 3d_verification - 3DS authentication is required to complete the operation. |
| The URL for simulating 3DS authentication. |
| ACT - The payment is active and awaiting completion of 3DS. Relevant to payments. |
When authentication is complete, the API returns the following webhooks:
Method | Webhook |
---|---|
Create Payment | PAYMENT_COMPLETED |
Create Customer | CARD_ADDED_SUCCESSFULLY |
Add Payment Method to Customer | CARD_ADDED_SUCCESSFULLY |
The example below illustrates creating a card payment that requires 3DS authentication and simulating the authentication.
Creating a Payment with 3DS Authentication
To create a payment that requires 3DS authentication, specify an amount above 1000 and not one of the amounts described on Error Simulation. See Create Payment.
Create Payment Request
In this example, the value of amount
is 1050.
Create Payment Request
Request URL - post https://sandboxapi.rapyd.net/v1/payments
{ "amount": 1050, "currency": "USD", "payment_method": { "type": "us_visa_card", "fields": { "number": "4111111111111111", "expiration_month": "12", "expiration_year": "25", "cvv": "789", "name": "John Doe" } }, "capture": true }
Create Payment Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "42416643-4159-49a8-8c65-4a17e8d4e489" }, "data": { "id": "payment_46bd13214fe6e7ab9f12f70e64d5743c", "amount": 0, "original_amount": 1050, "is_partial": false, "currency_code": "USD", "country_code": "US", "status": "ACT", // ... "payment_method": "card_761c1a5ce9b7af77f5f6cd539fb1fcbb", "payment_method_data": { "id": "card_761c1a5ce9b7af77f5f6cd539fb1fcbb", "type": "us_visa_card", "category": "card", // ... "next_action": "3d_verification" }, // ... "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_46bd13214fe6e7ab9f12f70e64d5743c", // ... "next_action": "3d_verification", // ... }, }
In the data
section:
status
- The status of the payment is ACT (active). The payment is active and awaiting completion of 3DS authentication.redirect_url
- The URL for 3DS authentication.next_action
- The value is 3d_verification. 3DS authentication is required to complete the payment.
Simulating Cardholder Disputes
You can simulate cardholder disputes in the sandbox.
Create a payment using a specific, reserved card number. See Create Payment.
Reserved Card Numbers
To simulate a specific type of dispute, use one of the following card numbers in the payment_method
object of the Create Payment request:
Card Number | Type of Cardholder Dispute |
---|---|
4539922288211219 | Goods or services not provided. |
4556028624137080 | Subscription canceled. |
4556942399248726 | Counterfeit merchandise. |
5374500863109043 | Credit not processed. |
5132803130357186 | Cardholder dispute - miscellaneous. |
Example Disputed Transaction Request
Request URL - post https://sandboxapi.rapyd.net/v1/payments
{ "amount": 26.49, "currency": "USD", "merchant_reference_id": "042620221450", "payment_method": { "type": "us_visa_card", "fields": { "number": "4539922288211219", "expiration_month": "11", "expiration_year": "25", "cvv": "123", "name": "John Doe" } }, "ewallets": [ { "ewallet": "ewallet_e67c8ad63200d781470a04107fbd7c59", "percentage": 100 } ], "metadata": { "merchant_defined": "created" }, "capture": true }
Example Disputed Transaction Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "49e868c9-e886-4e0e-bb25-11aa47b6a9b7" }, "data": { "id": "payment_ce936f36d93bc9307a3db9ebfd3deaaa", "amount": 26.49, "original_amount": 26.49, "is_partial": false, "currency_code": "USD", "country_code": "US", "status": "CLO", "description": "", "merchant_reference_id": "042620221450", "customer_token": "cus_62c7139fb12eb0c57a7cc52382b549c4", "payment_method": "card_39d8aee398dfa5492fc2a0ea2822958f", "payment_method_data": { "id": "card_39d8aee398dfa5492fc2a0ea2822958f", "type": "us_visa_card", "category": "card", "metadata": null, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "name": "John Doe", "last4": "1219", "acs_check": "unchecked", "cvv_check": "unchecked", "bin_details": { "type": null, "brand": null, "level": null, "country": null, "bin_number": "453992" }, "expiration_year": "25", "expiration_month": "11", "fingerprint_token": "ocfp_f63d2a47a4ccca8613e8b00dc481d461", "network_reference_id": "123456" }, "expiration": 1651578901, "captured": true, "refunded": false, "refunded_amount": 0, "receipt_email": "", "redirect_url": "", "complete_payment_url": "", "error_payment_url": "", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "Doc Team", "transaction_id": "", "created_at": 1650974101, "metadata": { "merchant_defined": "created" }, "failure_code": "", "failure_message": "", "paid": true, "paid_at": 1650974101, "dispute": { "id": "1d34c78e-4adf-49df-9450-f5bd78300834", "token": "dispute_3e4862ba69665f04da530154f1019998", "status": "ACT", "amount": 26.49, "currency": "USD", "dispute_category": "Cardholder Dispute", "dispute_reason_description": "Goods or Services Not Provided", "original_transaction_currency": "USD", "original_transaction_amount": 26.49, "original_dispute_amount": 26.49, "original_dispute_currency": "USD", "original_transaction_id": "payment_ce936f36d93bc9307a3db9ebfd3deaaa", "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "central_processing_date": null, "created_at": 1650974101, "updated_at": 1650974101, "due_date": 1651751701, "payment_method": "card_39d8aee398dfa5492fc2a0ea2822958f", "payment_method_data": { "id": "card_39d8aee398dfa5492fc2a0ea2822958f", "type": "us_visa_card", "category": "card", "metadata": null, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "name": "John Doe", "last4": "1219", "acs_check": "unchecked", "cvv_check": "unchecked", "bin_details": { "type": null, "brand": null, "level": null, "country": null, "bin_number": "453992" }, "expiration_year": "25", "expiration_month": "11", "fingerprint_token": "ocfp_f63d2a47a4ccca8613e8b00dc481d461" }, "rate": 1, "evidence": null, "evidence_reason_code": null, "pre_dispute": false }, "refunds": null, "order": null, "outcome": null, "visual_codes": {}, "textual_codes": {}, "instructions": [], "ewallet_id": "ewallet_e67c8ad63200d781470a04107fbd7c59", "ewallets": [ { "ewallet_id": "ewallet_e67c8ad63200d781470a04107fbd7c59", "amount": 26.49, "percent": 100, "refunded_amount": 0 } ], "payment_method_options": {}, "payment_method_type": "us_visa_card", "payment_method_type_category": "card", "fx_rate": 1, "merchant_requested_currency": null, "merchant_requested_amount": null, "fixed_side": "", "payment_fees": null, "invoice": "", "escrow": null, "group_payment": "", "cancel_reason": null, "initiation_type": "customer_present", "mid": "", "next_action": "not_applicable", "error_code": "", "remitter_information": {} } }
Simulated Errors
The following errors are produced in the sandbox environment. You can intentionally generate these errors as described in Error Simulation.
ERROR_CREATE_PAYMENT_GATEWAY_NOT_RESPONDING
This is a simulated error because the amount was set between 4000 and 4009. The simulated error is INTERNAL_ERROR.
ERROR_PROCESS_PAYMENT_EXPIRED
The sandbox detected a simulated error, where the payment could not be processed because of expiration of the payment.
ERROR_PROCESS_PAYMENT_INSUFFICIENT_FUNDS
The sandbox detected a simulated error, where the payment could not be processed because of insufficient funds in the source of funds.
ERROR_PROCESS_PAYMENT_PROCESSOR_UNAVAILABLE
The sandbox detected a simulated error, where the payment could not be processed because the payment processor was unavailable.
ERROR_PROCESS_PAYMENT_SETTLEMENT_DECLINED
The sandbox detected a simulated error, where the payment could not be processed because settlement was declined.
ERROR_PROCESS_PAYMENT_SETTLEMENT_PENDING_ON_GATEWAY
The sandbox detected a simulated error, where the payment could not be processed because settlement remained pending on the gateway.