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

Key	Type	Value
api-key	String	Bearer `YOUR_SECRET_KEY`
Content-Type	String	application/json

Body Parameters

Key	Type	Description
transaction	String	Transaction reference or ID

cURL Example

#!/bin/sh
url="https://payment-api-service.transactpay.ai/payment/order/refund"
header="api-key: YOUR SECRET KEY"
content_type="Content-Type: application/json"
data=' {
          "reference":"transactionReference",
          "Reason": "refund",
          "Amount": "10.00"
}'

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

Key	Type	Value
Authorization	String	Bearer `YOUR_SECRET_KEY`

Query Parameters

Key	Type	Description
transaction	String	(Optional) Filter by transaction ID
currency	String	(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

Key	Type	Value
Authorization	String	Bearer `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"
  }
}

Use Case

1. Create a Refund

Endpoint

Headers

Body Parameters

cURL Example

Note:

Sample Response

2. List All Refunds

Endpoint

Headers

Query Parameters

cURL Example

Sample Response

3. Fetch a Specific Refund

Endpoint

Headers

cURL Example

Sample Response

Final Notes

Security Reminder

Best Practice

What’s Next