Sign in

v1

latestOpenAPI 3.1.02026-07-1342112262.5 KB
Payment links

Create a payment link

Create a payment link

Required scopes: business/orders:read, business/orders:write

post/v1/payment_links/

Request body

customer_referencestring required

The customer's name or reference that will appear on the payment page.

customer_descriptionstring nullable

An optional description that will appear on the payment page.

Example request

{
  "amount": {
    "amount": 1500,
    "currency": "ZAR"
  },
  "customer_description": "This description is visible to the customer on the payment page.",
  "customer_reference": "Peter Parker"
}

Response

Successful Response

idstring required

The unique identifier of the payment link.

urlstring required

The payment link.

customer_referencestring required

The customer's name or reference that will appear on the payment page.

customer_descriptionstring nullable required

An optional description that will appear on the payment page.

status'cancelled' | 'paid' | 'pending' required

A payment link transitions through various states throughout its lifecycle.

A payment link is always created in a pending state. From there, it will move to a terminal state which will be one of either paid or cancelled.

The following transitions are possible:

  • pending -> paid
  • pending -> cancelled
order_idstring required

A reference to the original order.

created_atstring date-time required

The payment link creation date and time in ISO 8601 format.

updated_atstring date-time nullable required

The date and time the payment link was last modified in ISO 8601 format.

Example response

{
  "created_at": "2024-11-19T15:27:02+00:00",
  "customer_description": "This description is visible to the customer on the payment page.",
  "customer_reference": "Peter Parker",
  "id": "1743683416648-616bc018-c572-430b-9c07-4e813ed03eb4",
  "order_id": "1585232943682-9f7e2dbe-a09e-4fa8-aa4a-72290c513f1d",
  "status": "pending",
  "updated_at": "2024-11-19T16:27:23+00:00",
  "url": "https://pay.yoco.com/r/dRggEC"
}