Receivers

Create, list, update and remove the individuals and companies you pay, with the fields the server enforces and the update traps

A receiver is the person or company you pay. Bank accounts and beneficiary wallets are attached to a receiver. Receivers are also called beneficiaries.

Receivers belong to your selected organisation. You can create them before your organisation is fully active.

Individual or company

Set type to one of:

Type	Name fields	Rules
`INDIVIDUAL`	`firstName`, `lastName`, optional `middleName`	`legalName` is rejected
`COMPANY`	`legalName`	`firstName` and `lastName` are rejected

Create a receiver

POST /receivers

Field	Type	Required	Notes
`type`	`INDIVIDUAL` or `COMPANY`	Yes
`firstName`, `lastName`	string	Yes for `INDIVIDUAL`
`legalName`	string	Yes for `COMPANY`
`middleName`	string	No	`INDIVIDUAL` only
`email`	email	Send it
`address`	object	Send it	See below
`countryIsoCode`	ISO 3166-1 alpha-2	Send it	Check it against `isoCode3166` from `GET /countries` first
`phoneNumber`	string	No	10 digits, or E.164 such as `+5511999998888`
`dateOfBirth`	`YYYY-MM-DD`	No	Needed for BRL bank accounts on an individual
`taxId`	string	No	Brazil: CPF for an individual, CNPJ for a company. Check digits are validated
`nationality`	ISO 3166-1 alpha-2	No	Needed for BRL bank accounts on an individual

When you create a receiver, the server only enforces type and the name fields. It does not require email, address or countryIsoCode. Send all three anyway: bank accounts and payouts depend on them, and some payout rails reject a receiver without an address.

countryIsoCode trap: on create, a code the server does not know is saved as "no country", without an error. Validate the code against GET /countries before you send it.

The address object

Field	Required	Notes
`addressLine1`	Yes	Street and number
`city`	Yes
`postCode`	Yes
`state`	Brazil only	The two-letter state (UF), for example `SP`

The country is not part of the address. It is countryIsoCode on the receiver. Other keys in the address are not stored.

{
  "type": "COMPANY",
  "legalName": "Acme Trading Ltd",
  "email": "payments@acme.example",
  "countryIsoCode": "GB",
  "address": {
    "addressLine1": "10 Example Street",
    "city": "London",
    "postCode": "EC1A 1AA"
  }
}

The response is the receiver. Keep its _id: bank accounts, wallets and transactions reference it.

Errors

Status	Message
400	`FirstName and LastName are required fields in a receiver of type individual`
400	`LegalName is a required field in a receiver of type company`
400	`Receiver of type company only accepts legalName`
400	`Receiver of type individual only accepts firstName and lastName`
400	`Please use a valid phone number (10 digits, or E.164 format e.g. +5511999998888)`
400	an invalid `taxId`, `email` or `nationality`

List receivers

GET /receivers/me returns the receivers of your selected organisation. Each result includes its bankAccounts and wallets.

Parameter	Effect
`limit`, `offset`	Pagination. See Setup
`searchTerm`	Matches first, last or legal name
`paymentType`	`fiat` keeps receivers with at least one bank account. `crypto` keeps receivers with at least one wallet

Other filters listed in the API reference (organisation, isSelf, isHidden) have no effect on this endpoint. Removed receivers and your organisation's own receiver are never listed.

Get one receiver

GET /receivers/{id} returns the receiver with its bankAccounts and wallets. It returns 404 for a removed receiver, for your organisation's own receiver, and for a receiver outside your organisation.

Update a receiver

PATCH /receivers/{id} takes the same fields as create.

Always send the full receiver, not just the fields you change. Read it with GET /receivers/{id}, change what you need and send every field back.

If you leave out countryIsoCode, the receiver's country is cleared.
If the receiver has bank accounts, clearing its country, address or email returns 400 Cannot remove previous information from receiver, since it has bank accounts associated.
Changing type clears the name fields and date of birth of the other type.
An unknown countryIsoCode returns 400 Country IsoCode not supported.

Only an active member of the organisation who is not view-only can update its receivers:

Status	Message
403	`Only an active member of the organisation can modify its beneficiaries`
403	`View-only members cannot modify beneficiaries`
404	`This receiver doesn't exist`
429	More than 20 update calls per hour by the same user

Remove a receiver

DELETE /receivers/{id} hides the receiver. It is not erased.

It disappears from GET /receivers/me, and GET /receivers/{id} returns 404.
Transactions that already reference it are not affected.
The response is the receiver as it was before the call, so it still shows isHidden: false.
The same membership rules as update apply, and removals are limited to 20 per hour per user. A missing receiver returns 404 Receiver not found.

Your organisation's own receiver

Skyline creates one receiver that represents your organisation, during onboarding. It is used when funds come back to you, for example in an on-ramp. Read it with GET /receivers/self. It returns 404 Receiver not found if it does not exist yet. It never appears in GET /receivers/me.

What's next

Add a bank account or a wallet to the receiver.

Receivers

On this page