Skip to main content
POST
/
api
/
v1
/
server-to-server-interface
/
paymentv2
3D Secure Payment API
curl --request POST \
  --url https://api-dev.paymentoptions.com/api/v1/server-to-server-interface/paymentv2 \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": "1000",
  "currency": "JPY",
  "card": {
    "cvc": "100",
    "expiry_month": "12",
    "expiry_year": "29",
    "name": "John Doe",
    "number": "4000002500003155"
  },
  "merchant_txn_ref": "qwe",
  "customer_ip": "127.0.0.1",
  "merchant_id": "< Merchant ID >",
  "billing_address": {
    "country": "JP",
    "email": "[email protected]",
    "phone_number": "8112345678",
    "address1": "1-2-3 Shinjuku",
    "city": "Shinjuku-ku",
    "state": "Tokyo",
    "postal_code": "1600022"
  },
  "return_url": {
    "webhook_url": "< Webhook url >",
    "success_url": "http://www.successurl.com/",
    "decline_url": "http://www.declineurl.com/"
  },
  "shipping_address": {
    "country": "JP",
    "email": "[email protected]",
    "phone_number": "8112345678",
    "address1": "1-2-3 Shinjuku",
    "city": "Shinjuku-ku",
    "state": "Tokyo",
    "postal_code": "1600022"
  },
  "browser_info": {
    "acceptHeader": "text/html",
    "screenColorDepth": "48",
    "javaEnabled": false,
    "language": "en",
    "screenHeight": "1200",
    "screenWidth": "1600",
    "challengeWindow": "4",
    "userAgent": "Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)"
  },
  "time_zone": "Asia/Kuala_Lumpur"
}
'
{
  "url": "https://checkout-dev.paymentoptions.com/integration/3ds?_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmMmIwMWRhZi1lMWI2LTRlMTYtOGJlOC1hN2YwNTQ1NmQyNWEiLCJpYXQiOjE3Mzc5NTI0MTIsImlzcyI6IjYwMzc4ZjcxNGEwZTg5MTZlMDQ1YjQzOCIsIk9yZ1VuaXRJZCI6IjYwMzc4ZjcxZDk2ODQzM2UyMmIxZTY5NCIsImV4cCI6MTczNzk1NDIxMn0.ytizEgQCt_hQEPn3mdJMAaKjP0L68WiGYkOzD_nHeWI&_c=400000&_a=YXNpYWJpbGw=",
  "statusCode": 200,
  "success": true,
  "redirect_url": "https://checkout-dev.paymentoptions.com/integration/3ds?_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmMmIwMWRhZi1lMWI2LTRlMTYtOGJlOC1hN2YwNTQ1NmQyNWEiLCJpYXQiOjE3Mzc5NTI0MTIsImlzcyI6IjYwMzc4ZjcxNGEwZTg5MTZlMDQ1YjQzOCIsIk9yZ1VuaXRJZCI6IjYwMzc4ZjcxZDk2ODQzM2UyMmIxZTY5NCIsImV4cCI6MTczNzk1NDIxMn0.ytizEgQCt_hQEPn3mdJMAaKjP0L68WiGYkOzD_nHeWI&_c=400000&_a=YXNpYWJpbGw="
}

​
Integration Steps

​
Step 1: Send a 3D Request

To initiate the 3D Secure authentication, send a server-to-server request to the 3D Secure endpoint.

​
Step 2: Use the Redirect URL

Use the redirect_url from the response to open the 3D Secure page in the browser.

​
Step 3: After Completing the 3D Secure Authentication

After the cardholder completes the authentication, the issuer will approve or reject the request. Based on the outcome, the customer will be redirected to either a success_url or a decline_url that you provide.

success_url

Redirects the customer to the specified page if the 3DS authentication is successful.

decline_url

Redirects the customer if the authentication is declined or fails.

​
Step 4: Webhook Notification

In addition to the redirect response, the gateway will send a Webhook notification to your specified webhook_url to confirm the status of the transaction. This ensures the transaction result is reliably communicated, even if the customer does not return to your website after the 3DS process.

​
Webhook Sample Response

{
  "success": true,
  "status_code": 200,
  "is_live": false,
  "transaction_type": "CAPTURE",
  "gateway_response": {
    "version": "1",
    "type": "INFO",
    "message": "Payment Successful.",
    "code": "INFO0000"
  },
  "merchant_details": {
    "legal_name": "<merchant name>",
    "mid": "DASMID",
    "merchant_txn_ref": "<merchant_txn_ref>"
  },
  "payment_details": {
    "amount": <amount>,
    "response_code": 0,
    "auth_code": null,
    "currency": "<currency>",
    "payment_method": "",
    "scheme": "VISA",
    "card": {
      "name": "<cardholder’s name>",
      "number": "<card number>",
      "exp_month": "MM",
      "exp_year": "YY"
    },
    "additional_data": {
      "payment_data_source": {
        "type": "card"
      }
    }
  },
  "transaction_details": {
    "id": "<transaction ref Id>",
    "ref": <ref>,
    "timestamp": "YYYY-MM-DDTHH:MM:SS.000Z",
    "merchant_txn_ref": "<merchant_txn_ref>"
  },
  "risk-details": {}
}

