Standardcheckout – Cashonrails Documentation

Standard Checkout

The Standard Checkout integration allows you to generate a unique payment URL that your customers can use to securely complete their transactions.

Initialize the Payment
Make a server-side POST request to the payment initialization endpoint:
https://api.cashonrails.com/api/v1/transaction/initialize.
Redirect the Customer
Upon a successful request, we’ll return a unique link or access code for the payment page. Redirect your customer to this page to complete their payment.
After the Payment
Once the payment is completed, the customer will be redirected back to your provided redirectUrl. You can use this event to confirm the transaction and update your records.

Step 1: Initialize the Payment

Make a server-side POST request to the payment initialization endpoint with the following payload:


{
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "amount": "5000",
  "currency": "NGN",
  "reference": "unique-ref-12345",
  "redirectUrl": "https://example.com/payment-complete",
  "logoUrl": "https://example.com/logo.png"
}

Field	Type	Required	Description
email	string	Required unless `customer_code` identifies an existing customer	Customer’s email address (e.g., customer@example.com)
first_name	string	Required unless `customer_code` identifies an existing customer	Customer’s first name (e.g., John)
last_name	string	Required unless `customer_code` identifies an existing customer	Customer’s last name (e.g., Doe)
customer_code	string	No	Existing Cashonrails customer code. If supplied without full customer details, it must match an existing customer.
amount	number	Yes	The amount to be charged. Current validation requires a minimum of `100`
currency	string	Yes	The currency of the transaction (e.g., NGN)
reference	string	Yes	A unique reference for the transaction (e.g., unique-ref-12345)
redirectUrl	string	No	The URL to redirect after payment (e.g., https://example.com/payment-complete )
logoUrl	string	No	The URL of the logo to display (e.g., https://example.com/logo.png )

If you do not pass customer_code, provide email, first_name, and last_name so the API can resolve or create the customer for the checkout.

Step 2: Redirect the Customer

Upon a successful request, we’ll return a unique link or access code for the payment page. Redirect your customer to this page to complete their payment.

Response


{
  "success": true,
  "message": "Transaction Initialized Successfully",
  "data": {
    "authorization_url": null,
    "access_code": "x012345678abcdefghijkl",
    "checkout_link": "https://checkout.cashonrails.com/pay/x012345678abcdefghijkl",
    "transactionRef": "COR-qqlmex9vo62pdcl84rdzb",
    "reference": "78248692"
  }
}

Step 3: After the Payment

After the payment is completed, the following actions will occur:

The customer will be redirected to your redirect_url with query parameters status, reference.
If webhooks are enabled, a notification will be sent to your webhook endpoint. Learn more about webhooks.
An email receipt will be sent to the customer if the payment was successful, unless this feature is disabled.
You will receive an email notification, unless this feature is disabled.

On your server, you should handle the redirect and always verify the final state of the transaction.