Collections

A collection asks a customer to pay you from their mobile money wallet. The customer gets a prompt on their phone, approves it with their PIN, and the money goes to your merchant balance.

POST/api/v1/transactions/payments/collection

How it works

1. You send the request. NeraSika replies 202 Accepted with status pending.
2. The customer gets a prompt on their phone and approves or declines it.
3. NeraSika sends the result to your merchantCallbackURL.
4. A successful collection is credited to your merchant balance.

Request

{
  "phone": "0241234567",
  "amount": "10.50",
  "desc": "Order 1042",
  "network": "MTN",
  "merchantRef": "order-1042",
  "merchantCallbackURL": "https://example.com/callback"
}

Field	Required	Description
phone	Yes	The customer’s mobile money number. 0241234567 and 233241234567 both work. Spaces and other non-digits are removed.
amount	Yes	Amount in GHS. A positive number with at most 2 decimal places, such as 10 or 10.50.
desc	Yes	A description of the payment.
network	Yes	MTN, Telecel or AirtelTigo.
merchantRef	Yes	Your own reference, such as an order ID. It comes back in the response and callback.
merchantCallbackURL	Yes	The URL that receives the result.

Any other field is rejected with 400.

Response

202 Accepted

{
  "success": true,
  "message": "Transaction processing",
  "data": {
    "transactionId": "6718a2c4e5f0a1b2c3d4e5f6",
    "merchantRef": "order-1042",
    "amount": 10.5,
    "status": "pending"
  }
}

Store transactionId with your order. You need it to check the status or reverse the payment.

Result

The result arrives at merchantCallbackURL. See Callbacks for the payload. A status of successful (isoCode 000) means the money was collected. failed (isoCode 100) means it wasn’t, and statusReason says why where the network gives a reason.

Tip

If the result hasn’t arrived after a few minutes, check the status. The customer may not have responded to the prompt yet.

Account rules

Your merchant account settings control what you can collect:

Rule	Error
Collections must be enabled for your account.	403 Transaction type not allowed for merchant
The network must be enabled for your account.	403 MTN transactions not allowed for merchant
The amount must be within your collection limit.	400 Transaction amount of 5000 is above the 1000 limit for merchant

Contact Nerasol to change these settings.