Skip to content
Ridley Docs

Quickstart

Ridley uses a Stripe-like redirect flow: you create a session, send the customer to the returned checkout_url, and confirm the result with a webhook.

1. Authenticate

Section titled “1. Authenticate”

Every request uses your Source secret key as a Bearer token. Keys start with sk_test_ (sandbox) or sk_live_ (production). You can also send it in the X-API-Key header.

Terminal window
Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Create a Source and copy its keys from Settings → Sources in the dashboard.

2. Create a session

Section titled “2. Create a session”
Terminal window
curl https://api.ridleypay.com/v1/sessions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "amount": 150.00,
    "currency": "JMD",
    "reference": "order-12345",
    "description": "Order 12345",
    "customer_email": "jane@example.com",
    "success_url": "https://your-app.com/orders/12345/thanks",
    "cancel_url": "https://your-app.com/orders/12345/cancelled"
  }'

The response contains a checkout_url. Send the customer there.

{
  "data": {
    "id": "cs_a1b2c3d4e5f6g7h8",
    "type": "sessions",
    "attributes": {
      "amount": 150.0,
      "currency": "JMD",
      "reference": "order-12345",
      "checkout_url": "https://checkout.ridleypay.com/checkout/cs_a1b2c3d4e5f6g7h8",
      "expires_at": "2026-03-05T12:00:00.000000Z"
    }
  }
}

3. Confirm the payment

Section titled “3. Confirm the payment”

Two things happen after the customer pays:

  • The browser is redirected to your success_url. Use this for UX only.
  • Ridley sends a signed webhook. Treat this as the source of truth.
{
  "event": "payment.completed",
  "data": {
    "reference": "order-12345",
    "amount": 150.0,
    "currency": "JMD",
    "status": "PAID",
    "card_last": "4242",
    "card_brand": "visa"
  }
}

You can also poll the payment directly:

Terminal window
curl https://api.ridleypay.com/v1/payments/order-12345 \
  -H "Authorization: Bearer sk_test_xxx"

See Webhooks for signature verification and retry behaviour.

Next steps

Section titled “Next steps”