Skip to main content
Create a payment link

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

1 to 255 printable ASCII characters with no spaces, quotes or backslashes, in double quotes as the IETF draft defines, or without them. We recommend a UUID. Make one for each thing you mean to happen once and store it before you send the request, so a retry after a crash sends the same key. Keys are scoped to your account and the endpoint, not to a token, so a new token or a rotated secret doesn't affect a retry. A partner and its merchant are separate accounts, so the same key sent with each credential starts two requests. Keys are kept for at least 7 days. After that, the same key starts a new request.

Required string length: 1 - 257
Pattern: ^(?:([\x21\x23-\x5B\x5D-\x7E]{1,255})|"([\x21\x23-\x5B\x5D-\x7E]{1,255})")$

Path Parameters

id
string
required
Minimum string length: 1

Body

application/json
amount
object
required

An amount of money. Decimal values are refused, not rounded.

statement_descriptor
string
required

Becomes alphanumeric on the way to the bank. On a payment transaction through a virtual account, the customer's statement shows Quidkey's reconciliation reference instead.

Required string length: 1 - 18
type
enum<string>
default:single_use
Available options:
single_use,
reusable
is_test
boolean
default:false

Makes the link's payment transactions test ones. Without it the link is live, which answers LIVE_PAYMENTS_NOT_ALLOWED for a merchant not yet activated. A suspended merchant still gets its live link, whose payment transactions are refused until it can take live payment transactions again.

order
object

The caller's order. Not unique: a reusable link puts it on every payment transaction.

locale
string
default:en
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$
success_url
string<uri>

Both URLs or neither.

Maximum string length: 2048
Pattern: ^https://
failure_url
string<uri>
conditionally required

Both URLs or neither.

Maximum string length: 2048
Pattern: ^https://
expires_at
string<date-time>

60 seconds to 1 year ahead. Defaults to 7 days from now.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$

Response

The payment_link, in the full view.

result
object
required
entities
object
required

Nothing can be included here.

not_included
object[]
required