Paywithphone – Cashonrails Documentation

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://api.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
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
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