RECIPIENT_NOT_WHITELISTED

What happened

You submitted a payout with purpose: intercompany but the destination has no whitelist proof for this customer. This returns HTTP 422 with error code RECIPIENT_NOT_WHITELISTED. Which proof the payout needs depends on the destination:

Destination	Proof required	Where you register it
A bank account	A `registered` whitelist recipient matching the destination bank details	`POST /v2/customers/:id/whitelist-recipients` on the `us`, `swift` or `sepa` rail
The customer’s own crypto wallet	A `registered` `self_custody` registered address matching `chain` + `address`, and `attestation.custody: "self"` on the payout	`POST /v2/customers/:id/wallets/registered-addresses`
A group entity’s crypto wallet	A `registered` whitelist recipient on the `crypto` rail with `relationship: group_entity`, matching `chain` + `address`, and `attestation.custody: "third_party"` on the payout	`POST /v2/customers/:id/whitelist-recipients` with `rail: "crypto"`

The two crypto rows are not interchangeable. attestation.custody names who owns the destination, so "self" against a group-entity whitelist entry is refused, and "third_party" against a self_custody registered address is refused.

{
  "type": "RECIPIENT_NOT_WHITELISTED",
  "title": "Recipient Not Whitelisted",
  "status": 422,
  "detail": "purpose=intercompany requires whitelist proof for this destination: a registered whitelist recipient, or a registered self-custody wallet address.",
  "resolution": "For a bank recipient, register via POST /v2/customers/{customerId}/whitelist-recipients and wait for the whitelist_recipient.registered webhook. For the customer's own wallet, register the address via POST /v2/customers/{customerId}/wallets/registered-addresses with type=self_custody (synchronous) and send attestation.custody=self. For a group entity's wallet, register it via POST /v2/customers/{customerId}/whitelist-recipients with rail=crypto and relationship=group_entity, wait for the same webhook, and send attestation.custody=third_party with the recipient's identity fields. Then resubmit under the same idempotency key.",
  "docs": "/errors#recipient-not-whitelisted",
  "instance": "/v2/payouts",
  "correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

Common causes

No registration submitted — the destination has never been registered for this customer
Registration still in review — a registration exists but its status is pending_review, not registered
Registration rejected or revoked — the entry was declined or cancelled and no active replacement exists
Wrong attestation.custody on a crypto payout — a registration exists, but the payout declares the other owner. Send "self" against a self_custody registered address and "third_party" against a group_entity whitelist recipient

Recovery

1. Check existing registrations for the customer

curl -X GET https://api.conduit.financial/v2/customers/cus_034A0gCCVsxdV2PjHLx9k1/whitelist-recipients \
  -H "x-api-key: YOUR_API_KEY"

Look for an entry with status: registered whose coordinates match the destination — accountNumber and routingNumber on a us entry, iban or bic + accountNumber on a swift entry, iban on a sepa entry, chain + address on a crypto entry. For the customer’s own wallet, check GET /v2/customers/:id/wallets/registered-addresses instead. 2. If no registration exists, submit one Upload evidence documents first (ownership chart, inter-company agreement, or bank statement):

curl -X POST https://api.conduit.financial/v2/documents \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@ownership-chart.pdf;type=application/pdf" \
  -F "purpose=transaction_support"

Then register the recipient:

curl -X POST https://api.conduit.financial/v2/customers/cus_034A0gCCVsxdV2PjHLx9k1/whitelist-recipients \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: NEW_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "us",
    "routingNumber": "021000021",
    "accountNumber": "1234567890",
    "legalName": "Acme Holdings LLC",
    "relationship": "group_entity",
    "evidenceDocumentIds": ["doc_034A0gCCW6w2ubcipmRoY8"]
  }'

Registering a group entity's crypto wallet instead

Same endpoint, same evidence documents, same review. The crypto rail identifies the wallet by chain plus address, and relationship must be group_entity — self is rejected, because your customer’s own wallet belongs in the registered addresses register.

curl -X POST https://api.conduit.financial/v2/customers/cus_034A0gCCVsxdV2PjHLx9k1/whitelist-recipients \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: NEW_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "crypto",
    "chain": "ethereum",
    "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
    "legalName": "Acme Holdings LLC",
    "relationship": "group_entity",
    "evidenceDocumentIds": ["doc_034A0gCCW6w2ubcipmRoY8"]
  }'

3. Wait for compliance review The registration starts in pending_review. Conduit will notify you via webhook when the review is complete:

{
  "type": "whitelist_recipient.registered",
  "data": {
    "whitelistRecipientId": "wlr_034A0jdUHB1TtoSuXzAg19",
    "status": "registered"
  }
}

Do not poll for status. Listen for the whitelist_recipient.registered or whitelist_recipient.rejected webhook events.

4. Once registered, resubmit the payout

curl -X POST https://api.conduit.financial/v2/payouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $SAME_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
    "virtualAccountId": "vac_034A0gCCW1I7ZiTVLb0G7I",
    "assetAmount": {"code": "USD", "amount": "5000.00"},
    "purpose": "intercompany",
    "destination": {
      "type": "fiat",
      "rail": "fedwire",
      "recipient": {
        "type": "business",
        "legalName": "Acme Holdings LLC",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "accountType": "checking"
      }
    }
  }'

Resubmitting a crypto payout to a group entity

The whitelist entry gates the destination; the payout still carries the full recipient inline. attestation.custody must be third_party, and a third_party crypto recipient carries the identity fields for its type (legalName + countryOfRegistration for a business, firstName + lastName + countryOfCitizenship for an individual).

curl -X POST https://api.conduit.financial/v2/payouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $SAME_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_034A0gCCVsxdV2PjHLx9k1",
    "assetAmount": {"code": "USDC", "chain": "ethereum", "amount": "5000.000000"},
    "purpose": "intercompany",
    "destination": {
      "type": "crypto",
      "recipient": {
        "chain": "ethereum",
        "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
        "attestation": { "custody": "third_party" },
        "type": "business",
        "legalName": "Acme Holdings LLC",
        "countryOfRegistration": "USA"
      }
    }
  }'

Resubmit under the same Idempotency-Key as the rejected attempt. The 422 is returned before any payout is created, so the key is safe to reuse — and reusing it is what prevents a duplicate: if a later response is lost, replaying the same key returns the one accepted payout instead of creating a second one. Rotating to a new key on resubmit risks a double payout.

Prevention

Register recipients ahead of time — whitelist registration requires compliance review; submit the registration well before you intend to send funds
Listen for whitelist_recipient.registered — trigger your payout flow from the webhook, not from a timer or poll
Track registration state in your system — maintain a local map of the destination coordinates ((customerId, accountNumber) for a bank account, (customerId, chain, address) for a wallet) → whitelistRecipientId and its status, so you can gate payout submission on registered
Pin attestation.custody to the register you used — "self" for a self_custody registered address, "third_party" for a group_entity crypto whitelist recipient

POST /v2/customers/:id/whitelist-recipients — register a recipient
GET /v2/customers/:id/whitelist-recipients — list recipients and check status
POST /v2/payouts — submit a payout
Registered Addresses — register the customer’s own wallet address

Overview

Errors

Customers

Registered Addresses

Wallets

Wallet Signers

Signing Quorum

Virtual Accounts

Applications

Documents

Verifications

Signing Requests

Transactions

Payouts

RFIs

Whitelist Recipients

Orders

Quotes

Webhook Endpoints

Webhook Deliveries

Webhook Event Types

Features

Customer Onboarding

Markup

Sandbox

RECIPIENT_NOT_WHITELISTED

What happened

Common causes

Recovery

Prevention

​What happened

​Common causes

​Recovery

​Prevention

​Related endpoints

What happened

Common causes

Recovery

Prevention

Related endpoints