Create a payment request

POST/api/v2/payment-requests

Creates a payment request in status draft. Nothing reaches the payer, and no invoice is issued, before finalize. andThen runs finalize, and then send, in the same request and fails with their codes. A currency your team cannot receive bank transfers in fails with CURRENCY_NOT_RECEIVABLE. Needs payment-requests:write.

Header Parameters

idempotency-key?maxLength(255)

Client-chosen key, 1 to 255 characters (a UUID is recommended). The same key on the same endpoint within 24 hours replays the stored response with Idempotent-Replayed: true.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customId?|

Your own key for the payment request. Use it in place of the id wherever a payment request is referenced. Freed when the request is deleted.

description*maxLength(2000)

What the payer pays for. Printed on the invoice. 1 to 2000 characters.

Length1 <= length <= 2000

amount*MoneyInput

Decimal string with a . decimal point and up to two fraction digits. Minimum 0.10.

Match^\d+(\.\d{1,2})?$

currency*string

Currency of the request. Your team must be able to receive bank transfers in it.

Value in

"USD"
"EUR"
"CHF"
"GBP"

payer*|

Who is asked to pay, discriminated on type.

tags?array<>

Your labels for the payment request. Filter the list with ?tag=. Up to 20 tags of 1 to 100 characters.

Itemsitems <= 20

andThen?|

Runs the later steps in the same request, all or nothing. finalize moves the request to open and issues the invoice for a counterparty payer. finalize_and_send also emails paymentUrl to the payer; a failed email leaves sentAt null instead of failing the request, and send tries again.

Response Body

`application/json`

curl -X POST "https://example.com/api/v2/payment-requests" \  -H "Content-Type: application/json" \  -d '{    "description": "string",    "amount": "100.00",    "currency": "USD",    "payer": {      "type": "counterparty",      "counterpartyId": "counterparty_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e"    }  }'

{  "object": "payment_request",  "id": "payment_request_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",  "customId": "campaign-42",  "description": "string",  "amount": "100.00",  "currency": "USD",  "amountDue": "100.00",  "amountRemaining": "100.00",  "payer": {    "type": "email",    "email": "jane@example.com"  },  "status": "draft",  "tags": [    "string"  ],  "paymentUrl": "string",  "invoice": {    "number": "string",    "url": "string",    "issuedAt": "string",    "vatRate": "19.00",    "vatAmount": "100.00",    "creditNote": {      "number": "string",      "url": "string",      "issuedAt": "string"    }  },  "settlements": [    {      "type": "bank_transfer",      "transactionId": "transaction_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e_out",      "status": "pending",      "amount": "100.00",      "createdAt": "2026-09-24T10:00:00.000Z"    }  ],  "sentAt": "2026-09-24T10:00:00.000Z",  "firstViewedAt": "2026-09-24T10:00:00.000Z",  "transferAnnouncedAt": "2026-09-24T10:00:00.000Z",  "paidAt": "2026-09-24T10:00:00.000Z",  "cancelledAt": "2026-09-24T10:00:00.000Z",  "createdAt": "2026-09-24T10:00:00.000Z",  "updatedAt": "2026-09-24T10:00:00.000Z"}

Create a payment request

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`