RECIPIENT_NOT_WHITELISTED

What happened

You submitted a payout with purpose: intercompany but the destination bank account has no corresponding registered whitelist recipient for this customer. This returns HTTP 422 with error code RECIPIENT_NOT_WHITELISTED.

{
  "type": "RECIPIENT_NOT_WHITELISTED",
  "title": "Recipient Not Whitelisted",
  "status": 422,
  "detail": "No registered whitelist recipient matches the destination bank account for this customer.",
  "resolution": "Register the recipient via POST /v2/customers/:id/whitelist-recipients and wait for registered status before submitting the payout.",
  "docs": "/errors#recipient-not-whitelisted",
  "instance": "/v2/payouts",
  "correlationId": "corr_xyz789",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

Common causes

No registration submitted — the destination account has never been registered as a whitelist recipient 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

Recovery

1. Check existing registrations for the customer

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

Look for an entry with status: registered whose accountIdentifier matches the destination account number or IBAN. 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_abc123/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_abc123"]
  }'

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_abc123",
    "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_abc123",
    "virtualAccountId": "vac_abc123",
    "assetAmount": {"code": "USD", "amount": "5000.00"},
    "purpose": "intercompany",
    "destination": {
      "recipient": {
        "rail": "us",
        "type": "business",
        "legalName": "Acme Holdings LLC",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "accountType": "checking"
      }
    }
  }'

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 (customerId, accountNumber) → whitelistRecipientId and its status so you can gate payout submission on registered

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

Overview

Errors

Customers

Registered Addresses

Wallets

Wallet Signers

Signing Quorum

Virtual Accounts

Applications

Documents

Verifications

Signing Requests

Transactions

Payouts

Whitelist Recipients

Orders

RFIs

Webhook Endpoints

Webhook Deliveries

Webhook Event Types

Features

Customer Onboarding

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