Refunds
Refund a completed charge by its payment transaction_id (Mongo document id). Routes live under /api/v1/refund and require a dashboard JWT (Authorization: Bearer <token>), not the merchant secret key used for Accept Payment.
Refund from paid transactionScreenshot
Track: paid charge → POST /refund/create → refund status pending → GET /refund/:id.
Why a screenshot helps: Shows operators where amount and transaction_id come from in the dashboard before they call the API.
Authentication
Login (get JWT)
1curl -X POST https://api.spoutpay.com/api/v1/auth/login \
2 -H "Content-Type: application/json" \
3 -d '{
4 "email": "merchant@example.com",
5 "password": "••••••••"
6 }'
7# → { "status": 200, "data": { "token": "<jwt>", "user": { ... } } }Send Authorization: Bearer <token> on every refund call. Recommended: Idempotency-Key (falls back to transaction_id if omitted) and X-Request-Id for support correlation.
Create refund — POST /api/v1/refund/create
| Field | Required? | Description |
|---|---|---|
amount | Yes | Refund amount (same units as the original charge) |
transaction_id | Yes | Mongo _id of the payment to refund. Must be unique across refunds (second create for the same id fails validation). |
Request body
1{
2 "amount": 1000,
3 "transaction_id": "65f1a2b3c4d5e6f7081920ab"
4}1curl -X POST https://api.spoutpay.com/api/v1/refund/create \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer <dashboard_jwt>" \
4 -H "Idempotency-Key: refund-order_1001" \
5 -H "X-Request-Id: 8a2f...." \
6 -d '{
7 "amount": 1000,
8 "transaction_id": "65f1a2b3c4d5e6f7081920ab"
9 }'Success response (200)
Message text matches the live API spelling (Refund Crrated successfully.).
1{
2 "status": 200,
3 "data": {
4 "message": "Refund Crrated successfully."
5 },
6 "requestId": "...",
7 "responseId": "..."
8}Duplicate / validation error
1{
2 "status": 400,
3 "error": "...",
4 "message": "Refund Transaction already exists."
5}List, get, update
| Method | Path | Notes |
|---|---|---|
GET | /api/v1/refund | List refunds for the authenticated merchant |
GET | /api/v1/refund/:id | Single refund by id |
PATCH | /api/v1/refund/:id | Update amount, status, and/or transaction_id |
GET /:id response
1{
2 "status": 200,
3 "data": {
4 "_id": "66a1...",
5 "user_id": "65e9...",
6 "amount": "1000",
7 "transaction_id": "65f1a2b3c4d5e6f7081920ab",
8 "status": "pending",
9 "createdAt": "2026-11-18T17:00:00.000Z",
10 "updatedAt": "2026-11-18T17:00:00.000Z"
11 },
12 "requestId": "..."
13}PATCH body
1{
2 "amount": 500,
3 "status": "approved",
4 "transaction_id": "65f1a2b3c4d5e6f7081920ab"
5}How to track a refund
- Keep the payment Mongo
_idfrom your transaction list / initialize follow-up (this istransaction_id). - Create refund → store
requestIdfrom the response for support / observability. - Poll
GET /api/v1/refund/:iduntilstatusmoves offpending, or update via dashboardPATCH. - Use the same
Idempotency-Keyon retries so you do not double-create.