Skip to main content
Use a customer account when the customer owns the endpoint. Use a recipient and destination when another person or business receives the funds. The recipient records who receives funds. The destination records where they receive them.

​
1. Create the recipient

Create an individual or business with POST /v3/customers/{customerId}/recipients. Send these headers:
Request headers
Request body
relationship describes how the recipient relates to your customer. Choose a value from the POST /v3/customers/{customerId}/recipients request schema. If you send other, do not add a companion free-text field. Swipelux ignores fields that the request schema does not define, so the text would not be stored. Include the address before creating a fiat destination. Store the returned recipient data.id as RECIPIENT_ID and retain its current status.

​
2. Add a destination

Create the endpoint with POST /v3/customers/{customerId}/recipients/{recipientId}/destinations. Use a new key for this intended destination:
Request headers
Pix and Pix Safe destinations receive BRL and need the customer’s ready Pix capability (pix_pooled). A Pix destination pays a Pix key: a CPF or CNPJ in digits only, a phone number as +55 followed by 10 or 11 digits, an email, or a random key. A Pix Safe destination pays a Brazilian bank account identified by the holder’s CPF or CNPJ in taxId, the bank’s 8-digit ISPB code in bankCode, the branch, and the account number with its check digit. Responses and webhooks return taxId masked to its last four digits. Swipelux validates bank identifiers such as IBANs, BICs, ABA routing numbers, and CPF or CNPJ numbers, including checksums, when you create a bank destination. Malformed values return 400 validation_error. These checks confirm format only, not that the account exists or who owns it. Use self_custodied only when the recipient controls the wallet. Follow the current API Reference variant when the wallet is held by another custodian. Store the returned destination data.id as DESTINATION_ID and retain its current status.

​
3. Wait for destination readiness

Read GET /v3/customers/{customerId}/recipients/{recipientId}/destinations/{destinationId} before creating a quote. Continue only when the current destination status permits the payout and its currency, method, and network match the intended movement. Recipient and destination statuses are independent. Use the dst_ destination ID in the payout quote. The rcp_ recipient ID identifies the owner record and is not a quote destination. Next, take the ready destination to Send funds.