​
Step 5: Get the 3D Secure Transaction status

​
Request Attributes


curl --location '<base_URL>/api/v1/server-to-server-interface/transaction/status/<Transaction Ref ID>' \
--header 'Authorization: Basic <API Key>' \
--header 'x-api-key: <x-api-key>' \
--header 'Content-Type: application/json'

​
Response Attributes

{
    "success": true,
    "status_code": 200,
    "is_live": false,
    "transaction_type": "CAPTURE",
    "gateway_response": {
        "version": "1",
        "type": "INFO",
        "message": "Payment Successful.",
        "code": "INFO0000"
    },
    "merchant_details": {
        "legal_name": "<merchant name>",
        "mid": "<DASMID>",
        "merchant_txn_ref": "<merchant_txn_ref>"
    },
    "payment_details": {
        "amount": <amount>,
        "response_code": 0,
        "responseDescription": "The transaction was completed successfully.",
        "auth_code": null,
        "currency": "<currency>",
        "payment_method": null,
        "scheme": "<scheme>",
        "card": {
            "name": "<cardholder name>",
            "number": "<card_number>",
            "exp_month": "MM",
            "exp_year": "YY"
        },
        "additional_data": {
            "payment_data_source": {
                "type": "card"
            }
        }
    },
    "transaction_details": {
        "id": "<Transaction Ref Id>",
        "ref": <ref>,
        "timestamp": "YYYY-MM-DDTHH:MM:SS.000Z",
        "billing_details": {
            "billing_address": {
                "country": "<country code>",
                "email": "<email>",
                "address1": "<address1>",
                "phone_number": "<phone_number>",
                "city": "<city>",
                "state": "<state>",
                "postal_code": "<postal_code>"
            },
            "shipping_address": {
                "country": "<country code>",
                "email": "<email>",
                "address1": "<address1>",
                "phone_number": "<phone_number>",
                "city": "<city>",
                "state": "<state>",
                "postal_code": "<postal_code>"
            }
        }
    },
    "risk_details": {
        "risk_score": null
    }
}

​
Request Attributes

Authorizations

​
Authorization
string
header
required

API Key for Authorization. Format: 'Basic YOUR_API_KEY_HERE'

​
x-api-key
string
header
required

API Key specific to x-api-key.

Body

application/json

The request payload to process a 3D Secure payment transaction.

​
amount
string
required

The amount of the transaction.

Example:

"1000"

​
currency
string
required

The abbreviation of the processing currency of the product (e.g., JPY).

Maximum string length: 3
Example:

"JPY"

​
card
object
required

A JSON object containing the Card Details.

​
merchant_txn_ref
string
required

The merchant transaction reference ID.

Maximum string length: 45
Example:

"qwe"

​
customer_ip
string
required

The IP address of the cardholder.

Maximum string length: 45
Example:

"127.0.0.1"

​
merchant_id
string
required

The merchant ID (DASMID).

Maximum string length: 128
Example:

"< Merchant ID >"

​
billing_address
object
required

A JSON object containing the billing address of the cardholder.

​
return_url
object

A JSON object containing the Return URL. (This field is mandatory for 3DS transactions.)

​
shipping_address
object

A JSON object containing the shipping address of the cardholder (optional).

​
browser_info
object

A JSON object containing details about the browser used by the cardholder (optional).

​
time_zone
string

The country time zone of the transaction.

Maximum string length: 128
Example:

"Asia/Kuala_Lumpur"

Response

200 - application/json

3D Secure transaction initiated successfully

​
url
string

The URL for the 3D Secure authentication page.

Example:

"https://checkout-dev.paymentoptions.com/integration/3ds?_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmMmIwMWRhZi1lMWI2LTRlMTYtOGJlOC1hN2YwNTQ1NmQyNWEiLCJpYXQiOjE3Mzc5NTI0MTIsImlzcyI6IjYwMzc4ZjcxNGEwZTg5MTZlMDQ1YjQzOCIsIk9yZ1VuaXRJZCI6IjYwMzc4ZjcxZDk2ODQzM2UyMmIxZTY5NCIsImV4cCI6MTczNzk1NDIxMn0.ytizEgQCt_hQEPn3mdJMAaKjP0L68WiGYkOzD_nHeWI&_c=400000&_a=YXNpYWJpbGw="

​
statusCode
integer

The response status code.

Example:

200

​
success
boolean

Indicates if the transaction was successful.

Example:

true

​
redirect_url
string

The redirect URL for the 3D Secure authentication.

Example:

"https://checkout-dev.paymentoptions.com/integration/3ds?_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmMmIwMWRhZi1lMWI2LTRlMTYtOGJlOC1hN2YwNTQ1NmQyNWEiLCJpYXQiOjE3Mzc5NTI0MTIsImlzcyI6IjYwMzc4ZjcxNGEwZTg5MTZlMDQ1YjQzOCIsIk9yZ1VuaXRJZCI6IjYwMzc4ZjcxZDk2ODQzM2UyMmIxZTY5NCIsImV4cCI6MTczNzk1NDIxMn0.ytizEgQCt_hQEPn3mdJMAaKjP0L68WiGYkOzD_nHeWI&_c=400000&_a=YXNpYWJpbGw="