Refund a payment

curl --request POST \ --url https://api.sandpay.dev/v1/payments/{id}/refund \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "amount": 500, "reference": "<string>", "description": "<string>" } '

{ "tx_id": "TX_RF01A2B3", "amount": 500, "parent_tx_id": "TX_8K3M9F", "refunded_total": 500, "refundable_remaining": 0, "merchant_balance_after": 123, "recipient_balance_after": 123, "idempotent": true }

Autorisations

Authorization

string

header

requis

API key in format sp_sk_test_... or sp_sk_live_....

Paramètres de chemin

string

requis

Transaction id of the original collection, e.g. TX_8K3M9F.

Pattern: ^TX_[A-Z0-9]+$

Corps

application/json

amount

integer

Amount in minor units to refund. Omit for a full refund of the remaining refundable (original amount − prior refunds).

Plage requise: x >= 1

Exemple:

500

reference

string

Optional idempotency reference. Auto-generated when omitted.

Required string length: 1 - 80

description

string

Optional free-form description (max 200 chars).

Maximum string length: 200

Réponse

Refund created (status SUCCESS or INSUFFICIENT_FUNDS).

tx_id

string

requis

Transaction id of the refund.

Exemple:

"TX_RF01A2B3"

type

enum<string>

requis

Options disponibles:

refund

status

enum<string>

requis

Final settlement status.

Options disponibles:

SUCCESS,

PIN_INVALID,

INSUFFICIENT_FUNDS,

TIMEOUT,

ACCOUNT_BLOCKED,

USER_CANCELLED,

UNKNOWN_MSISDN,

LIMIT_EXCEEDED,

SERVICE_UNAVAILABLE,

DUPLICATE_REFERENCE,

PENDING

amount

integer

requis

Amount refunded (minor units).

Plage requise: x >= 1

Exemple:

500

parent_tx_id

string

requis

The original collection this refund reverses.

Exemple:

"TX_8K3M9F"

refunded_total

number

Total successfully refunded against the parent, including this refund.

Exemple:

500

refundable_remaining

number

Refundable amount still remaining after this refund.

Exemple:

0

merchant_balance_after

number

Merchant float after the refund.

recipient_balance_after

number | null

Recipient SIM balance after the credit, or null.

idempotent

boolean

True when this refund already existed (idempotent replay).