Execute a payout - Teel API

POST

api

rfq

execute

Execute a payout

curl --request POST \
  --url https://api.example.com/api/rfq/execute \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromCurrency": "<string>",
  "toCurrency": "<string>",
  "amount": 123,
  "recipientId": "<string>",
  "targetAmount": 123,
  "recipientPaymentMethodId": "<string>",
  "routeProtocol": "<string>",
  "paymentPurpose": "<string>",
  "reference": "<string>",
  "supportingDocumentKey": "<string>"
}
'

{
  "success": true,
  "data": {
    "payoutId": "8b1a4c1d-7a3c-4a08-94ad-9f1ef1e0c3a2",
    "quoteId":  "4c2b7e8f-3a3c-4a08-94ad-1234567890ab",
    "status": "accepted",
    "toAmount": 4425.00,
    "partnerFxRate": 4.4250,
    "effectiveRate": 4.4070,
    "fees": { "teelFee": 4.05, "teelFeeBps": 40, "partnerFee": 0, "gasFee": 0 },
    "bankingInstructions": {
      "accountNumber": "1234567890",
      "bankName": "Maybank",
      "swiftCode": "MBBEMYKL"
    }
  }
}

Lock + start a payout in one call. Pick the matching tab — shapes differ by corridor. Response: { "success": true, "data": { … } }.

Scope payouts:write · rate-limited

Headers

Authorization

string

required

API key.

Idempotency-Key

string

Optional. 8–255 url-safe characters. 24h replay window; mismatched bodies on the same key return 409 IDEMPOTENCY_KEY_REUSED.

Common fields

fromCurrency

string

required

Source currency. ISO 4217 for fiat, ticker for stablecoin.

toCurrency

string

required

Destination currency.

amount

number

required

Source amount. Must be > 0.

recipientId

string

required

UUID from POST /recipients.

targetAmount

number

Exact-output target. When set, sizes amount upstream so the recipient receives exactly this much.

recipientPaymentMethodId

string

UUID of the recipient PM, when more than one exists.

routeProtocol

string

