Skip to main content

Documentation

Simulating 'Create Payment' with 3DS - API

When you create a card payment, 3DS authentication of the cardholder is sometimes required. You can use the API to simulate this process in the sandbox.

Relevant where the payment method category is card.

Simulated card operations with 3DS authentication must be authenticated within 15 minutes. The 3DS simulator authenticates the card, the payment is created, and Rapyd sends a webhook.

Prerequisites

  • Keys to the sandbox environment for your user.

  • A properly configured testing tool.

How
  1. Create a payment with one of the following settings:

    • 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.

    For example:

      • Request

        • curl -X post
          https://sandboxapi.rapyd.net/v1/payments/
          -H 'access_key: your-access-key-here'
          -H 'Content-Type: application/json'
          -H 'idempotency: your-idempotency-parameter-here'
          -H 'salt: your-random-string-here'
          -H 'signature: your-calculated-signature-here'
          -H 'timestamp: your-unix-timestamp-here'
          -d '{
              "amount": 1050,
              "currency": "USD",
              "payment_method": {
                  "type": "is_visa_card",
                  "fields": {
                      "number": "4111111111111111",
                      "expiration_month": "12",
                      "expiration_year": "25",
                      "cvv": "789",
                      "name": "John Doe"
                  }
              },
              "capture": true
          }'

    The platform returns the following response and the PAYMENT_SUCCEEDED webhook, which has the same content:

      • Response

        • {
              "status": {
                  "error_code": "",
                  "status": "SUCCESS",
                  "message": "",
                  "response_code": "",
                  "operation_id": "3c7d66c1-29f2-4ade-8d52-7257e7ae353c"
              },
              "data": {
                  "id": "payment_b050cb27b65c3d7b742e59e0f68d059c",
                  "amount": 0,
                  "original_amount": 1050,
                  "is_partial": false,
                  "currency_code": "USD",
                  "country_code": "IS",
                  "status": "ACT",
                  "description": "",
                  "merchant_reference_id": "",
                  "customer_token": "cus_ed5296d1eea780f310cfecbf37a88c63",
                  "payment_method": null,
                  "payment_method_data": {
                      "id": null,
                      "type": "is_visa_card",
                      "category": "card",
                      "metadata": null,
                      "image": "",
                      "webhook_url": "",
                      "supporting_documentation": "",
                      "next_action": "3d_verification",
                      "name": "John Doe",
                      "last4": "1111",
                      "acs_check": "unchecked",
                      "cvv_check": "unchecked",
                      "bin_details": {
                          "type": "DEBIT",
                          "brand": "VISA",
                          "level": "CLASSIC",
                          "issuer": "CONOTOXIA SP. Z O.O",
                          "country": "PL",
                          "bin_number": "411111"
                      },
                      "expiration_year": "25",
                      "expiration_month": "12",
                      "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467",
                      "payment_account_reference": "V001R9YSPI6WE4AHTSTYFLXHQMHJJ",
                      "network_reference_id": "938151"
                  },
                  "auth_code": null,
                  "expiration": 1751298192,
                  "captured": true,
                  "refunded": false,
                  "refunded_amount": 0,
                  "receipt_email": "",
                  "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_b050cb27b65c3d7b742e59e0f68d059c",
                  "complete_payment_url": "",
                  "error_payment_url": "",
                  "receipt_number": "",
                  "flow_type": "",
                  "address": null,
                  "statement_descriptor": "Doc Team",
                  "transaction_id": "",
                  "created_at": 1750693392,
                  "metadata": {},
                  "failure_code": "",
                  "failure_message": "",
                  "paid": false,
                  "paid_at": 0,
                  "dispute": null,
                  "refunds": null,
                  "order": null,
                  "outcome": null,
                  "visual_codes": {},
                  "textual_codes": {},
                  "instructions": [
                      {
                          "name": "instructions",
                          "steps": [
                              {
                                  "step1": ""
                              }
                          ]
                      }
                  ],
                  "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
                  "ewallets": [
                      {
                          "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
                          "amount": 1050,
                          "percent": 100,
                          "refunded_amount": 0
                      }
                  ],
                  "payment_method_options": {
                      "3d_required": true
                  },
                  "payment_method_type": "is_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": "3d_verification",
                  "error_code": "",
                  "remitter_information": {},
                  "save_payment_method": false,
                  "merchant_advice_code": null,
                  "merchant_advice_message": null,
                  "authentication_result": {
                      "eci": null,
                      "result": "R",
                      "version": "2.2.0",
                      "cardholder_info": null
                  },
                  "transaction_link_id": null
              }
          }

    Note 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.

  2. Paste the redirect URL into the address bar of your browser.

    The Rapyd 3DS Simulator page appears.

    3ds.png
  3. Type 123456, then click Continue.

    The platform returns the PAYMENT_COMPLETED webhook.

      • Webhook

        • {
            "id": "wh_e97f2239ed679bbfd3d9ad879d72c98c",
            "type": "PAYMENT_COMPLETED",
            "data": {
              "id": "payment_27431c499e6c82b24f83ec588963d726",
              "mid": "",
              "paid": true,
              "order": null,
              "amount": 1053,
              "escrow": null,
              "status": "CLO",
              "address": null,
              "dispute": null,
              "fx_rate": 1,
              "invoice": "",
              "outcome": null,
              "paid_at": 1750841566,
              "refunds": null,
              "captured": true,
              "ewallets": [
                {
                  "amount": 1053,
                  "percent": 100,
                  "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
                  "refunded_amount": 0
                }
              ],
              "metadata": {},
              "refunded": false,
              "auth_code": null,
              "flow_type": "",
              "created_at": 1750841516,
              "error_code": "",
              "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861",
              "expiration": 1751446316,
              "fixed_side": "",
              "is_partial": false,
              "description": "",
              "next_action": "not_applicable",
              "country_code": "IS",
              "failure_code": "",
              "instructions": [
                {
                  "name": "instructions",
                  "steps": [
                    {
                      "step1": ""
                    }
                  ]
                }
              ],
              "payment_fees": null,
              "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_27431c499e6c82b24f83ec588963d726",
              "visual_codes": {},
              "cancel_reason": null,
              "currency_code": "USD",
              "group_payment": "",
              "receipt_email": "",
              "textual_codes": {},
              "customer_token": "cus_fb08bee976325bb212225931843e4508",
              "payment_method": null,
              "receipt_number": "",
              "transaction_id": "",
              "failure_message": "",
              "initiation_type": "customer_present",
              "original_amount": 1053,
              "refunded_amount": 0,
              "error_payment_url": "",
              "payment_method_data": {
                "id": null,
                "name": "John Doe",
                "type": "is_visa_card",
                "image": "",
                "last4": "1111",
                "category": "card",
                "metadata": null,
                "acs_check": "pass",
                "cvv_check": "unchecked",
                "bin_details": {
                  "type": "DEBIT",
                  "brand": "VISA",
                  "level": "CLASSIC",
                  "issuer": "CONOTOXIA SP. Z O.O",
                  "country": "PL",
                  "bin_number": "411111"
                },
                "next_action": "not_applicable",
                "webhook_url": "",
                "expiration_year": "25",
                "expiration_month": "12",
                "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467",
                "network_reference_id": "186036",
                "supporting_documentation": "",
                "payment_account_reference": "V001AN5956F1GYR4XNN2CEKD1JVYA"
              },
              "payment_method_type": "is_visa_card",
              "save_payment_method": false,
              "transaction_link_id": null,
              "complete_payment_url": "",
              "merchant_advice_code": null,
              "remitter_information": {},
              "statement_descriptor": "Doc Team",
              "authentication_result": {
                "eci": "05",
                "result": "A",
                "version": "2.2.0",
                "cardholder_info": null
              },
              "merchant_reference_id": "",
              "payment_method_options": {
                "3d_required": true
              },
              "merchant_advice_message": null,
              "merchant_requested_amount": null,
              "merchant_requested_currency": null,
              "payment_method_type_category": "card"
            },
            "trigger_operation_id": "b37b08b6-f755-4a2f-b18e-8a218363d7ee",
            "status": "NEW",
            "created_at": 1750841566,
            "extended_timestamp": 1750841566883
          }

    Note that the status has changed to CLO (closed).