Skip to main content
POST
/
v2
/
payment-orders
/
{id}
/
payer-authentication
Initiate 3DS payer authentication
curl --request POST \
  --url http://localhost:3156/v2/payment-orders/{id}/payer-authentication \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-merchant-id: <api-key>' \
  --data '
{
  "deviceInformation": {
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0",
    "userAgentBrowserValue": "Chrome/120.0",
    "httpAcceptBrowserValue": "text/html,application/xhtml+xml",
    "httpBrowserLanguage": "en-US",
    "httpBrowserJavaScriptEnabled": true,
    "httpBrowserScreenWidth": "1920",
    "httpBrowserScreenHeight": "1080"
  },
  "collectionReferenceId": "col_123456789",
  "returnUrl": "https://example.com/return"
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "ORDER-123",
  "status": "PAYER_AUTHENTICATION_CHALLENGE_REQUIRED",
  "amount": 250,
  "currency": "MXN",
  "payerAuthentication": {
    "id": "payer-auth-123",
    "url": "https://bank.example.com/authenticate",
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication (required)

​
x-merchant-id
string
header
required

Merchant ID for identifying the merchant (required)

Path Parameters

​
id
string<uuid>
required

Payment order ID

Body

application/json
​
deviceInformation
object
required
​
collectionReferenceId
string
required

Reference ID for the device data collection

Example:

"col_123456789"

​
returnUrl
string<uri-reference>
required

URL to redirect the user after authentication

Example:

"https://example.com/return"

Response

Payer authentication initiated successfully

​
id
string<uuid>
required

Payment order ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
status
enum<string>
required

Payment order status (typically PAYER_AUTHENTICATION_CHALLENGE_REQUIRED after this call)

Available options:
PENDING,
PROCESSING,
AUTHORIZED,
PARTIALLY_AUTHORIZED,
ACTION_REQUIRED,
PAYER_AUTHENTICATION_CHALLENGE_REQUIRED,
COMPLETED,
PARTIALLY_PAID,
CANCELLATION_REQUESTED,
CANCELLED,
FAILED,
REFUND_PROCESSING,
PARTIALLY_REFUNDED,
REFUNDED
Example:

"PAYER_AUTHENTICATION_CHALLENGE_REQUIRED"

​
externalId
string

External payment order ID

Example:

"ORDER-123"

​
amount
number

Payment amount

Example:

250

​
currency
string

Currency code

Example:

"MXN"

​
customer
object

Customer details

​
payerAuthentication
object

3DS authentication details