Refund transaction

Refund a transaction in your Blnk Ledger.

POST /refund-transaction/{transaction_id}

Queued refund

curl -X POST "http://localhost:5001/refund-transaction/{transaction_id}" \
  -H "X-blnk-key: <api-key>"

201 Queued

{
  "amount": 50,
  "amount_string": "50",
  "precision": 100,
  "precise_amount": 5000,
  "transaction_id": "txn_af70986c-fbdc-450a-bf81-c1af034ce840",
  "parent_transaction": "txn_b0468e80-5941-4ca8-b5d2-e44f4572926e",
  "source": "bln_f76360da-68db-410d-8a8b-1d960e2a766f",
  "destination": "bln_b1bd741e-eeb6-4dd4-a562-df35374bbaf9",
  "reference": "txn_b0468e80-5941-4ca8-b5d2-e44f4572926e_refund",
  "currency": "USD",
  "description": "Card payment on Stripe",
  "status": "QUEUED",
  "hash": "0b9c25fb5b00d6c71cb4ca87026bf6dc316e63353d3330deb588bd0b3d74dcc0",
  "allow_overdraft": false,
  "inflight": false,
  "created_at": "2024-11-26T09:33:35.265582042Z",
  "scheduled_for": "0001-01-01T00:00:00Z",
  "inflight_expiry_date": "0001-01-01T00:00:00Z",
  "inflight_commit_date": "0001-01-01T00:00:00Z"
}

If you’re using the auto-provisioned Enterprise Core instance included with your Production License deployment, set the base URL to: https://ENTERPRISE_PUBLIC_URL/core.

If you’re connecting to a different Core instance, use the publicly accessible base URL for that instance instead.

Authorization

If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>.

Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code.

See also: Scoped API keys and Secure your Blnk server.

Path

transaction_id · string · required

The original transaction ID from the lineage. Blnk resolves refundable records through parent lineage - use the ID returned when you recorded the transaction, or the split parent in meta_data.QUEUED_PARENT_TRANSACTION. Do not pass a VOID child’s ID.

Body

skip_queue · boolean · default: "false"

When true, processes the refund synchronously instead of placing it on the transaction queue. Requests without a body keep the default queued behavior.

dry_run · boolean · default: "false"

When true, Blnk projects the refund without writing anything and returns a preview. See Dry-run a transaction.

description · string

Narration for the refund. When omitted or empty, the refund copies the original transaction’s description.

Available in version 0.15.3 and later.

meta_data · object

Additional metadata for the refund. Blnk merges these keys onto the metadata inherited from the original transaction. Keys you send replace matching keys; other keys stay on the refund. An empty object is ignored. The original transaction is not modified.

Available in version 0.15.3 and later.

Response

Same JSON structure as Record a transaction

Queued refund

curl -X POST "http://localhost:5001/refund-transaction/{transaction_id}" \
  -H "X-blnk-key: <api-key>"

201 Queued

{
  "amount": 50,
  "amount_string": "50",
  "precision": 100,
  "precise_amount": 5000,
  "transaction_id": "txn_af70986c-fbdc-450a-bf81-c1af034ce840",
  "parent_transaction": "txn_b0468e80-5941-4ca8-b5d2-e44f4572926e",
  "source": "bln_f76360da-68db-410d-8a8b-1d960e2a766f",
  "destination": "bln_b1bd741e-eeb6-4dd4-a562-df35374bbaf9",
  "reference": "txn_b0468e80-5941-4ca8-b5d2-e44f4572926e_refund",
  "currency": "USD",
  "description": "Card payment on Stripe",
  "status": "QUEUED",
  "hash": "0b9c25fb5b00d6c71cb4ca87026bf6dc316e63353d3330deb588bd0b3d74dcc0",
  "allow_overdraft": false,
  "inflight": false,
  "created_at": "2024-11-26T09:33:35.265582042Z",
  "scheduled_for": "0001-01-01T00:00:00Z",
  "inflight_expiry_date": "0001-01-01T00:00:00Z",
  "inflight_commit_date": "0001-01-01T00:00:00Z"
}

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please contact us or join our Discord community.