Status and reversals

Transaction statuses

Every transaction starts as pending and ends as successful or failed.

`status`	`isoCode`	`code` (deprecated)	Meaning
`pending`	(none)	(none)	Waiting for the customer or the network.
`successful`	`000`	`111`	The money moved.
`failed`	`100`	`000`	The money didn’t move. `statusReason` gives the reason where available.

Use isoCode, which follows ISO 8583. The legacy code is deprecated but still sent, so existing integrations keep working. See Result codes.

Transaction types:

`transactionType`	Meaning
`collection`	A collection.
`collection-dd`	A direct debit payment.
`disbursement-b2c`	A disbursement to a customer.
`disbursement-b2b`	A disbursement to a business. Not available through the API yet.

Check a status

GET/api/v1/transactions/payments/status/{transactionId}

curl https://preprod.api.nerasika.com/api/v1/transactions/payments/status/6718a2c4e5f0a1b2c3d4e5f6 \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "message": "Success",
  "data": {
    "transactionId": "6718a2c4e5f0a1b2c3d4e5f6",
    "merchantRef": "order-1042",
    "transactionType": "collection",
    "amount": 10.5,
    "originalAmount": 10.5,
    "isoCode": "000",
    "code": "111",
    "status": "successful",
    "statusReason": "successful",
    "reversed": false
  }
}

amount is the current amount, which goes down after a partial reversal. originalAmount stays as it was. reversalAmount appears only once a transaction has been reversed.

The status check asks the network for the latest result. If the network has a final result that NeraSika hadn’t recorded yet, the transaction is updated and the result is also sent to your callback URL.

Reverse a collection

A reversal returns all or part of a successful collection to the customer.

POST/api/v1/transactions/payments/reverse

{
  "transactionId": "6718a2c4e5f0a1b2c3d4e5f6",
  "reversalAmount": "5.00",
  "merchantReversalCallbackURL": "https://example.com/reversal"
}

Field	Required	Description
`transactionId`	Yes	The collection to reverse.
`reversalAmount`	No	Amount to return, in GHS. Leave it out to reverse the full amount.
`merchantReversalCallbackURL`	Yes	The URL that receives the reversal result.

Response (200):

{
  "success": true,
  "message": "Transaction processing",
  "data": {
    "transactionId": "6718a2c4e5f0a1b2c3d4e5f6",
    "merchantRef": "order-1042",
    "originalAmount": 10.5,
    "reversalAmount": 5,
    "reversalStatus": "pending"
  }
}

The result arrives at merchantReversalCallbackURL. See Callbacks.

Reversal rules

Rule	Error
Only collections and direct debit payments can be reversed.	`400` `Only collections can be reversed`
The transaction must be `successful`.	`400` `Transaction still processing` or `Failed transaction, cannot be reversed`
A transaction can be reversed only once.	`400` `Transaction has already been reversed...`
Only one reversal can run at a time.	`400` `Transactions reversal already initiated`
The reversal can’t be more than the transaction amount.	`400` `Reversal is amount greater than transaction amount`
Your balance must cover the reversal amount, which is held until the reversal finishes.	`403` `Not enough merchant funds`
Reversals must be enabled for your account.	`403` `Transaction type not allowed for merchant`