3DS

Initiate a 3-D Secure 2.x session for a card payment. This is the first step in any card flow that requires strong customer authentication. The endpoint returns a reference_id that must be attached to the subsequent Create Payment request.

When to Use

  • Before creating a card payment when your acquiring region (e.g. EEA / UK) or issuer mandates 3DS 2.x
  • Before any card transaction where you want the liability shift that 3DS provides
  • Whenever your risk model requests strong customer authentication for a high-value transaction
  • When your frontend needs a device fingerprint collection snippet for a compliant authentication flow

You do not need to call this endpoint when:

  • The payment method is a wallet (BINANCE_PAY, ALIPAY_PLUS_PAY) — those have their own authentication
  • You are using a server-to-server token that has already been 3DS-authenticated upstream

Endpoint

POST https://api.sandbox.build.app/api/v1/acq/3ds/setup

Integration Flow

3DS Integration Flow

Numbered steps

  1. Your backend calls POST /3ds/setup with the card and amount.
  2. Build returns a reference_id (used to correlate the 3DS session) and a data_collection_info blob.
  3. Your frontend executes the device fingerprint collection using data_collection_info.
  4. Your backend calls POST /payment with payment_type=AUTH / DEBIT and the reference_id in three_ds_info.
  5. If the payment responds with next_action.type=3DS, redirect the cardholder to verify_url to complete the challenge.
  6. After receiving the 3DS authentication completion notification, resume the payment by calling POST /payment again with the reference_id and payment_id.

Best Practices

  • Always pass merchant_request_id. It is your idempotency key; retries with the same value return the first response within the 24-hour window.
  • Collect browser data accurately. Frictionless authentication depends heavily on complete device_info. Missing fields (screen size, language, IP) lower your frictionless rate.
  • Pass full billing details (address + email). Issuers often downgrade to challenge if AVS fields are sparse.
  • Do not cache reference_id. It is bound to a single cardholder session.
  • Time-box the flow. If the cardholder has not completed Step 2 (device fingerprint) within ~10 seconds, you can proceed with a payment call.

FAQ

Q: Is 3DS mandatory for all card payments? A: No. It depends on your acquiring region, issuer requirements, and your risk policy. Build does not enforce 3DS by default — you decide when to call /3ds/setup.

Q: What happens if I skip /3ds/setup and call /payment directly? A: The payment may succeed (for non-3DS regions) or it may be declined with REQUIRES_ACTION. In the latter case, restart with /3ds/setup.

Q: Can I reuse a reference_id for multiple payments? A: No. Each reference_id is tied to one cardholder session and one intended payment amount.

Q: Frictionless vs Challenge — how do I know which path the cardholder will take? A: You don't know ahead of time. Always implement the challenge redirect logic (next_action.type=3DS). If the response comes back without next_action, the payment was authorized frictionlessly.

Q: The cardholder completes the challenge but my payment is still pending. What should I do? A: After receiving the 3DS authentication completion notification, resume the payment by calling POST /payment again with the reference_id and payment_id.

Next Steps