Skip to content
Ridley Docs

Create a payment link.

POST
/v1/payment-links
curl --request POST \
  --url https://api.ridleypay.com/v1/payment-links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "Deposit for order 1042", "description": "Balance due on delivery.", "amount": 2500, "currency": "JMD", "success_url": "https://example.com/thanks", "cancel_url": "https://example.com/cart", "max_uses": 1, "expires_at": "2026-12-31T23:59:59Z", "taxable": true, "recurring": null, "metadata": { "order_id": "1042" }, "products": null }'

Pass either an amount or products. The response’s url is the link to send to your customer.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
title
required

Shown to the customer on the checkout page. Must not be greater than 255 characters.

string
Example
Deposit for order 1042
description

More detail shown under the title. Must not be greater than 5000 characters.

string
nullable
Example
Balance due on delivery.
amount

The amount to charge. Required unless you pass products. This field is required when products is not present. Must be at least 0.01. Must not be greater than 999999.99.

number
nullable
Example
2500
currency

ISO 4217 code. Defaults to the website’s default currency. Must be 3 characters.

string
nullable
Example
JMD
success_url

Where to send the customer after paying. Must be a valid URL. Must not be greater than 2048 characters.

string
nullable
Example
https://example.com/thanks
cancel_url

Where to send the customer if they cancel. Must be a valid URL. Must not be greater than 2048 characters.

string
nullable
Example
https://example.com/cart
max_uses

Turn the link off after this many payments. Use 1 for a one-off link. Must be at least 1.

integer
nullable
Example
1
expires_at

Turn the link off at this time (ISO 8601). Must be a valid date. Must be a date after now.

string
nullable
Example
2026-12-31T23:59:59Z
taxable

Add tax from your team’s tax settings on top of the amount. Defaults to false, so the customer pays exactly the amount.

boolean
nullable
Example
true
recurring

Bill the customer on a schedule after the first payment.

object
frequency

Daily, weekly, monthly or yearly. This field is required when recurring is present.

string
Allowed values: daily weekly monthly yearly
Example
monthly
interval_count

For example 3 with monthly bills every 3 months. Must be at least 1. Must not be greater than 365.

integer
nullable
Example
1
end_date

Stop billing after this date. Must be a valid date. Must be a date after today.

string
nullable
Example
2027-06-30
Example
null
metadata

Up to 50 keys of your own data. Copied onto every payment made with the link and included in its webhooks. Must not have more than 50 items.

object
Example
{
  "order_id": "1042"
}
products

Charge for products from your Ridley catalogue instead of a fixed amount. Must have at least 1 items. Must not have more than 50 items.

Array<object>
object
id
required

Must match an existing stored value.

integer
Example
16
quantity

Must be at least 1. Must not be greater than 1000.

integer
nullable
Example
22
Example
null

Responses

Section titled “ Responses ”

201

Section titled “201”

Created

Media typeapplication/json
object
data
object
id
string
type
string
attributes
object
url
string
title
string
description
string
nullable
type
string
amount
string
currency
string
active
boolean
usable
boolean
uses_count
integer
max_uses
integer
expires_at
string
nullable
taxable
boolean
recurring
string
nullable
products
array
metadata
object
order_id
string
success_url
string
nullable
cancel_url
string
nullable
test
boolean
created_at
string
updated_at
string
links
object
self
string
pay
string
Example
{
  "data": {
    "id": "41",
    "type": "payment-links",
    "attributes": {
      "url": "https://checkout.ridleypay.com/pay/Xk2...",
      "title": "Deposit for order 1042",
      "description": null,
      "type": "custom",
      "amount": "2500.00",
      "currency": "JMD",
      "active": true,
      "usable": true,
      "uses_count": 0,
      "max_uses": 1,
      "expires_at": null,
      "taxable": false,
      "recurring": null,
      "products": [],
      "metadata": {
        "order_id": "1042"
      },
      "success_url": null,
      "cancel_url": null,
      "test": false,
      "created_at": "2026-09-28T12:00:00.000000Z",
      "updated_at": "2026-09-28T12:00:00.000000Z"
    },
    "links": {
      "self": "https://api.ridleypay.com/v1/payment-links/41",
      "pay": "https://checkout.ridleypay.com/pay/Xk2..."
    }
  }
}

422

Section titled “422”

Validation error

Media typeapplication/json
object
errors
Array<object>
object
status
string
title
string
detail
string
Example
{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "The amount field is required when products is not present."
    }
  ]
}