Batch settlement combines multiple relayed_intent payments into a single relay call. Each payer signs their own PaymentIntent; your backend collects signatures and calls POST /payments/settlements/intents/batch. All payments settle atomically with flow relayed_batch, one transaction, multiple payment.settled webhooks. Group project energy, but it actually ships.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
A buyer signs three PaymentIntents for cart items. Your backend collects all signatures and calls POST /payments/settlements/intents/batch with batchReference cart-1042. One transaction settles all three; three payment.settled webhooks arrive with flow relayed_batch.
Auto-batching on the relay lane
When you relay intents individually via POST /payments/settlements/intents/relay, Videpay may combine queued intents on the same settlement contract into an automatic relayed_batch if the lane threshold or wait window is reached. Explicit batch calls give you immediate control over grouping and batchReference.
Submit all signatures in one request. Payments must be prepared relayed_intent records on the same chain and settlement contract.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
batchReference | string | No | Optional reconciliation label for the batch (max 100). Auto-generated when omitted. |
payments | array | Yes | Signed intents to settle atomically. 1–50 items; each item requires paymentId and signature. |
payments[].paymentId | uuid | Yes | Prepared relayed_intent payment ID. |
payments[].signature | hex string | Yes | EIP-712 signature for that payment intent. |
/payments/settlements/intents/batchRelay multiple signed payment intents atomically. Requires secret API key.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "batchReference": "batch-cart-001",03 "chain": "base",04 "payments": [05 {06 "paymentId": "pst_4a8f2c1d9e7b6a3f5c2d8e1b0a9f7c6d",07 "signature": "0x..."08 },09 {10 "paymentId": "pst_bbb2c1d9e7b6a3f5c2d8e1b0a9f7c6e",11 "signature": "0x..."12 }13 ]14}When a prepared intent will not be used, prepare an on-chain nonce invalidation transaction for the payer to sign. Only relayed_intent payments that have not settled can be invalidated.
Settled intents cannot be invalidated
Invalidation is only available before settlement. If the intent was already relayed and settled, use POST /payments/refund on the Refunds page instead.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
/payments/settlements/intents/pst_4a8f2c1d9e7b6a3f5c2d8e1b0a9f7c6d/invalidate/preparePrepare invalidation of an unused payment intent. Requires secret API key.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/jsonRegister a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.
payment.settledSent when funds are confirmed on-chain and credited to your merchant balance.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: payment.settled04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...