---
title: "Attach the supporting document (invoice) for a payout"
method: POST
path: "/transfers/{transfer_id}/documents"
tags: ["Transfers"]
---

# Attach the supporting document (invoice) for a payout

`POST /transfers/{transfer_id}/documents`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/transfers/{transfer_id}/documents`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Attaches the commercial supporting document for a payout transfer: in
practice the invoice the payment settles. The receiving institution
validates the purpose code against this document, so a payout can be
accepted and then sit unsettled while it is missing.

One document per transfer. Upload it before the payout is dispatched:
the document is forwarded to the receiving institution only after the
payment order exists, so this response does not say whether it has
been forwarded.

The bytes travel inline as base64 in a single call, unlike customer
documents, which use a two-call signed upload. A payout document is one
small file per operation, and a single call makes the result
indivisible, with no window where the document is registered and its
bytes are absent.

## Path parameters

- `transfer_id` string, required

## Request body

- PayoutDocumentUpload: The supporting document for a payout, sent inline as base64. The bytes travel in the request rather than through a signed upload URL because this is one small file per payout, and a single call leaves no window in which the document is registered and its bytes are absent, a state that reads as "sent" and is not.
  - `file_name` string, required: Name shown to compliance reviewers.
  - `content_type` 'application/pdf', required: PDF only. The receiving institution named PDF as the format for the invoice, and a file its compliance review cannot accept comes back as a request for information days later, by email. Refusing here is an immediate message to whoever still has the file in hand.
  - `content_base64` string, required: The file, base64-encoded, without a `data:` prefix. Maximum 10 MB decoded. Content that does not decode, or decodes to zero bytes, is refused with `400 DOCUMENT_CONTENT_INVALID` before anything is stored.

## Response `201`

Document stored and linked to the payout.

- PayoutDocument: The stored supporting document for a payout.
  - `id` string, uuid
  - `object` 'payout_document'
  - `transfer_id` string: The transfer this document supports (`ozav_tr_...`).
  - `file_name` string
  - `content_type` string
  - `size_bytes` integer: Decoded size.

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `404`: The resource does not exist, is not visible to the caller, or the id was malformed for this position (see "Resource ids" under Errors). These share one status; `code` and `message` tell them apart.
- `409`: This transfer already has a supporting document.

---

[API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)