v1

latestOpenAPI 3.1.02026-07-2478315484.9 KB

Payment Links

Create Payment Link

Creates a payment link that can be shared with customers to collect payments. The link remains ACTIVE until it expires, reaches its usage limit, or is explicitly disabled.

post/payment-links/v1

Request body

namestring nullable

A label for your own reference. Not shown to payers. Useful for distinguishing links in list views.

max_usagesinteger nullable

The maximum number of successful payments this link will accept. Once reached, the link transitions to USED status and will reject further payment attempts. Defaults to 1000 if omitted.

expires_atstring date-time nullable

The date and time at which this link will automatically expire, in ISO 8601 format. After this time the link transitions to EXPIRED status. Omit to create a link with no expiry.

redirect_urlstring nullable

The URL your customer is redirected to after completing or cancelling a payment. Must be an absolute URL. You can use query parameters to carry context (e.g., an order ID) back to your application. Optional - if omitted, the payer will see a confirmation screen on completion instead of being redirected.

customer_idstring uuid nullable

Associates this link with a specific customer in your system. If provided, all payments will be associated with that customer.

Example request

{
  "payment_details": {
    "currency": "AED"
  },
  "identifiers": [
    {
      "type": "EMAIL",
      "display_label": "Your email address",
      "required": true
    }
  ]
}

Response

Payment link created successfully

idstring uuid required

The unique ID of this payment link. Use this to retrieve, update, or reference the link in other API calls.

linkstring uri required

The URL to share with your customer. Directing a customer to this URL begins the payment flow. Anyone with this URL can initiate a payment.

status'ACTIVE' | 'EXPIRED' | 'USED' | 'DISABLED' required

The lifecycle state of a payment link.

ACTIVE: The link is live and will accept payments. This is the initial state after creation.
EXPIRED: The link's expires_at time has passed. It can no longer accept payments and cannot be reactivated.
USED: The link has reached its max_usages limit. All permitted payments have been collected. Cannot be reactivated.
DISABLED: The link was manually disabled via the update endpoint. It can be re-enabled by setting status to ACTIVE.

current_usagesinteger required

The number of successful payments completed through this link. Increments each time a payer completes a payment. Compare with max_usages to understand remaining capacity.

namestring nullable

The label you provided when creating the link, if any. For display purposes only.

max_usagesinteger nullable

The maximum number of payments this link will accept before transitioning to USED status. Null indicates no limit.

expires_atstring date-time nullable

The expiry date and time for this link in ISO 8601 format. After this time the link cannot be used. Null means the link does not expire automatically.

redirect_urlstring uri required

The URL your customer is redirected to after completing or cancelling a payment.

customer_idstring uuid nullable

The ID of the customer associated with this link, if any. Payments through this link will be attributed to this customer.

Example response

{
  "payment_details": {
    "currency": "AED"
  }
}