Paywithwallet – Cashonrails Documentation

Pay with Wallet

Overview

Pay with Wallet allows customers to make payments directly through supported digital banks like OPay and PalmPay.

Base URL

https://api.cashonrails.com/api/v1/s2s

Integration Steps

1. Get Available Banks

First, retrieve the list of supported banks:


curl -X GET '{{baseurl}}/paywithbank/list \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Response


[
    {
        "bank": "Opay",
        "code": "100004"
    },
    {
        "bank": "PalmPay",
        "code": "100033"
    }
]

2. Initialize Payment

Make a POST request to initialize the payment:


curl --location '{{baseurl}}/paywithbank/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
    "email": "customer@email.com",
    "amount": "100",
    "currency": "NGN",
    "reference": "{{reference}}",
    "bankCode": "100004"
}'

Request Parameters

Parameter	Type	Required	Description
email	string	Yes	Customer’s email address
amount	string	Yes	Amount to charge
currency	string	Yes	Currency code (e.g., NGN)
reference	string	Yes	Unique transaction reference
bankCode	string	Yes	Bank code from available banks

Sample Response


{
    "_links": {
        "url": "https://api.cashonrails.com/api/v1/checkout/verify-transaction/COR_1743008425526102",
        "method": "GET"
    },
    "redirect_url": "https://express.opaycheckout.com/apiCashier/redirect/payment/checkoutHome?orderToken=TOKEN.273d2beb5a8e45dfb3ad05a526ec485d"
}

3. Redirect Customer

Redirect the customer to the URL provided in redirect_url to complete their payment.

4. Verify Transaction

After the customer completes payment, verify the transaction status:


curl -X GET '{{baseurl}}/transaction/verify/{reference}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Success Response


{
    "status": true,
    "message": "Transaction verified successfully",
    "data": {
        "reference": "COR_202402210123456789",
        "amount": "100",
        "currency": "NGN",
        "status": "success",
        "payment_method": "bank_transfer"
    }
}

Always verify the transaction status before confirming payment to the customer.

5. Cancel Transaction

You can cancel a transaction that is still pending or in progress:


curl -X GET {{baseurl}}/transaction/cancel/{reference} \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Replace {reference} with your transaction reference.

Cancellation Rules

Only pending or processing transactions can be cancelled
Completed transactions cannot be cancelled (use refund instead)
Failed transactions are already inactive and don’t need cancellation
Once cancelled, a transaction cannot be resumed