# Supporting documents

Attach the evidence required to review and process each payout, on the party or payment it relates to.

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/supporting-documents

Documents are embedded in the payout request as base64 and attached to the
thing they evidence. There is one document structure, used in three places:

| Location                                                                                                                  | What it evidences                            | Example                                                                  |
| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
| `supportingDocuments[]` on the payout                                                                                     | The payment itself                           | Invoice, contract, purchase order                                        |
| `sender.documents[]`, `recipient.documents[]`                                                                             | The party, without a specific identification | Proof of address, financial statement                                    |
| `sender.identification.documents[]`, `recipient.identification.documents[]`, `relationships[].identification.documents[]` | A specific identification                    | Registry extract for a registration number, passport scan for a passport |

Corridor rules decide which documents are required. Retrieve corridor details
before creating the payout and include all documents in the initial request;
confirmation does not accept additional evidence.

Smart Payload Mapping helps you connect documents from your records to the
appropriate Axiym document locations. See
[How it works](/payment-api/tools#associate-documents) for preparing and reviewing
those connections.

## Document fields

| Field          | Type or format | Requiredness | Description                                                                                                    |
| -------------- | -------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
| `documentType` | Axiym enum     | Required     | Type of evidence. Use an exact Axiym code; other labels need a saved value translation on the mapped endpoint. |
| `name`         | String         | Required     | File name, including the extension.                                                                            |
| `data`         | Base64 string  | Required     | Complete file encoded as base64 from its raw bytes.                                                            |

Encode the raw file bytes once. Do not include a data-URL prefix such as
`data:application/pdf;base64,`. Axiym detects the media type from the content;
there is no separate content-type field. A two-sided document is one file.

## Example

Replace the placeholder with the base64 encoding of a complete sandbox
fixture. The placeholder is not valid document content.

```json
{
  "documentType": "REGISTRY_EXTRACT",
  "name": "acme-registry-extract.pdf",
  "data": "REPLACE_WITH_BASE64_ENCODED_REGISTRY_EXTRACT"
}
```

Use an exact `documentType` code, such as `REGISTRY_EXTRACT`, in direct
requests. Other labels require a saved value translation on the mapped
endpoint. See
[Controlled values](/payment-api/integration-guide/prepare-payout-data/controlled-values#supportingdocumenttype).

## What the response returns

The payment does not echo base64 data. Each accepted document is returned in
the same place with its metadata:

```json
{
  "documentType": "REGISTRY_EXTRACT",
  "fileId": "6c1d0e42-8b7a-4f39-9d21-3a5e7c9b1f08",
  "name": "acme-registry-extract.pdf",
  "contentType": "application/pdf",
  "size": 96311
}
```

Use `fileId` to correlate the stored file with your own records.