Opaque route token (rt_…) from a /quotes/* call. Pins the route.

paymentPurpose

string

Partner-side classification (e.g. salary).

reference

string

Free-text reference echoed back on reads.

supportingDocumentKey

string

S3 key for an attached supporting document. Required by some compliance-bearing onramp flows.

Request body

Switch tabs for the type-specific fields and response shape.

Fiat-to-fiat
Stablecoin-to-fiat
Onramp (fiat → stablecoin)

Send fiat from your stored payment method; recipient receives fiat.

userPaymentMethodId

string

required

UUID of your funding source.

Response

payoutId

string

UUID of the new payout. Use with GET /payouts/{id}.

quoteId

string

UUID of the locked quote. Use with GET /rfq/status/{quoteId}.

status

string

Hard-coded accepted on success.

toAmount

number

Destination amount the recipient will receive.

partnerFxRate

number

Quoted FX rate, pre-fees.

effectiveRate

number

Effective rate net of fees.

fees

object

Per-payout fee breakdown — see Fees.

bankingInstructions

object

Map of string → string describing where to send the source fiat. Keys vary by rail (accountNumber, bankName, swiftCode, etc.).

{
  "success": true,
  "data": {
    "payoutId": "8b1a4c1d-7a3c-4a08-94ad-9f1ef1e0c3a2",
    "quoteId":  "4c2b7e8f-3a3c-4a08-94ad-1234567890ab",
    "status": "accepted",
    "toAmount": 4425.00,
    "partnerFxRate": 4.4250,
    "effectiveRate": 4.4070,
    "fees": { "teelFee": 4.05, "teelFeeBps": 40, "partnerFee": 0, "gasFee": 0 },
    "bankingInstructions": {
      "accountNumber": "1234567890",
      "bankName": "Maybank",
      "swiftCode": "MBBEMYKL"
    }
  }
}

Send stablecoin from your wallet; recipient receives fiat. The response carries escrow deposit instructions — your wallet must send the source stablecoin to escrowAddress.

walletAddress

string

required

Source wallet address.

Response

payoutId

string

UUID of the new payout.

quoteId

string

UUID of the locked quote.

status

string

Always awaiting_escrow_deposit until the deposit lands.

toAmount

number

Destination fiat amount.

partnerFxRate

number

Quoted FX rate, pre-fees.

effectiveRate

number

Effective rate net of fees.

fees

object

Per-payout fee breakdown — see Fees.

escrowAddress

string

On-chain address your wallet must send the source stablecoin to.

depositAmountAtomic

string

Atomic-units integer string — parse with BigInt. JSON numbers lose precision for 18-decimal tokens. Example: "300000" = 0.3 USDC at 6 decimals.

tokenAddress

string

ERC-20 contract address of the source stablecoin.

chainId

integer

EVM chain id of the deposit address.

{
  "success": true,
  "data": {
    "payoutId": "8b1a4c1d-7a3c-4a08-94ad-9f1ef1e0c3a2",
    "quoteId":  "4c2b7e8f-3a3c-4a08-94ad-1234567890ab",
    "status": "awaiting_escrow_deposit",
    "toAmount": 4425.00,
    "partnerFxRate": 4.4250,
    "effectiveRate": 4.4070,
    "fees": { "teelFee": 0.91, "teelFeeBps": 40, "partnerFee": 0, "gasFee": 0.05 },
    "escrowAddress": "0xAbcDef0123456789AbcDef0123456789AbcDef01",
    "depositAmountAtomic": "227250000",
    "tokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "chainId": 137
  }
}

After the response: your wallet sends depositAmountAtomic of tokenAddress to escrowAddress on chainId. The engine auto-detects the transfer; if it misses, fall back to POST /rfq/confirm-escrow-deposit with the tx hash.

Send fiat from your stored PM; recipient receives stablecoin on-chain.

userPaymentMethodId

string

required

UUID of your funding source.

Response

payoutId

string

UUID of the new payout.

quoteId

string

UUID of the locked quote.

status

string

Passed through from the onramp route.

toAmount

number

Destination stablecoin amount.

partnerFxRate

number

Quoted FX rate, pre-fees.

effectiveRate

number

Effective rate net of fees.

fees

object

Per-payout fee breakdown — see Fees.

paymentUrl

string

Hosted payment page — redirect the user here to complete the onramp.

bankingInstructions

object

When the rail settles by bank transfer instead of hosted page. Mutually exclusive with paymentUrl.

{
  "success": true,
  "data": {
    "payoutId": "8b1a4c1d-7a3c-4a08-94ad-9f1ef1e0c3a2",
    "quoteId":  "4c2b7e8f-3a3c-4a08-94ad-1234567890ab",
    "status": "pending",
    "toAmount": 990.50,
    "partnerFxRate": 1.0,
    "effectiveRate": 0.9905,
    "fees": { "teelFee": 9.50, "teelFeeBps": 95, "partnerFee": 0, "gasFee": 0 },
    "paymentUrl": "https://pay.example.com/sess_abc123"
  }
}

Fees

fees.teelFee

number

Teel’s fee, in fromCurrency.

fees.teelFeeBps

integer

Teel’s fee in basis points (1 bp = 0.01%).

fees.partnerFee

number

Your markup. 0 unless configured.

fees.gasFee

number

On-chain gas (S2F / stablecoin flows).

Errors

Status	Code	When
`400`	`INVALID_JSON` / `INVALID_PARAMETER`	Body malformed, required field missing, or a UUID doesn’t belong to your account.
`401`	`UNAUTHORIZED`	Missing or invalid key.
`403`	`FORBIDDEN`	Key lacks `payouts:write`.
`409`	`IDEMPOTENCY_KEY_REUSED` / `IDEMPOTENCY_REQUEST_IN_FLIGHT`	Idempotency conflict — back off per `Retry-After` for in-flight.
`429`	`RATE_LIMITED`	Per-key rate limit.

Next steps

Poll GET /rfq/status/{quoteId} or — preferred — subscribe to payout.status.updated and payout.delivered via Webhooks.

Execute a batch of payoutsLock and execute N payouts that share a source currency, in one call.

Execute a payout

curl --request POST \
  --url https://api.example.com/api/rfq/execute \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromCurrency": "<string>",
  "toCurrency": "<string>",
  "amount": 123,
  "recipientId": "<string>",
  "targetAmount": 123,
  "recipientPaymentMethodId": "<string>",
  "routeProtocol": "<string>",
  "paymentPurpose": "<string>",
  "reference": "<string>",
  "supportingDocumentKey": "<string>"
}
'

{
  "success": true,
  "data": {
    "payoutId": "8b1a4c1d-7a3c-4a08-94ad-9f1ef1e0c3a2",
    "quoteId":  "4c2b7e8f-3a3c-4a08-94ad-1234567890ab",
    "status": "accepted",
    "toAmount": 4425.00,
    "partnerFxRate": 4.4250,
    "effectiveRate": 4.4070,
    "fees": { "teelFee": 4.05, "teelFeeBps": 40, "partnerFee": 0, "gasFee": 0 },
    "bankingInstructions": {
      "accountNumber": "1234567890",
      "bankName": "Maybank",
      "swiftCode": "MBBEMYKL"
    }
  }
}

​Headers

​Common fields

​Request body

​Response

​Response

​Response

​Fees

​Errors

​Next steps

Headers

Common fields

Request body

Response

Response

Response

Fees

Errors

Next steps