API conventions

Authentication

Send your Source secret key as a Bearer token (or in X-API-Key). Keys are prefixed sk_live_ (production) or sk_test_ (sandbox).

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Call GET /v1/me to verify a key and see its mode and limits.

Test mode

Keys beginning with sk_test_ run in sandbox mode. Test sessions render a sandbox checkout that never contacts a payment processor. The test card decides the outcome. Test data is isolated: a test key only sees test payments, a live key only sees live payments.

Card number	Result
`4242 4242 4242 4242`	Approved
`4000 0000 0000 0002`	Declined (insufficient funds)
`4000 0000 0000 9995`	Declined (generic)

Errors

Every error uses a JSON:API errors array, including framework-level failures (404, 405, 429, 5xx), so one parser handles everything.

{
  "errors": [
    { "status": "422", "title": "Unprocessable Entity", "detail": "The amount field is required." }
  ]
}

Validation errors also include meta.errors, a map of field → messages.

Amounts

Amounts are decimals in the currency’s major unit and are returned as strings (e.g. "99.99"). Requests use ISO 4217 alphabetic currency codes (e.g. JMD).

Idempotency

POST endpoints accept an Idempotency-Key header. Reuse the same key within 24 hours to receive the original response instead of creating a duplicate. Reusing a key with a different request body returns 409 Conflict.

curl https://api.ridleypay.com/v1/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Idempotency-Key: order-12345" \
  -d '{ "amount": 150.00, "currency": "JMD", "reference": "order-12345" }'

Payment references

A session’s reference (usually your order ID) identifies one payment. Creating a session returns 409 Conflict when:

a payment with that reference has already gone through, or
the reference is already used by another website on Ridley.

You can create a new session for a reference whose earlier attempt failed or was abandoned. If you share references across stores, prefix them (for example store2-1001).

Rate limits

Responses include X-RateLimit-Limit and X-RateLimit-Remaining; 429 responses include Retry-After. Limits depend on your plan.

Includes and sparse fieldsets

Request related resources with include, and limit attributes with fields:

GET /v1/payments/order-12345?include=refunds
GET /v1/payments?fields[payments]=reference,status,amount