Managing recipients

Overview

Recipients are the businesses or individuals you send payments to. When you create a recipient, Teel automatically provisions them across all of your active payment providers, so you can pay them through any available rail. Request bodies are camelCase (businessName, transferType, paymentMethods); responses are snake_case at the top level, with camelCase fields inside nested payment-method objects.

Destination types

A recipient’s transferType sets where their funds land:

`transferType`	Recipient receives	Payment method
`fiat`	Fiat in a bank account	Bank details (account number, routing/SWIFT, etc.)
`stablecoin`	Stablecoin in a wallet	Wallet address + network

Whether a stablecoin recipient is paid via a Stablecoin payout (you fund with fiat) or a Crypto payout (you fund with stablecoin) is decided when you execute the payout — not on the recipient.

Step 1: Get recipient requirements

Fetch the fields required to create a recipient, based on your active providers and currencies. The response is a dynamic schema you can render as a form.

curl https://api.teel.finance/recipients/requirements \
  -H "Authorization: Bearer $TEEL_API_KEY"

The schema adapts to your account — fields and required documents differ by currency and rail. Treat it as the source of truth for what to send in step 3 rather than hard-coding fields.

Step 2: Get wallet networks

If your recipient will receive stablecoins, fetch the supported wallet networks. The response is a JSON array:

curl https://api.teel.finance/recipients/wallet-networks \
  -H "Authorization: Bearer $TEEL_API_KEY"

[
  { "name": "ethereum", "displayName": "Ethereum", "chainId": 1 },
  { "name": "polygon", "displayName": "Polygon", "chainId": 137 },
  { "name": "arbitrum", "displayName": "Arbitrum", "chainId": 42161 },
  { "name": "base", "displayName": "Base", "chainId": 8453 }
]

Use the name value (e.g. polygon) as the rail on a wallet payment method.

Step 3: Create a recipient

Fiat recipient (bank account)

curl -X POST https://api.teel.finance/recipients \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "businessName": "Vendor Co",
    "email": "payments@vendorco.com",
    "country": "US",
    "transferType": "fiat",
    "paymentMethods": [
      {
        "type": "bank",
        "currency": "USD",
        "rail": "ach",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "accountType": "checking"
      }
    ]
  }'

Stablecoin recipient (wallet)

curl -X POST https://api.teel.finance/recipients \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "businessName": "Crypto Vendor",
    "email": "treasury@cryptovendor.com",
    "country": "SG",
    "transferType": "stablecoin",
    "paymentMethods": [
      {
        "type": "wallet",
        "currency": "USDC",
        "rail": "polygon",
        "walletAddress": "0xRecipientWalletAddress"
      }
    ]
  }'

A recipient can carry multiple payment methods — e.g. wallets on several chains, or a bank account plus a wallet. Add more objects to paymentMethods. Save the id (a UUID) 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.

Step 4: Auto-provisioning

When a recipient is created, Teel provisions them across all of your active payment providers in the background, so the recipient is ready to receive payments through any rail your providers support — no extra setup needed.

Step 5: Retry failed provisioning

If provisioning fails for a provider (e.g. a transient error), retry it:

curl -X POST https://api.teel.finance/recipients/{recipientId}/retry \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Step 6: Get recipient details

Retrieve a recipient with their per-provider counterparty status:

curl https://api.teel.finance/recipients/{recipientId}/with-counterparty \
  -H "Authorization: Bearer $TEEL_API_KEY"

{
  "id": "8f3c2a91-4e5b-4d8c-9a1f-3e2b1c4d5e6f",
  "business_name": "Vendor Co",
  "email": "payments@vendorco.com",
  "country": "US",
  "transfer_type": "fiat",
  "status": "accepted",
  "created_at": "2026-03-10T10:00:00Z"
}

Adding and removing payment methods

You can add payment methods to an existing recipient, or remove one, without recreating the recipient.

Add a payment method

curl -X POST https://api.teel.finance/recipients/{recipientId}/payment-methods \
  -H "Authorization: Bearer $TEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "wallet",
    "currency": "USDC",
    "rail": "arbitrum",
    "walletAddress": "0xArbitrumAddress"
  }'

The new payment method is provisioned across your active providers in the background, the same way it is at recipient creation.

Remove a payment method

curl -X DELETE https://api.teel.finance/recipients/{recipientId}/payment-methods/{paymentMethodId} \
  -H "Authorization: Bearer $TEEL_API_KEY"

Both routes require the recipients:write scope.

Getting Started

Guides

Managing recipients

Overview

Destination types

Step 1: Get recipient requirements

Step 2: Get wallet networks

Step 3: Create a recipient

Fiat recipient (bank account)

Stablecoin recipient (wallet)

Step 4: Auto-provisioning

Step 5: Retry failed provisioning

Step 6: Get recipient details

Adding and removing payment methods

Add a payment method

Remove a payment method

​Overview

​Destination types

​Step 1: Get recipient requirements

​Step 2: Get wallet networks

​Step 3: Create a recipient

​Fiat recipient (bank account)

​Stablecoin recipient (wallet)

​Step 4: Auto-provisioning

​Step 5: Retry failed provisioning

​Step 6: Get recipient details

​Adding and removing payment methods

​Add a payment method

​Remove a payment method

Overview

Destination types

Step 1: Get recipient requirements

Step 2: Get wallet networks

Step 3: Create a recipient

Fiat recipient (bank account)

Stablecoin recipient (wallet)

Step 4: Auto-provisioning

Step 5: Retry failed provisioning

Step 6: Get recipient details

Adding and removing payment methods

Add a payment method

Remove a payment method