Create Payment

Create a Payment — the primary endpoint for charging a customer. One endpoint serves two modes:

  • payment_type=DEBIT — immediate charge (funds captured right away)
  • payment_type=AUTH — pre-authorization (funds held; capture later via Capture Payment)

This endpoint also unifies multiple payment methods: cards (with optional 3DS), wallets (Binance Pay, Alipay+), and tokens (one-time tokens produced by your frontend SDK).

When to Use

  • Charging a customer for a purchase (DEBIT)
  • Reserving funds before fulfilment (AUTH + later Capture)
  • Resuming a paused 3DS challenge (pass three_ds_info.paused_payment_id)
  • Creating a wallet / QR-based payment (Binance Pay, Alipay+)

Endpoint

POST https://api.sandbox.build.app/api/v1/acq/payment

Integration Flow

Card payment with 3DS (full flow)

3DS Card Payment Flow

Wallet / QR payment (Binance Pay, Alipay+)

Wallet Payment Flow

Simple card payment (no 3DS)

Card Payment without 3DS

State Transitions

Payment Status

Best Practices

  • merchant_request_id is sacred. Always generate one per intended payment. Mismatched payloads with the same ID return IDEM_REQ_PARAMS_CHANGED.
  • Always implement a next_action handler. Even if you think the flow is frictionless, some jurisdictions / issuers force 3DS. Your code must redirect or render QR when told.
  • Use AUTH + Capture for anything involving fulfilment. It lets you charge only when you ship, reducing refunds.
  • Respect expire_time. For wallet / QR flows, the entrance URL has a limited lifetime. Show a countdown or offer a refresh action.
  • Reconcile via webhooks, not polling. Treat DEBIT webhook as the source of truth.
  • Pass accurate billing for card payments. AVS / 3DS frictionless rates depend heavily on address and email. Sparse billing data means more challenges.
  • Validate success_url / cancel_url / error_url. Use HTTPS. Invalid URLs break the post-payment redirect.

FAQ

Q: Can I charge the cardholder without 3DS? A: Depends on the issuer / region. In many regions you can, but the liability for fraud remains on you. Consult your acquiring agreement.

Q: What is the difference between DEBIT and AUTH? A: DEBIT charges immediately — funds leave the customer at authorization time. AUTH places a hold; you must call /capture later to actually take the money, or /cancel to release the hold. Use AUTH whenever there is a fulfilment step.

Q: Can I combine 3DS with DEBIT? A: Yes. 3DS works with both DEBIT and AUTH. The flow is the same: /3ds/setup → /payment.

Q: What does next_action.type=PAYMENT_ENTRANCE mean? A: The payment requires the customer to complete the flow in an external app or QR scan (typical of wallets like Binance Pay and Alipay+). Render the QR / deeplink / redirect to checkout_url and wait for the webhook.

Q: The payment response does not include next_action. Is the payment done? A: Yes. An absent next_action means the payment reached a terminal state for this API call. Check payment_status: SUCCEEDED means success.

Q: My 3DS challenge redirect completed, but the cardholder bounced back and my payment is still REQUIRES_ACTION. What now? A: Resume the payment by calling POST /payment again with the same merchant_request_id and adding three_ds_info.paused_payment_id. Do not create a new payment.

Q: Can I pass my own payment_id? A: No. payment_id is generated by Build. Use order_reference and merchant_request_id for your own identifiers.

Q: What is the maximum amount? A: Depends on your merchant limits and the payment method.

Q: Is there a test mode for BINANCE_PAY / ALIPAY_PLUS_PAY? A: Yes — the sandbox environment simulates wallet callbacks. See the sandbox guide for trigger values.

Next Steps