Skip to main content
POST
/
api
/
v1
/
payment
/
refund
BODY='{"original_transaction_id":"txn_pos_12345","amount":"1500.00","reason":"Customer returned item","initiated_by":"admin_user_01"}'
TIMESTAMP='2026-03-10T12:00:00Z'
SIGNATURE=$(printf 'POST\n/api/v1/payment/refund\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/payment/refund" \
  -H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"

{
  "success": true,
  "message": "Refund processed successfully",
  "refund_transaction_id": "rfnd_abc789",
  "amount": "1,500.00 SLE"
}
Refunds are submitted through the HMAC integration and reverse funds from the processor back to the subscriber.

​
Request

​
X-API-Key-ID
string
required
API key ID assigned to the integration
​
X-Timestamp
string
required
RFC3339 timestamp used in the HMAC signature
​
X-Signature
string
required
Hex-encoded HMAC-SHA256 of the request

​
Body Parameters

​
original_transaction_id
string
required
ID of transaction to refund
​
amount
string
required
Amount to refund (can be partial)
​
reason
string
required
Reason for refund
​
initiated_by
string
required
Admin/User ID authorizing refund

​
Response

​
success
boolean
Whether refund succeeded
​
refund_transaction_id
string
Refund transaction ID
​
amount
string
Formatted refunded amount

​
Example

BODY='{"original_transaction_id":"txn_pos_12345","amount":"1500.00","reason":"Customer returned item","initiated_by":"admin_user_01"}'
TIMESTAMP='2026-03-10T12:00:00Z'
SIGNATURE=$(printf 'POST\n/api/v1/payment/refund\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://olive-gateway-a6ba.onrender.com/api/v1/payment/refund" \
  -H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"

{
  "success": true,
  "message": "Refund processed successfully",
  "refund_transaction_id": "rfnd_abc789",
  "amount": "1,500.00 SLE"
}

​
Errors

StatusCodeDescription
400Validation or business errorInvalid amount or refund not allowed
401HMAC auth errorMissing/invalid X-API-Key-ID, X-Timestamp, or X-Signature
500Internal errorServer error

Authorizations

​
Authorization
string
header
required

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

Headers

​
X-API-Key-ID
string
required

API key ID assigned to the integration

​
X-Timestamp
string
required

RFC3339 timestamp used in the HMAC signature

​
X-Signature
string
required

Hex-encoded HMAC-SHA256 of the request

Body

application/json
​
original_transaction_id
string
required

ID of transaction to refund

​
amount
string
required

Amount to refund (can be partial)

​
reason
string
required

Reason for refund

​
initiated_by
string
required

Admin/User ID authorizing refund

Response

200 - application/json

Response 200

​
success
boolean

Whether refund succeeded

​
refund_transaction_id
string

Refund transaction ID

​
amount
string

Formatted refunded amount