Refund Payment - OLIVE Payment Platform

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/pos/refund\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/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"
}

{
  "success": false,
  "error": "Transaction already fully refunded"
}

POST

pos

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/pos/refund\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/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"
}

{
  "success": false,
  "error": "Transaction already fully refunded"
}

Refunds are submitted through the POS HMAC integration and reverse funds from the processor back to the subscriber.

Request

string

required

API key ID assigned to the POS integration

string

required

RFC3339 timestamp used in the HMAC signature

string

required

Hex-encoded HMAC-SHA256 of the request

Body Parameters

string

required

ID of transaction to refund

string

required

Amount to refund (can be partial)

string

required

Reason for refund

string

required

Admin/User ID authorizing refund

Response

boolean

Whether refund succeeded

string

Refund transaction ID

string

Formatted refunded amount

Examples

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/pos/refund\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://demo.api.vultlocal.com/api/v1/pos/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"
}

{
  "success": false,
  "error": "Transaction already fully refunded"
}

Errors

Status	Code	Description
400	Validation or business error	Invalid amount or refund not allowed
401	HMAC auth error	Missing/invalid `X-API-Key-ID`, `X-Timestamp`, or `X-Signature`
500	Internal error	Server error

Authorizations

Authorization

string

header

required

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

Body

application/json

Refund details

amount

string

required

Accepts decimal format like "150.00" or "150"

Example:

"150.00"

initiated_by

string

required

Example:

"admin-user-id"

original_transaction_id

string

required

Example:

"txn-uuid"

reason

string

required

Example:

"Customer returned goods"

Response

Refund processed

The response is of type object.

Verify Card

Lookup Card

​Request

​Body Parameters

​Response

​Examples

​Errors

Authorizations

Body

Response

Request

Body Parameters

Response

Examples

Errors