Refunds

The Refunds API lets you create, manage, and retrieve refunds for transactions, ensuring timely resolutions for failed services, overcharges, or disputes.

Use Case

Automatically trigger refunds for failed services, overcharges, or customer complaints.


1. Create a Refund

Initiate a refund for a specific transaction using its reference or ID.

Endpoint

POST /refund

Headers

KeyTypeValue
api-keyStringBearer YOUR_SECRET_KEY
Content-TypeStringapplication/json

Body Parameters

KeyTypeDescription
transactionStringTransaction reference or ID

cURL Example

#!/bin/sh
url="https://api.transactpay.co/refund"
authorization="Authorization: Bearer YOUR_SECRET_KEY"
content_type="Content-Type: application/json"
data='{ "transaction": 1641 }'

curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
⚠️

Note:

Refunds are queued and may not be instant.

Sample Response

{
  "status": true,
  "message": "Refund has been queued for processing",
  "data": {
    "transaction": {
      "id": 1004723697,
      "reference": "T685312322670591",
      "amount": 10000,
      "currency": "NGN",
      "paid_at": "2021-08-20T18:34:11.000Z",
      "customer_note": "Refund for transaction T685312322670591"
    },
    "status": "pending",
    "expected_at": "2021-12-16T09:21:17.016Z"
  }
}

2. List All Refunds

Fetch all refunds processed under your account.

Endpoint

GET /refund

Headers

KeyTypeValue
AuthorizationStringBearer YOUR_SECRET_KEY

Query Parameters

KeyTypeDescription
transactionString(Optional) Filter by transaction ID
currencyString(Optional) Filter by currency

cURL Example

#!/bin/sh
url="https://api.transactpay.co/refund"
authorization="Authorization: Bearer YOUR_SECRET_KEY"

curl "$url" -H "$authorization" -X GET

Sample Response

{
  "status": true,
  "message": "Refunds retrieved",
  "data": [
    {
      "id": 1,
      "transaction": 1641,
      "amount": 500000,
      "currency": "NGN",
      "status": "processed",
      "refunded_by": "[email protected]",
      "refund_date": "2018-01-12T10:54:47.000Z"
    },
    {
      "id": 2,
      "transaction": 323896,
      "amount": 500000,
      "currency": "NGN",
      "status": "pending",
      "refunded_by": "[email protected]",
      "refund_date": "2017-09-24T21:11:53.000Z"
    }
  ]
}

3. Fetch a Specific Refund

Get the details of a refund using its unique ID.

Endpoint

GET /refund/:id

Headers

KeyTypeValue
AuthorizationStringBearer YOUR_SECRET_KEY

cURL Example

#!/bin/sh
url="https://api.transactpay.co/refund/:id"
authorization="Authorization: Bearer YOUR_SECRET_KEY"

curl "$url" -H "$authorization" -X GET

Sample Response

{
  "status": true,
  "message": "Refund retrieved",
  "data": {
    "transaction": 1641,
    "amount": 500000,
    "currency": "NGN",
    "status": "processed",
    "refunded_by": "[email protected]",
    "refund_date": "2018-01-12T10:54:47.000Z"
  }
}

Final Notes

⚠️

Security Reminder

Always keep your SECRET_KEY secure and never expose it in client-side code.

👍

Best Practice

Use webhooks to monitor refund status updates and notify your customers automatically when a refund is completed.

#!/bin/sh
url="https://api.transactpay.co/refund/:id"
authorization="Authorization: Bearer YOUR_SECRET_KEY"

curl "$url" -H "$authorization" -X GET
{
  "status": true,
  "message": "Refund retrieved",
  "data": {
    "transaction": 1641,
    "amount": 500000,
    "currency": "NGN",
    "status": "processed",
    "refunded_by": "[email protected]",
    "refund_date": "2018-01-12T10:54:47.000Z"
  }
}

What’s Next