Saved Recipients

Saved recipients store reusable destination details for Stabyl Pro withdrawal workflows and account management. They are address book records, not payment instructions. Production requires approved KYB to create or update a fiat recipient. Recipient lists remain readable and crypto-recipient management is unchanged. Development and staging skip the fiat-recipient KYB gate.

Endpoint	Purpose
`POST /partner/wallets/recipients`	Create a saved recipient
`GET /partner/wallets/recipients`	List saved recipients
`PATCH /partner/wallets/recipients/{recipient_id}`	Update recipient metadata
`DELETE /partner/wallets/recipients/{recipient_id}`	Delete a saved recipient

Fiat recipient creation should follow account verification with POST /partner/wallets/fiat/verify-account. Crypto recipients are saved addresses and metadata only.

Create a fiat recipient

curl "$STABYL_BASE_URL/partner/wallets/recipients" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "recipient_type": "fiat",
    "label": "Operations account",
    "currency": "NGN",
    "bank_code": "044",
    "bank_name": "Access Bank",
    "account_number": "0123456789",
    "account_name": "Example Recipient"
  }'

Stabyl verifies the bank code and account number. Use the verified account name returned by the API rather than assuming the submitted name is authoritative.

Create a crypto recipient

curl "$STABYL_BASE_URL/partner/wallets/recipients" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "recipient_type": "crypto",
    "label": "Main USDT recipient",
    "currency": "USDT",
    "chain": "tron",
    "crypto_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "country": "NGA"
  }'

{
  "status": "success",
  "data": {
    "id": "0197f1f0-0000-7000-8000-000000000002",
    "recipient_type": "crypto",
    "label": "Main USDT recipient",
    "currency": "USDT",
    "chain": "tron",
    "bank_code": null,
    "bank_name": null,
    "account_number": null,
    "account_name": null,
    "crypto_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "country": "NGA",
    "created_at": "2026-07-17T12:00:00Z",
    "updated_at": "2026-07-17T12:00:00Z"
  }
}

Recipient Types

Type	Typical fields	Recommended validation
Fiat	bank code, account number, account name, display label	Verify account before saving
Crypto	asset rail, chain, address, display label	Confirm route and address format before saving

Use clear labels that operators can recognize in Stabyl Pro. Avoid labels that only make sense inside one internal service.

Saved recipients do not initiate withdrawals through the API. Signed Partner withdrawal requests send destination details directly and do not accept a saved recipient_id.

Update or delete a recipient

curl "$STABYL_BASE_URL/partner/wallets/recipients/$RECIPIENT_ID" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{"label": "Primary USDT recipient"}'

curl "$STABYL_BASE_URL/partner/wallets/recipients/$RECIPIENT_ID" \
  -X DELETE \
  -H "X-Api-Key: $STABYL_API_KEY"

Lifecycle

Action	Notes
Create	Store validated details for future use
List	Show current saved recipients for account review
Update	Change metadata or supported editable fields
Delete	Remove a saved recipient from future selection

Recipient routes require X-Api-Key enabled for recipient management. Common failures include a key that is not permitted for the action, invalid account details, duplicate recipient details, or a recipient identifier that does not exist.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Create a fiat recipient

Create a crypto recipient

Recipient Types

Update or delete a recipient

Lifecycle

​Create a fiat recipient

​Create a crypto recipient

​Recipient Types

​Update or delete a recipient

​Lifecycle

Create a fiat recipient

Create a crypto recipient

Recipient Types

Update or delete a recipient

Lifecycle