Skip to main content
This guide walks you through making your first payout against the Teel sandbox environment. Sandbox provider APIs don’t move real funds — perfect for end-to-end integration testing before you switch to production credentials.
1

Set your API key

Teel uses long-lived secret API keys (sk_live_… for production, sk_test_… for sandbox) presented as a bearer token. Same pattern as Stripe, OpenAI, Resend.Sandbox API keys are issued by the Teel onboarding team. Email support@teel.finance (or reach out to your dedicated onboarding contact) and we’ll send your sk_test_… key through an encrypted channel. The plaintext is shown exactly once at creation; afterwards only the first 12 characters are retrievable for identification.
Confirm the key works against the unauthenticated health endpoint and then against an authenticated read:
See the Authentication page for key format, scopes, rotation, and revocation.
2

Check coverage

The public /config/coverage endpoint returns the matrix of currencies, rails, directions, and amount bounds Teel can route. No auth required — partners can hit it from their integration server’s pre-flight checks before quoting.
Confirm your corridor (e.g. USD → PHP) is in the response before proceeding. See the Coverage page for the full schema.
3

Create a recipient

Register the counterparty who will receive the payout. Recipients carry one or more payment methods — bank accounts or wallet addresses — that resolve currency-by-currency to the right provider at execution time.
Request bodies are camelCase (isBusiness, businessName, paymentMethods); responses are snake_case. Save the id from the response — that’s your recipientId.The Idempotency-Key header is optional but recommended: a timeout-retry with the same key replays the cached response (24h window) instead of creating a duplicate recipient. See POST /recipients for every field.
4

Get a quote

Fetch the best available rate for your corridor. Quotes are short-lived (~minutes) and carry an opaque protocol token you’ll pass back at execution time to pin the route.
The response includes the exchange rate, fees, estimated delivery amount, a quoteId (use it to poll status in step 6), an opaque protocol route token (pass it back as routeProtocol at execution to pin this route), and the expiresAt timestamp. Use the quote before it expires.See the Quotes pages for the full quote families (onramp / offramp / fiat-to-fiat / fiat-to-stablecoin).
5

Execute the payout

Partners execute payouts through the RFQ (request-for-quote) endpoint. Re-send the corridor and amount from your quote, plus the routeProtocol token to pin the exact route you were quoted. Like recipient creation, this is Idempotency-Key-safe — Teel deduplicates retry attempts in a 24h window so a network timeout doesn’t double-spend.
The response includes the transactionId and initial status. The payout begins processing immediately.
6

Track status

Two options: poll the status endpoint, or subscribe a webhook URL.Poll:
Status moves through initiated → compliance_cleared → instructions_sent → collected → converting → settling → delivered (terminal: delivered or failed).Subscribe a webhook for production payout monitoring instead of polling. Teel POSTs every status change to your URL with an HMAC-SHA256 signature header you verify with the secret returned at subscription creation:
Today the subscribable events are payout.created and payout.status.updated — delivery and failure arrive as the status field inside payout.status.updated (terminal values delivered / failed), not as separate event types.The response includes the signing secret returned exactly once. Store it server-side. See the Webhooks guide for signature verification + retry semantics.For real-time updates without a public URL, a WebSocket endpoint is also available. Auth is in-band — connect, then send {"type":"auth","apiKey":"sk_test_..."} as the first frame:

​
Next steps

Authentication

Key format, scopes, rotation (7-day overlap), revocation, error responses.

Core concepts

Multi-provider architecture, quote engine, transaction lifecycle.

Coverage

Supported countries, currencies, rails, and amount bounds via /config/coverage.

Webhooks

Subscribe a URL, verify HMAC signatures, replay deliveries.

​
OpenAPI spec

Every endpoint above is documented in the machine-readable spec at /openapi.json (or /openapi.yaml). The same spec covers production — pick the matching servers[] entry on import. Use it with Postman, Insomnia, or openapi-generator-cli for a typed client in any language.