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 a recipient is an account that holds the third party's details, with one or more external accounts attached as payout destinations.

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

Call account.recipient.create with the third party's details. Only metadata.name is required; email, phone_number, and business_info are optional.

POST /account.recipient.create
Content-Type: application/json

{
    "metadata": {
        "name": "Acme Pty Ltd",
        "email": "accounts@acme.example"
    }
}

The response carries the recipient's id. Keep it — you need it to attach a destination.

Adding a payout destination

Call account.external.bank.add with recipient_id set to the recipient's id. Without recipient_id, the bank account is added to your own account instead.

POST /account.external.bank.add
Content-Type: application/json

{
    "recipient_id": "9f2c1a55-3d6e-4b71-8f0a-2c7d51e9b8a4",
    "type": "AUD_NPP",
    "account_name": "Acme Pty Ltd",
    "account_number": "123456789",
    "national_clearing_code": "062000"
}

The response carries the external account's id — that is the external_account_id you pay out to. Required fields vary by rail: type selects the rail (AUD_NPP, USD_ACH, GBP_FPS, EUR_SEPA, and so on) and determines which routing fields the request must carry.

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.

Reading recipients

Editing and deleting a recipient are dashboard-only. A recipient with transactions against it cannot be deleted.

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.