> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paymentoptions.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 3D Secure Integration
> Comprehensive guide to integrating 3D Secure authentication for enhanced transaction security.
## **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.
Redirects the customer to the specified page if the 3DS authentication is successful. 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**
```json theme={null}
{
"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": "",
"mid": "DASMID",
"merchant_txn_ref": ""
},
"payment_details": {
"amount": ,
"response_code": 0,
"auth_code": null,
"currency": "",
"payment_method": "",
"scheme": "VISA",
"card": {
"name": "",
"number": "",
"exp_month": "MM",
"exp_year": "YY"
},
"additional_data": {
"payment_data_source": {
"type": "card"
}
}
},
"transaction_details": {
"id": "",
"ref": [,
"timestamp": "YYYY-MM-DDTHH:MM:SS.000Z",
"merchant_txn_ref": ""
},
"risk-details": {}
}
```
***
### **Step 5: Get the 3D Secure Transaction status**
#### **Request Attributes**
```curl theme={null}
curl --location '/api/v1/server-to-server-interface/transaction/status/' \
--header 'Authorization: Basic ' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json'
```
#### **Response Attributes**
```json theme={null}
{
"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": "",
"mid": "",
"merchant_txn_ref": ""
},
"payment_details": {
"amount": ,
"response_code": 0,
"responseDescription": "The transaction was completed successfully.",
"auth_code": null,
"currency": "",
"payment_method": null,
"scheme": "",
"card": {
"name": "",
"number": "",
"exp_month": "MM",
"exp_year": "YY"
},
"additional_data": {
"payment_data_source": {
"type": "card"
}
}
},
"transaction_details": {
"id": "",
"ref": ][,
"timestamp": "YYYY-MM-DDTHH:MM:SS.000Z",
"billing_details": {
"billing_address": {
"country": "",
"email": "",
"address1": "",
"phone_number": "",
"city": "",
"state": "",
"postal_code": ""
},
"shipping_address": {
"country": "",
"email": "",
"address1": "",
"phone_number": "",
"city": "",
"state": "",
"postal_code": ""
}
}
},
"risk_details": {
"risk_score": null
}
}
```
***
## Request Attributes
## OpenAPI
````yaml /api-reference/en/open-api-config/server-to-server/purchase.json POST /api/v1/server-to-server-interface/paymentv2
openapi: 3.0.1
info:
title: Payment Options API
description: API for generating Hosted Payment Page (HPP) links and processing payments.
version: 1.0.0
servers:
- url: https://api-dev.paymentoptions.com
security:
- apiKeyAuth: []
xApiKeyAuth: []
paths:
/api/v1/server-to-server-interface/paymentv2:
post:
summary: 3D Secure Payment API
description: Initiates a 3D Secure payment transaction.
operationId: process3DSecurePayment
requestBody:
description: The request payload to process a 3D Secure payment transaction.
required: true
content:
application/json:
schema:
type: object
properties:
amount:
type: string
description: The amount of the transaction.
example: '1000'
currency:
type: string
description: >-
The abbreviation of the processing currency of the product
(e.g., JPY).
example: JPY
maxLength: 3
card:
type: object
additionalProperties: false
description: A JSON object containing the Card Details.
properties:
cvc:
type: string
description: >-
The Security Code of the card (3 digits for most, 4
digits for AMEX).
example: '100'
maxLength: 4
expiry_month:
type: string
description: The expiry month of the card (e.g., 12 for December).
example: '12'
maxLength: 2
expiry_year:
type: string
description: The expiry year of the card (e.g., 29 or 2029 for 2029).
example: '29'
maxLength: 4
name:
type: string
description: The cardholder’s name on the card.
example: John Doe
maxLength: 255
number:
type: string
description: The card number.
example: '4000002500003155'
maxLength: 16
merchant_txn_ref:
type: string
description: The merchant transaction reference ID.
example: qwe
maxLength: 45
customer_ip:
type: string
description: The IP address of the cardholder.
example: 127.0.0.1
maxLength: 45
merchant_id:
type: string
description: The merchant ID (DASMID).
example: < Merchant ID >
maxLength: 128
return_url:
type: object
additionalProperties: false
description: >-
A JSON object containing the Return URL. (This field is
mandatory for 3DS transactions.)
properties:
webhook_url:
type: string
description: The webhook URL link.
example: < Webhook url >
maxLength: 255
success_url:
type: string
description: The redirect URL after successful payment.
example: http://www.successurl.com/
maxLength: 255
decline_url:
type: string
description: The redirect URL after failed payment.
example: http://www.declineurl.com/
maxLength: 255
billing_address:
type: object
additionalProperties: false
description: >-
A JSON object containing the billing address of the
cardholder.
properties:
country:
type: string
description: The cardholder’s billing country code.
example: JP
maxLength: 2
email:
type: string
description: The cardholder’s billing email address.
example: billing@testemail.com
maxLength: 45
phone_number:
type: string
description: The cardholder’s billing phone number.
example: '8112345678'
maxLength: 20
address1:
type: string
description: The cardholder’s billing address line.
example: 1-2-3 Shinjuku
maxLength: 199
city:
type: string
description: The cardholder’s billing city.
example: Shinjuku-ku
maxLength: 65
state:
type: string
description: The cardholder’s billing state.
example: Tokyo
maxLength: 65
postal_code:
type: string
description: The cardholder’s billing postal code.
example: '1600022'
maxLength: 45
shipping_address:
type: object
additionalProperties: false
description: >-
A JSON object containing the shipping address of the
cardholder (optional).
properties:
country:
type: string
description: The cardholder’s shipping country code.
example: JP
maxLength: 2
email:
type: string
description: The cardholder’s shipping email address.
example: shipping@testemail.com
maxLength: 45
phone_number:
type: string
description: The cardholder’s shipping phone number.
example: '8112345678'
maxLength: 20
address1:
type: string
description: The cardholder’s shipping address line.
example: 1-2-3 Shinjuku
maxLength: 199
city:
type: string
description: The cardholder’s shipping city.
example: Shinjuku-ku
maxLength: 65
state:
type: string
description: The cardholder’s shipping state.
example: Tokyo
maxLength: 65
postal_code:
type: string
description: The cardholder’s shipping postal code.
example: '1600022'
maxLength: 45
browser_info:
type: object
additionalProperties: false
description: >-
A JSON object containing details about the browser used by
the cardholder (optional).
properties:
acceptHeader:
type: string
description: The value of the HTTP Accept header sent by the browser.
example: text/html
maxLength: 200
screenColorDepth:
type: string
description: The color depth of the screen in bits per pixel.
example: '48'
maxLength: 2
javaEnabled:
type: boolean
description: Indicates whether Java is enabled in the browser.
example: false
language:
type: string
description: >-
The language of the browser, typically the language set
in the browser settings.
example: en
maxLength: 10
screenHeight:
type: string
description: The height of the screen in pixels.
example: '1200'
maxLength: 5
screenWidth:
type: string
description: The width of the screen in pixels.
example: '1600'
maxLength: 5
challengeWindow:
type: string
description: >-
The size of the challenge window that the cardholder's
browser supports.
example: '4'
maxLength: 2
userAgent:
type: string
description: The User-Agent string of the browser.
example: Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)
maxLength: 500
time_zone:
type: string
description: The country time zone of the transaction.
example: Asia/Kuala_Lumpur
maxLength: 128
required:
- amount
- currency
- card
- merchant_txn_ref
- customer_ip
- merchant_id
- billing_address
responses:
'200':
description: 3D Secure transaction initiated successfully
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: 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:
type: integer
description: The response status code.
example: 200
success:
type: boolean
description: Indicates if the transaction was successful.
example: true
redirect_url:
type: string
description: 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=
components:
securitySchemes:
apiKeyAuth:
type: apiKey
name: Authorization
in: header
description: 'API Key for Authorization. Format: ''Basic YOUR_API_KEY_HERE'''
xApiKeyAuth:
type: apiKey
name: x-api-key
in: header
description: API Key specific to x-api-key.
````]