Refunds

A refund returns funds for a transaction that has already been captured. With Tokeflow you issue refunds against a single, normalized API — the orchestration layer relays the request to the connected payment provider, tracks the result, and reflects it back on both the refund record and the parent transaction.

Tokeflow standardizes refunds across providers: one request shape, one status lifecycle, one reconciliation model. The connected payment provider performs the actual movement of funds.

How refunds work

Every refund is a child of a captured transaction. You can refund the full remaining captured amount, or issue several partial refunds over time until the transaction is fully refunded.

• Full refund — omit amount to refund the entire remaining captured amount.
• Partial refund — pass amount (in minor units) to refund less than the remaining captured amount. The remaining balance stays captured and can be refunded later.
• Multiple partial refunds — repeat partial refunds until the remaining captured amount reaches zero. Each call creates a new refund record.

A refund can only be initiated when the parent transaction is in authorized or refund_pending status. Once a refund is initiated, the transaction moves to refund_pending while the provider confirms the result.

Refund lifecycle

A refund record has its own status, independent of the parent transaction.

How refund status maps to the transaction

The parent transaction reflects the aggregate refund state:

• While any refund is pending, the transaction is refund_pending.
• When the captured amount has been fully refunded, the transaction becomes refunded.
• When only part of the captured amount has been refunded, the transaction becomes partially_refunded.

Endpoints

POST/api/v1/transactions/:id/refund

Refund a captured transaction. Supports full and multiple partial refunds.

Refund a previously captured transaction. Omit amount for a full refund of the remaining captured amount, or pass amount for a partial refund.

Path parameters

Query parameters

Body

curl -X POST "https://api.tokeflow.com/api/v1/transactions/tx_777/refund" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9a7e-2b4d-4e0a-9c6f-7d1e2a3b4c5d" \
  -d '{
    "amount": 5000,
    "reason": "requested_by_customer"
  }'

For a full refund, omit amount:

curl -X POST "https://api.tokeflow.com/api/v1/transactions/tx_777/refund" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "duplicate" }'

Response 200 OK

The response confirms the refund was accepted and echoes the reconciliation totals on the transaction. Money fields are in minor units.

{
  "success": true,
  "data": {
    "id": "tx_777",
    "refund_id": "ref_abc123",
    "status": "refund_pending",
    "amount_captured": 15000,
    "amount_refunded": 5000,
    "total_refunded": 5000,
    "updated_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c2a1b9d4e",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET/api/v1/transactions/:id/refunds

List all refunds for a transaction, newest first.

Use this to view refund history, check the status of partial refunds, or correlate refund events with webhook notifications.

Path parameters

Query parameters

curl "https://api.tokeflow.com/api/v1/transactions/tx_777/refunds?page=1&limit=20" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Accept: application/json"

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "ref_def456",
      "payment_transaction_id": "tx_777",
      "amount": 4000,
      "currency": "BRL",
      "status": "succeeded",
      "reason": "requested_by_customer",
      "provider_refund_id": "rfnd_7Qx9KpL2",
      "failure_reason": null,
      "created_at": "2026-01-15T13:10:00.000Z",
      "updated_at": "2026-01-15T13:11:42.000Z"
    },
    {
      "id": "ref_abc123",
      "payment_transaction_id": "tx_777",
      "amount": 5000,
      "currency": "BRL",
      "status": "succeeded",
      "reason": "requested_by_customer",
      "provider_refund_id": "rfnd_3Mt0VbN8",
      "failure_reason": null,
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:31:05.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_5a2f7b1c8e0d",
  "timestamp": "2026-01-15T13:12:00.000Z"
}

GET/api/v1/transactions/:id/refunds/:refundId

Retrieve a single refund.

Use this in support flows — for example, to inspect a refund after a webhook notification, or when a refund fails or takes time to settle.

Path parameters

Query parameters

curl "https://api.tokeflow.com/api/v1/transactions/tx_777/refunds/ref_abc123" \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Accept: application/json"

Response 200 OK

{
  "success": true,
  "data": {
    "id": "ref_abc123",
    "payment_transaction_id": "tx_777",
    "amount": 5000,
    "currency": "BRL",
    "status": "succeeded",
    "reason": "requested_by_customer",
    "provider_refund_id": "rfnd_3Mt0VbN8",
    "failure_reason": null,
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:31:05.000Z"
  },
  "request_id": "req_9c4e1d7a2b6f",
  "timestamp": "2026-01-15T12:32:00.000Z"
}

The refund object

Errors

Refund endpoints use the standard error envelope.

{
  "error": {
    "type": "business_rule_error",
    "code": "TRANSACTION_NOT_REFUNDABLE",
    "message": "Transaction must be in 'authorized' or 'refund_pending' status to be refunded.",
    "details": { "current_status": "failed" },
    "request_id": "req_2b8d4f6a1c3e",
    "timestamp": "2026-01-15T12:40:00.000Z"
  }
}

Related

• Transactions — create, capture, and inspect transactions.
• Webhooks — receive transaction.refunded and transaction.partially_refunded events.
• Idempotency & rate limits — make refund requests safe to retry.
• Errors — error envelope and types.