Recipients (third-party payments)

Most withdrawals send funds to your own bank or wallet. But you may also need to pay out to a third party — a customer, vendor, or counterparty. In Blacksheep these are modelled as recipient external accounts: external accounts that belong to a different person or entity than the account holder.

When to use this

• Marketplaces paying sellers
• Payroll / contractor disbursements
• Refunds to a customer's chosen account
• Any disbursement flow where the destination is not your treasury

Creating a recipient

Recipients are created as external accounts with the third party's details. Use the dashboard or the (session-authenticated) creation endpoints to add them. Each recipient external account has:

• The third party's details — account_name and routing details for banks, address for wallets
• A type — the account kind (BANK_ACCOUNT or WEB3), with the payment rail in metadata.type (e.g. AUD_NPP, evm)
• An id you pass as external_account_id when paying out

Paying out to a recipient

Identical to any other withdrawal — pass the recipient's external_account_id:

POST /transaction.submitWithdraw
Content-Type: application/json

{
    "external_account_id": "b21189d4-e549-4d77-b76b-85bfbb45d42d",
    "currency_out": { "value": "75000", "code": "AUD", "decimals": 2 },
    "metadata": { "description": "Invoice INV-99" }
}

The metadata field accepts a single free-text description (the allowlist is strict — other keys are rejected). Use it to carry a short correlation note between the Blacksheep transaction and the underlying obligation.

Compliance considerations

Third-party payouts may invoke additional checks (KYB on the recipient, sanctions screening, transaction monitoring). Failed checks surface as FAILED transactions — handle these in your UI so the operator can take corrective action.

Audit-relevant fields on every recipient transaction:

• external_account_metadata — a snapshot of the destination's details (e.g. account_name) at time of payout
• the metadata.description you attached

These appear on transaction.get and on transaction.created / transaction.updated webhook payloads.