spout

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
Refund flow from paid charge to pending refund

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

FieldRequired?Description
amountYesRefund amount (same units as the original charge)
transaction_idYesMongo _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

MethodPathNotes
GET/api/v1/refundList refunds for the authenticated merchant
GET/api/v1/refund/:idSingle refund by id
PATCH/api/v1/refund/:idUpdate 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

  1. Keep the payment Mongo _id from your transaction list / initialize follow-up (this is transaction_id).
  2. Create refund → store requestId from the response for support / observability.
  3. Poll GET /api/v1/refund/:id until status moves off pending, or update via dashboard PATCH.
  4. Use the same Idempotency-Key on retries so you do not double-create.