Skip to main content

Documentation

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

Create Checkout Page

Set amount to 1000 or above. Certain amounts above 2000 trigger specific errors instead of the 3DS flow. See Error Simulation.

Create Card Token

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

  1. Create a Rapyd Verify application as described in Create Rapyd Verify Application.

  2. Open the link for the hosted application in a Web browser. When an authentication code page appears, enter 111111. The Business Details page appears.

    643e7cbf403b3.png

  3. In the Business Description field of the Business Details tab, enter one of the following values: approved, rejected, pending.

  4. Fill in all the mandatory fields of the application, and save it.

  5. Submit the application. A confirmation message appears.

    643e7cc09f485.png

  6. Click Submit.

    A confirmation page appears.

    643e7cc1c7625.png

    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 amount to 1000 or above. Certain amounts above 2000 trigger specific errors instead of the 3DS flow. See Error Simulation. For an amount below 1000, set payment_method_options.3d_required to true. Relevant to card payment methods where the response to Get Payment Method Required Fields includes 3d_required.

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 requirements differ from card to card.

  • 3DS authentication is required when payment_method_options.3d_required is set to true. Relevant to payment methods where the response to Get Payment Method Required Fields includes 3d_required.

The API response includes the following fields:

Field

Description

next_action

3d_verification - 3DS authentication is required to complete the operation.

redirect_url

The URL for simulating 3DS authentication.

status

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.

In this section: