Pay with Phone
Overview
Pay with Phone allows customers to make payments using their phone number. A payment prompt is sent directly to their phone for authorization.
How It Works
- Initialize payment with customer’s phone number
- Customer receives payment prompt on their phone
- Customer authorizes payment
- Verify transaction status
- Optionally cancel the transaction if needed
Base URL
https://mainapi.cashonrails.com/api/v1/s2s
Integration Steps
1. Initialize Payment
Send a POST request to initialize the payment:
curl --location '{{baseurl}}/paywithphone/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
"email": "customer@email.com",
"amount": "100",
"currency": "NGN",
"reference": "{{reference}}",
"phoneNumber": "08012345678"
}'Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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 |
| phoneNumber | string | Yes | Customer’s phone number |
Sample Response
{
"status": true,
"message": "Payment prompt sent successfully",
"data": {
"reference": "COR_202402210123456789",
"amount": "100",
"currency": "NGN",
"status": "pending"
}
}2. Customer Authorization
Customer will receive a prompt on their phone to authorize the payment. This might be a USSD prompt
3. Verify Transaction
After customer authorization, 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": "phone"
}
}⚠️
Always verify the transaction status before confirming payment. The verification step is crucial as the customer might decline or ignore the payment prompt.
4. 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