Beneficiary Management
Learn how to create and manage payment receivers and beneficiaries
Before you can initiate transactions on the Skyline Digital platform, you need to register at least one beneficiary (also called a receiver). A receiver represents a payment recipient -- either an individual person or a company -- and stores the details needed to route payments correctly. This tutorial covers the full lifecycle of managing receivers.
Prerequisites
Before starting this tutorial, complete the KYC & KYB Verification tutorial. Your organisation must have an onboarding status of APPROVED before you can create receivers.
What are receivers
A receiver is a registered payment recipient associated with your organisation. Each receiver has a type that determines which fields are required and how the receiver is presented in the system. There are two receiver types:
| Type | Description |
|---|---|
| INDIVIDUAL | A natural person who will receive payments. Requires personal details such as first name, last name, and email. |
| COMPANY | A legal entity that will receive payments. Requires business details such as the legal name and email. |
You can create as many receivers as you need. Each transaction you initiate will reference a specific receiver as the payment destination.
Creating an individual receiver
To create a receiver for an individual person, send a request to POST /receivers with the type set to INDIVIDUAL and the required personal details.
The following fields are required when creating an individual receiver:
| Field | Description |
|---|---|
| type | Must be set to INDIVIDUAL. |
| firstName | The receiver's first (given) name. |
| lastName | The receiver's last (family) name. |
| The receiver's email address. Used for identification and notifications. | |
| address | The receiver's physical address. |
| countryIsoCode | The ISO 3166-1 alpha-2 country code for the receiver's country of residence (for example, GB for the United Kingdom or US for the United States). |
The API returns the newly created receiver object, including a unique identifier that you will use when creating transactions.
Creating a company receiver
To create a receiver for a legal entity, send a request to POST /receivers with the type set to COMPANY and the required business details.
The following fields are required when creating a company receiver:
| Field | Description |
|---|---|
| type | Must be set to COMPANY. |
| legalName | The registered legal name of the company. |
| The company's contact email address. | |
| address | The company's registered address. |
| countryIsoCode | The ISO 3166-1 alpha-2 country code for the country where the company is registered. |
Listing receivers
To retrieve a list of all receivers associated with your organisation, send a request to GET /receivers/me. The response is paginated and can be filtered using query parameters.
Pagination parameters
| Parameter | Description |
|---|---|
| page | The page number to retrieve. Defaults to the first page. |
| limit | The number of receivers to return per page. |
Filter parameters
| Parameter | Description |
|---|---|
| paymentType | Filter receivers by their associated payment type. |
| isSelf | When set to true, returns only self-receivers (see below). When set to false, excludes self-receivers. |
| isHidden | When set to true, includes hidden receivers. When set to false, excludes them. |
Getting a specific receiver
To retrieve the full details of a single receiver, send a request to GET /receivers/:id, replacing :id with the receiver's unique identifier. This is useful when you need to verify a receiver's details before initiating a transaction.
Updating a receiver
To modify an existing receiver, send a request to PATCH /receivers/:id with only the fields you want to change. Partial updates are supported, so you do not need to include every field -- only the ones being modified.
For example, you can update just the email address or the address without affecting other fields. The API returns the updated receiver object.
Deleting a receiver
To remove a receiver, send a request to DELETE /receivers/:id. Once deleted, the receiver can no longer be used for new transactions. Any existing transactions that reference the receiver are not affected.
Self-receiver
Every organisation has a special self-receiver that represents the organisation itself as a payment destination. This is used when you need to receive funds into your own account rather than paying out to a third party.
To retrieve your self-receiver, send a request to GET /receivers/self. The self-receiver is created automatically when your organisation is set up and does not need to be managed manually.
You can also find your self-receiver in the list returned by GET /receivers/me by filtering with the isSelf parameter set to true.
What's next
With your receivers set up, you are ready to start creating transactions. Continue to the Transactions section to learn how to initiate and manage payments.