Skip to content
Ridley Docs

Create a session.

POST
/v1/sessions
curl --request POST \
  --url https://api.ridleypay.com/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ord_abc123' \
  --data '{ "amount": 99.99, "reference": "WOO-123", "currency": "JMD", "description": "Order #123: Blue Widget", "success_url": "https://store.example.com/order-received/123", "cancel_url": "https://store.example.com/checkout", "customer_email": "jane@example.com", "customer_name": "Jane Doe", "metadata": { "order_id": 42, "order_key": "wc_order_abc" }, "subtotal": 89.99, "discount": 10, "shipping": 5, "tax": { "amount": 15, "lines": [ { "name": "GCT", "rate": 15, "amount": 15 } ] }, "capture_method": "automatic", "save_payment_method": true, "apply_tax": true }'

Creates a new checkout session and returns a checkout_url to redirect your customer to. The session expires after 24 hours.

Supports an optional Idempotency-Key header. If the same key is sent within 24 hours, the original response is returned.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
Example
ord_abc123

Request Bodyrequired

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

The payment amount. Must be at least 0.01. Must not be greater than 999999.99.

number
Example
99.99
reference
required

A unique reference for the payment (e.g. your order ID). Must not be greater than 255 characters.

string
Example
WOO-123
currency

ISO 4217 currency code. Defaults to the source’s configured currency. Must be 3 characters.

string
nullable
Example
JMD
description

An optional description for the payment. Must not be greater than 500 characters.

string
nullable
Example
Order #123: Blue Widget
success_url

URL to redirect to after a successful payment. Must be a valid URL.

string
nullable
Example
https://store.example.com/order-received/123
cancel_url

URL to redirect to if the customer cancels. Must be a valid URL.

string
nullable
Example
https://store.example.com/checkout
customer_email

Customer’s email address. Must be a valid email address.

string
nullable
Example
jane@example.com
customer_name

Customer’s full name. Must not be greater than 255 characters.

string
nullable
Example
Jane Doe
metadata

Arbitrary key-value data to attach to the payment. Returned in webhooks.

object
Example
{
  "order_id": 42,
  "order_key": "wc_order_abc"
}
subtotal

Order subtotal before tax, shipping, and discounts. Must be at least 0.

number
nullable
Example
89.99
discount

Total discount amount applied to the order. Must be at least 0.

number
nullable
Example
10
shipping

Shipping cost. Must be at least 0.

number
nullable
Example
5
tax

Tax breakdown object with total amount and optional line items.

object
amount

Must be at least 0.

number
nullable
Example
15
lines
Array<object>
object
name

This field is required when tax.lines is present. Must not be greater than 255 characters.

string
Example
b
rate

Must be at least 0.

number
nullable
Example
39
amount

This field is required when tax.lines is present. Must be at least 0.

number
Example
84
Example
[
  {
    "name": "GCT",
    "rate": 15,
    "amount": 15
  }
]
Example
{
  "amount": 15,
  "lines": [
    {
      "name": "GCT",
      "rate": 15,
      "amount": 15
    }
  ]
}
capture_method

How to handle the payment. “automatic” (default) captures immediately. “manual” authorizes only, and you must call /payments/{reference}/capture later.

string
nullable
Allowed values: automatic manual
Example
automatic
save_payment_method

Save the card on file so it can be charged later without the customer present (recurring schedules and /charges). Supported on PowerTranz.

boolean
nullable
Example
true
apply_tax

Calculate tax from your team tax settings. With exclusive tax, amount is the subtotal and tax is added; with inclusive tax, tax is extracted from amount. Overrides tax.

boolean
nullable
Example
true

Responses

Section titled “ Responses ”

201

Section titled “201”

Session created

Media typeapplication/json
object
data
object
id
string
type
string
attributes
object
amount
number
currency
string
reference
string
checkout_url
string
expires_at
string
links
object
self
string
checkout
string
Example
{
  "data": {
    "id": "cs_a1b2c3d4e5f6g7h8",
    "type": "sessions",
    "attributes": {
      "amount": 99.99,
      "currency": "USD",
      "reference": "WOO-123",
      "checkout_url": "https://pay.example.com/checkout/cs_a1b2c3d4e5f6g7h8",
      "expires_at": "2026-03-05T12:00:00.000000Z"
    },
    "links": {
      "self": "https://pay.example.com/api/v1/sessions/cs_a1b2c3d4e5f6g7h8",
      "checkout": "https://pay.example.com/checkout/cs_a1b2c3d4e5f6g7h8"
    }
  }
}

401

Section titled “401”

Invalid API key

Media typeapplication/json
object
errors
Array<object>
object
status
string
title
string
detail
string
Example
{
  "errors": [
    {
      "status": "401",
      "title": "Unauthorized",
      "detail": "Invalid or missing API key. Provide a secret key (sk_) as a Bearer token."
    }
  ]
}

409

Section titled “409”

Reference already used

Media typeapplication/json
object
errors
Array<object>
object
status
string
title
string
detail
string
Example
{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "A payment with this reference has already been completed."
    }
  ]
}

422

Section titled “422”

Validation error

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