# Recipient

Identify the business being paid and the destination that receives the payout.

Product: Payment API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/recipient

The `recipient` object holds the business being paid and the `destination`
that receives the payout. Account fields sit directly on
`recipient.destination`, and `recipient.destination.bank` carries the
servicing bank for bank destinations.

The current Payment API accepts bank destinations only.

## Recipient fields

| Field                              | Type or format             | Requiredness                        | Description                                                                                                              |
| ---------------------------------- | -------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `recipient.businessRelationship`   | Axiym enum                 | Required                            | Relationship to the sender. Use an exact Axiym code; other labels need a saved value translation on the mapped endpoint. |
| `recipient.name`                   | String                     | Required                            | Registered legal business name.                                                                                          |
| `recipient.countryOfIncorporation` | ISO 3166-1 alpha-2         | Optional                            | Country where the recipient is incorporated, when known or required by the corridor.                                     |
| `recipient.address`                | Object                     | Required                            | Structured business address, see below.                                                                                  |
| `recipient.contact.email`          | Email                      | Required when `contact` is supplied | Business contact email.                                                                                                  |
| `recipient.contact.phoneNumber`    | International phone number | Required when `contact` is supplied | Business contact phone number.                                                                                           |
| `recipient.relationships[]`        | Array                      | Conditional                         | Related individuals and their roles, when required by the corridor.                                                      |
| `recipient.documents[]`            | SupportingDocumentInput\[] | Conditional                         | Documents about the recipient that do not evidence a specific identification, when required by the corridor.             |

`contact` is optional unless required by the corridor. When supplied, it must
include both email and phone number.

## Address fields

Addresses are structured following ISO 20022. `streetName` is the primary
address line, not literally a street name: it can carry the full street address
and number, a PO box, or a building or lot description. Use the value that
identifies the location; do not use placeholder values. `buildingNumber` is
optional, so a system that keeps a single address line integrates without
parsing anything.

| Field                              | Type or format     | Requiredness |
| ---------------------------------- | ------------------ | ------------ |
| `recipient.address.streetName`     | String             | Required     |
| `recipient.address.buildingNumber` | String             | Optional     |
| `recipient.address.city`           | String             | Required     |
| `recipient.address.region`         | String             | Recommended  |
| `recipient.address.postalCode`     | String             | Recommended  |
| `recipient.address.country`        | ISO 3166-1 alpha-2 | Required     |

## Identification fields

Identification is conditional: the destination rules decide when it is needed.
China bank payouts require it, for example.

| Field                                  | Type or format             | Requiredness                               | Description                                                              |
| -------------------------------------- | -------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| `recipient.identification.type`        | Axiym enum                 | Required when `identification` is supplied | Identification type.                                                     |
| `recipient.identification.number`      | String                     | Required when `identification` is supplied | Identification number.                                                   |
| `recipient.identification.country`     | ISO 3166-1 alpha-2         | Conditional                                |                                                                          |
| `recipient.identification.issueDate`   | ISO 8601 date              | Conditional                                |                                                                          |
| `recipient.identification.expiryDate`  | ISO 8601 date              | Conditional                                |                                                                          |
| `recipient.identification.documents[]` | SupportingDocumentInput\[] | Conditional                                | Documents evidencing this identification, when required by the corridor. |

When supplied, `recipient.relationships[]` must contain at least one individual,
even when the corridor does not require it. Every entry requires `firstName`,
`lastName`, `nationalities`, `address`, `identification`, and `role`, with the
same field requirements as [sender relationships](/payment-api/integration-guide/prepare-payout-data/sender).
Its `role` requires an exact Axiym code in direct requests. On the mapped
endpoint, another label must have a saved value translation.

## Destination fields

| Field                                 | Type or format | Requiredness | Description                                                                                                          |
| ------------------------------------- | -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `recipient.destination.accountNumber` | String         | Required     | Account number or IBAN, as required by the corridor.                                                                 |
| `recipient.destination.currency`      | Currency code  | Required     | Currency delivered to the recipient. It must match the currency of `destinationAmount` when that amount is supplied. |

## Bank fields

Supply the receiving bank details in `recipient.destination.bank`.

| Field                                           | Type or format     | Requiredness                   | Description                                                                                                                               |
| ----------------------------------------------- | ------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `recipient.destination.bank.bankName`           | String             | Required when bank is supplied | Name of the receiving bank.                                                                                                               |
| `recipient.destination.bank.address.country`    | ISO 3166-1 alpha-2 | Required when bank is supplied | Country of the receiving bank. It must align with the selected destination corridor and lets Axiym derive the applicable clearing system. |
| `recipient.destination.bank.swiftBic`           | ISO 9362 BIC       | Conditional                    | Required in some corridors, optional in others.                                                                                           |
| `recipient.destination.bank.clearingCode`       | Corridor-specific  | Conditional                    | Local bank resolving code, such as a clearing or routing code. See the Country Playbook.                                                  |
| `recipient.destination.bank.clearingSystemCode` | String             | Derived                        | Clearing system the code belongs to. Derived from the bank country; supply it where a country has more than one system.                   |

Use exact Axiym codes for `businessRelationship`, identification type,
relationship role, and document type. To use your own labels, prepare
[value mappings](/payment-api/integration-guide/prepare-payout-data/payment-data-maps#value-mapping)
and submit through the mapped endpoint. See
[Controlled values](/payment-api/integration-guide/prepare-payout-data/controlled-values).

## Example

```json
{
  "businessRelationship": "SUPPLIER",
  "name": "Example Supplier Corporation",
  "address": {
    "streetName": "Ayala Avenue",
    "buildingNumber": "6789",
    "city": "Makati",
    "region": "Metro Manila",
    "postalCode": "1226",
    "country": "PH"
  },
  "contact": {
    "email": "accounts@example-supplier.test",
    "phoneNumber": "+63281234567"
  },
  "destination": {
    "accountNumber": "1234567890",
    "currency": "PHP",
    "bank": {
      "bankName": "Example Bank",
      "address": { "country": "PH" },
      "swiftBic": "BNORPHMM",
      "clearingCode": "010000018"
    }
  }
}
```