Skip to main content
POST
/
payments-api-service
/
v1
/
refund-reversal
Initiate Refund/Reversal
curl --request POST \
  --url https://sandbox.waftpay.io/api/payments-api-service/v1/refund-reversal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_reference": "TRC94513697913522",
  "payment_uuid": "803556523944079845",
  "amount": 400,
  "notification_url": "https://webhook.site/679ced79-7dac-4977-be7a-3d600b39c245",
  "remarks": "Test remarks"
}
'
{
  "code": 102,
  "status": "SUCCESS",
  "description": "Request accepted",
  "results": {
    "request_uuid": "A333RTYUT"
  }
}

​
Overview

Use this endpoint to initiate a refund or reversal for a collection payment. The request is asynchronous: you receive a request_uuid immediately, then check the final outcome via the status endpoint.
Auth: Requires a Collection token (Authorization: Bearer <collection_token>).

​
Endpoint

POST {BASE_URL}/payments-api-service/v1/refund-reversal

​
Request body

FieldTypeRequiredNotes
transaction_referencestringYesOriginal transaction reference to refund/reverse.
payment_uuidstringYesOriginal Waftpay payment UUID.
amountnumberYesAmount to refund/reverse in major units.
notification_urlstringYesHTTPS URL to receive the final status callback.
remarksstringNoOptional reason or notes.

​
Example request

{
  "transaction_reference": "TRC94513697913522",
  "payment_uuid": "803556523944079845",
  "amount": 400,
  "notification_url": "https://webhook.site/679ced79-7dac-4977-be7a-3d600b39c245",
  "remarks": "Test remarks"
}

​
Example response (accepted)

{
  "code": 102,
  "status": "SUCCESS",
  "description": "Request accepted",
  "results": {
    "request_uuid": "A333RTYUT"
  }
}

​
Next step

Use the request_uuid to check the final outcome: Refund/Reversal status.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
transaction_reference
string
required

Original transaction reference to refund/reverse.

​
payment_uuid
string
required

Original Waftpay payment UUID.

​
amount
number
required

Amount to refund/reverse in major units.

​
notification_url
string<uri>
required

HTTPS URL to receive final status callbacks.

​
remarks
string

Optional reason or notes.

Response

Accepted

​
code
integer
required

Application code, e.g., 102 for SUCCESS.

​
status
string
required

Semantic status, e.g., SUCCESS.

​
description
string
required

Human-readable description.

​
results
object
required

Request metadata for status checks.