API Reference

Base URL, headers, and every endpoint available today.

Every endpoint documented here is callable with a merchant API key. Provisioning and compliance operations are internal and deliberately excluded — if it is not listed in this reference, it is not part of the merchant API.

Base URL

https://api.spendin.app

All routes are versioned under /v1/. The version changes only on a breaking change to a published contract.

Required headers

Header	When	Notes
X-API-Key	Every request	See Authentication
Idempotency-Key	Every POST, PUT, PATCH	UUID v4. See Idempotency
X-Request-Id	Optional, recommended	Echoed back and into our logs. See Errors
Content-Type	Requests with a body	application/json

POST /v1/banks/resolve is the one exception to the idempotency rule. It is a POST only to keep an account number out of a query string; it writes nothing, so it needs no Idempotency-Key.

Conventions

All field names are snake_case, in both directions, with no casing transformation. Timestamps are ISO-8601 UTC. Every monetary amount is paired with a currency field sharing its prefix.

Status values (PENDING_PAYMENT, SUCCESSFUL) are uppercase. Webhook event types (payout.pending_payment) are lowercase and dotted. They are easy to confuse.

What’s available

Payouts

Create a payout, read one with its status timeline, and list them.

Payment instructions

Fetch the active settlement instruction for a payout.

Rates

Indicative rates, and executable quotes with a fixed TTL.

Banks

Institution directory and name enquiry on a destination account.

Inflows

Your settlements, matched and unmatched.

Outflows

Every dispatch attempt made against a payout.

Refunds

Refund destinations, and the history of money returned to you.

Webhooks

Configure your endpoint, rotate the secret, inspect deliveries.

Endpoint summary

Method	Path	Scope
POST	/v1/payouts	payouts:write
GET	/v1/payouts	payouts:read
GET	/v1/payouts/{id}	payouts:read
GET	/v1/payouts/{payout_id}/payment-instruction	payment_instructions:read
GET	/v1/payouts/{payout_id}/outflows	outflows:read
GET	/v1/payouts/{payout_id}/refunds	refunds:read
GET	/v1/rates	rates:read
POST	/v1/rates/quotes	rates:read
GET	/v1/rates/quotes/{id}	rates:read
POST	/v1/rates/quotes/{id}/accept	rates:read
GET	/v1/banks	identity:enquiry
POST	/v1/banks/resolve	identity:enquiry
GET	/v1/inflows	inflows:read
GET	/v1/inflows/{id}	inflows:read
GET	/v1/outflows/{id}	outflows:read
PUT	/v1/refund-destinations	refunds:manage
GET	/v1/refund-destinations	refunds:read
GET	/v1/refunds	refunds:read
GET	/v1/refunds/{id}	refunds:read
PUT	/v1/webhooks/config	webhooks:manage
GET	/v1/webhooks/config	webhooks:manage
POST	/v1/webhooks/config/rotate-secret	webhooks:manage
GET	/v1/webhooks/deliveries	webhooks:manage

Every operation declares its requirement as x-required-scopes. A key missing it gets 403 INSUFFICIENT_SCOPES, and the response names the scope it wanted.

Pagination

GET /v1/payouts, /v1/inflows, /v1/refunds, and /v1/webhooks/deliveries are cursor-paginated and return a { data, meta } envelope. Every other list endpoint returns a bare array. See Pagination.

No write endpoints for pipeline records

Inflows, outflows, payment instructions, and refunds are all system-generated. There is no way to create, mutate, or cancel one through the API — they are the record of what happened, and the only write you make is POST /v1/payouts.