Skip to main content

Documentation

Creating a Card Payment With 3DS Authentication - External 3DS

This procedure describes how to create a card payment that uses an external provider for 3DS authentication. This procedure is relevant to the production environment.

Note

  • To enable this feature, contact Rapyd Client Support.

  • This option currently is not available for hosted pages.

  • The card issuer might require 3DS even when it is not specified in the payment request.

Related Information

Prerequisites

  • Keys to the production environment for your user.

  • A payment method that supports 3DS authentication by external provider. The response to Get Payment Method Required Fields must include the following fields:

    • payment_method_options.3d_required - 3DS is supported.

    • 3d_version

    • cavv

    • eci

    • ds_trans_id

  • The following information from your external 3DS provider:

    • 3d_version - 3DS version.

    • cavv - Cardholder authentication verification value (CAVV) represented as a 20-byte value that is Base64 encoded.

    • eci - Electronic commerce indicator (ECI) from MPI Plugin (3-D Secure 1.0) or 3DS Server (3-D Secure 2.0).

    • ds_trans_id - The directory server transaction ID. Required for Mastercard 2.0.

How
  1. Create a payment as described in Create Payment, with the following settings:

    • payment_method - Specify one of the following:

      • The ID of the customer's payment method.

      • A 'payment method' object that contains all required fields.

    • payment_method_options - Specify an object that contains the fields listed in the prerequisites.

      • Request

        • curl -X post
          https://api.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": 10,
              "currency": "EUR",
              "capture": false,
              "description": "payment by card",
              "customer": "cus_5bee14584a78638ba717e746be62ee01",
              "payment_method": {
                  "type": "is_visa_card",
                  "fields": {
                      "name": "John Doe",
                      "number": "4111111111111111",
                      "expiration_month": "05",
                      "expiration_year": "31",
                      "cvv": "111"
                  }
              },
              "payment_method_options": {
                  "3d_version": "2.2.0",
                  "cavv": "BwABBYcyOCdlg0QChDI4EHUURgE",
                  "eci": "05",       
                  "ds_trans_id": "1b20b229-8676-5812-8000-000000617fbb"
              },
              "save_payment_method": true,
              "complete_payment_url": "https://complete.rapyd.net",
              "error_payment_url": "https://error.rapyd.net"
          }'
      • Response

        • {
              "status": {
                  "error_code": "",
                  "status": "SUCCESS",
                  "message": "",
                  "response_code": "",
                  "operation_id": "137f1eac-d498-4203-b901-d836abfadadf"
              },
              "data": {
                  "id": "payment_e05ad752b2d547b2a454b972038e9536",
                  "amount": 0,
                  "original_amount": 10,
                  "is_partial": false,
                  "currency_code": "EUR",
                  "country_code": "IS",
                  "status": "ACT",
                  "description": "payment by card",
                  "merchant_reference_id": "",
                  "customer_token": "cus_5bee14584a78638ba717e746be62ee01",
                  "payment_method": "card_bc43dabab72ca676a8bb237c03969b62",
                  "payment_method_data": {
                      "id": "card_bc43dabab72ca676a8bb237c03969b62",
                      "type": "is_visa_card",
                      "category": "card",
                      "metadata": null,
                      "image": "",
                      "webhook_url": "",
                      "supporting_documentation": "",
                      "next_action": "not_applicable",
                      "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": "31",
                      "expiration_month": "05",
                      "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467",
                      "network_reference_id": "123456"
                  },
                  "auth_code": null,
                  "expiration": 1751295440,
                  "captured": false,
                  "refunded": false,
                  "refunded_amount": 0,
                  "receipt_email": "",
                  "redirect_url": "",
                  "complete_payment_url": "https://complete.rapyd.net",
                  "error_payment_url": "https://error.rapyd.net",
                  "receipt_number": "",
                  "flow_type": "",
                  "address": null,
                  "statement_descriptor": "Doc Team",
                  "transaction_id": "",
                  "created_at": 1750690640,
                  "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": 10,
                          "percent": 100,
                          "refunded_amount": 0
                      }
                  ],
                  "payment_method_options": {
                      "eci": "05",
                      "cavv": "BwABBYcyOCdlg0QChDI4EHUURgE",
                      "3d_version": "2.2.0",
                      "ds_trans_id": "1b20b229-8676-5812-8000-000000617fbb"
                  },
                  "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": "pending_capture",
                  "error_code": "",
                  "remitter_information": {},
                  "save_payment_method": true,
                  "merchant_advice_code": null,
                  "merchant_advice_message": null,
                  "transaction_link_id": null
              }
          }
  2. The external 3DS provider authenticates the buyer.

  3. Rapyd completes the payment.