3DS Authentication

3DS changes the payment flow from a simple confirm into a confirm-plus-customer-action flow.

3DS Flow

Controls in the Payment API

The payment creation request supports these 3DS-related fields:

• authentication_type -- set to "three_ds" to request 3DS, or "no_three_ds" to skip
• request_external_three_ds_authentication -- for external 3DS authentication providers

Common values for authentication_type:

• no_three_ds
• three_ds

Creating a Payment with 3DS

POST /payments

curl https://sandbox.perfectpay.ai/payments \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": "USD",
    "authentication_type": "three_ds",
    "return_url": "https://example.com/checkout/complete",
    "confirm": false
  }'

What Happens at Runtime

If 3DS is required, the payment moves to requires_customer_action after confirmation and the response carries a next_action value such as:

• redirect_to_url
• three_ds_invoke

Your integration should:

1. Preserve the current payment_id and client_secret
2. Let the SDK or the browser complete the 3DS step
3. Retrieve the final status after the redirect returns

Recommended Pattern

Use the Web SDK for browser-based checkout so the SDK can manage redirects, wallet handoffs, and post-auth retrieval for you.

Direct API Confirmations

If you confirm directly from the server, send:

• api-key: YOUR_SECRET_API_KEY
• browser_info when your processor or region requires it

curl https://sandbox.perfectpay.ai/payments/pay_mbabizu24mvu3mela5njyhpit4/confirm \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
      "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "10",
        "card_exp_year": "25",
        "card_cvc": "123",
        "card_holder_name": "Jane Doe"
      }
    }
  }'

Operational Notes

• Expect requires_customer_action before success on regulated or issuer-step-up traffic
• Keep the return_url stable across retries
• Do not treat processing as a failure after a 3DS step