Paymentservices – Cashonrails Documentation

Payment Services

Use payment services to create hosted checkout sessions and verify transaction status. The backend should create the transaction and pass only authorization_url or access_code to the frontend.

Initialize Hosted Checkout


const checkout = await client.payment.checkout.initialize({
  email: 'customer@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
  amount: 5000,
  currency: 'NGN',
  reference: 'order_10045',
  redirectUrl: 'https://merchant.example/payments/callback',
  title: 'Order #10045',
  description: 'Payment for Order #10045'
});
 
console.log(checkout.data.authorization_url);

Current successful response shape:


{
  "success": true,
  "message": "Transaction Initialized Successfully",
  "data": {
    "authorization_url": "https://checkout.cashonrails.com/pay/<access_code>",
    "qr_code": "data:image/png;base64,...",
    "access_code": "<access_code>",
    "transactionRef": "COR-...",
    "reference": "order_10045"
  }
}

Request Fields

Field	Required	Notes
`amount`	Yes	Numeric. Current validation minimum is `100`.
`currency`	Yes	3-character currency code.
`reference`	Yes	Unique merchant reference, 3 to 100 characters.
`customer_code`	No	Use an existing customer. If not supplied, provide customer details.
`email`, `first_name`, `last_name`	Required unless `customer_code` resolves to a customer	Used to resolve or create the customer.
`phone`, `address`, `bvn`, `nin`, `dob`	No	Optional customer fields.
`redirectUrl`	No	HTTPS URL. Falls back to dashboard callback URL when omitted.
`title`, `description`, `logoUrl`	No	Checkout display metadata.

Verify Transaction


const verification = await client.payment.checkout.verify('order_10045');
 
if (verification.status === true && verification.data.status === 'success') {
  // Mark the order as paid if it is not already fulfilled.
}

Verification uses:


GET /api/v1/transaction/verify/{reference}

Integration Pattern

Generate and persist your own order reference.
Initialize checkout from your backend.
Redirect the customer to data.authorization_url or launch checkout with data.access_code.
Listen for webhooks.
Verify final status before fulfilment.

Notes on S2S Payments

Server-to-server payment methods live under /api/v1/s2s/* and require product-specific access. Use the route-level API Reference and provider-specific docs for those flows.