Documents

List of endpoints

Description Endpoint
Checking the Documents for a Payment

GET/payments/v1/payments/{paymentID}/documents

Uploading Files for a Document

POST/payments/v1/payments/{paymentID}/documents/{documentID}/files

Downloading Files of a Document

GET/payments/v1/payments/{paymentID}/documents/{documentID}/files/{fileID}

Deleting Files of a Document

DELETE/payments/v1/payments/{paymentID}/documents/{documentID}/files/{fileID}

About Documents

Some payments need documents due to regulatory and compliance requirements. Usually, the payer submits the supporting documents, for example the payer's passport or an invoice for the transaction.

Who can submit a document?

  • The payer can upload documents via the UI form (currently only available with the Checkout Experience)

  • You can upload document files via the API (see Uploading Files for a Document).

    Documents vs. Files

    In the API, it's important to distinguish between documents and files:

    Document: A container (like a folder) identified by a document ID.

    File: The actual content, such as a PDF or image. Identified by a file ID.

    A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

Requirements for using the Documents Resource

In general (all /documents endpoints):

You need permission to use the /documents endpoints. Please contact the Solutions team if you want to use them.

For downloading documents:

You need special permissions for downloading a document file, since the files could potentially contain sensitive data.

Please contact the Solutions team if you want to download documents.

Checking the Documents for a Payment

Request

This request enables you:

  • To check which documents are expected for the payment (this can be either required or optional documents).

    If no documents are expected for the payment, a 404 Not Found is returned. This does not indicate an error, it simply means there are no required or optional documents associated with this payment.

  • To check if the payer already uploaded the necessary files for the documents.

  • To check if the uploaded files are virus free.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

The payment reference is an ID generated by Flywire to identify a payment.

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

With the payment reference, the payment can be tracked through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

The payment reference is returned in an API response right after the payment is created .

For existing payments, you have various options to look up a payment reference:

Flywire API: You can find payment references by Getting a List of all Payments.

Callbacks: All payment callbacks contain the payment reference, see Payment Status Notifications.

Parameters for the Request Body

No request body needed.

GET/payments/v1/payments/{paymentID}/documents

curl https://base-url-placeholder/payments/UUI754118889/documents
-X GET
-H "Content-Type: application/json"
-H "X-Authentication-Key: {api_key}"

Response

  • Success
  • 404 - no documents

The response contains an array of documents:

The document ID. This is the ID you need to manage files for this document.

The document ID is an ID generated by Flywire to identify a document.

Format:

8-4-4-4-12 hexadecimal characters, for example

3b156a2e-6fd8-41f1-9efd-c945c26ed73d

Documents vs. Files

In the API, it's important to distinguish between documents and files:

Document: A container (like a folder) identified by a document ID.

File: The actual content, such as a PDF or image. Identified by a file ID.

A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

The name of the document. Note that this is not the file name, since a document can contain multiple files.

Indicates if the document is required to complete the payment:

  • true: The document is required

  • false: The document is optional. No file needs to be uploaded for this document.

The maximum size for this file in bytes.

files array

The list of files for the document. If no file has been uploaded for the document yet, the list of files is returned as empty [].

The file ID.

The file ID is an ID generated by Flywire to identify a file.

Format:

8-4-4-4-12 hexadecimal characters, for example

a4afa704-5102-4f5f-8cac-35c01dfcabad

Documents vs. Files

In the API, it's important to distinguish between documents and files:

Document: A container (like a folder) identified by a document ID.

File: The actual content, such as a PDF or image. Identified by a file ID.

A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

The status of the file. Possible values:

pending

The file is being uploaded and analyzed by the anti-virus.

available

The file has been successfully uploaded and no virus was detected.

virus_infected

The file has been uploaded but a virus was detected.

Files in this status can be deleted, but not downloaded.

The name of the file, for example passport.pdf.

[
	{
		"id": "3b156a2e-6fd8-41f1-9efd-c945c26ed73d",
		"name": "Passport",
		"required": true,
		"max_file_size": 1048576,
		"files": [
			{
				"id": "2f13712d-05b9-427f-8a31-952a8dce78ad",
                "status": "virus_infected",
                "file_name": "passport_front.pdf"
            },
            {
                "id": "a4afa704-5102-4f5f-8cac-35c01dfcabad",
                "status": "available",
                "file_name": "passport_back.pdf"
            }
        ]
    },
    {
        "id": "22813282-729a-4932-86e1-e6752e0ab3a2",
        "name": "Invoice",
        "required": false,
        "max_file_size": 1048576,
        "files": []
    }
]

404 Error - No documents for this payment

If no documents are expected for the payment, a 404 Not Found is returned. This does not indicate an error, it simply means there are no required or optional documents associated with this payment.

{
  "type": "https://developers.flywire.com",
  "status": "404",
  "title": "Not Found"
}

Uploading Files for a Document

Request

This request enables you to upload a file for a document.

You can upload multiple files for one document.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

The payment reference is an ID generated by Flywire to identify a payment.

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

With the payment reference, the payment can be tracked through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

The payment reference is returned in an API response right after the payment is created .

For existing payments, you have various options to look up a payment reference:

Flywire API: You can find payment references by Getting a List of all Payments.

Callbacks: All payment callbacks contain the payment reference, see Payment Status Notifications.

Replace {documentID} in the endpoint with the document ID.

The document ID is an ID generated by Flywire to identify a document.

Format:

8-4-4-4-12 hexadecimal characters, for example

3b156a2e-6fd8-41f1-9efd-c945c26ed73d

Documents vs. Files

In the API, it's important to distinguish between documents and files:

Document: A container (like a folder) identified by a document ID.

File: The actual content, such as a PDF or image. Identified by a file ID.

A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

The document IDs for all expected documents are returned in the API response after Checking the Documents for a Payment.

Content of the Request Body

To upload a file to a document, you need to use the request type multipart/form-data. The field name that contains the file must be file .

POST/payments/v1/payments/{paymentID}/documents/{documentID}/files 

curl https://base-url-placeholder/payments/UUI754118889/documents/3b156a2e-6fd8-41f1-9efd-c945c26ed73d/files
-X POST \
-H "X-Authentication-Key: {api_key}" \
-F "file=@/path/to/a/file.pdf"

Response

A 204 response will let you know that the file has been successfully uploaded. It will automatically be scanned for viruses after the upload. You can check the status of the file by Checking the Documents for a Payment.

204 NO CONTENT

Downloading Files of a Document

Request

Notes for downloading files:

  • You can only download a file when its status is available.

  • You need special permissions for downloading a document file, since the files could potentially contain sensitive data.

    Please contact the Solutions team if you want to download documents.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

The payment reference is an ID generated by Flywire to identify a payment.

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

With the payment reference, the payment can be tracked through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

The payment reference is returned in an API response right after the payment is created .

For existing payments, you have various options to look up a payment reference:

Flywire API: You can find payment references by Getting a List of all Payments.

Callbacks: All payment callbacks contain the payment reference, see Payment Status Notifications.

Replace {documentID} in the endpoint with the document ID.

The document ID is an ID generated by Flywire to identify a document.

Format:

8-4-4-4-12 hexadecimal characters, for example

3b156a2e-6fd8-41f1-9efd-c945c26ed73d

Documents vs. Files

In the API, it's important to distinguish between documents and files:

Document: A container (like a folder) identified by a document ID.

File: The actual content, such as a PDF or image. Identified by a file ID.

A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

The document IDs for all expected documents are returned in the API response after Checking the Documents for a Payment.

Replace {fileID} in the endpoint with the file ID.

The file ID is an ID generated by Flywire to identify a file.

Format:

8-4-4-4-12 hexadecimal characters, for example

a4afa704-5102-4f5f-8cac-35c01dfcabad

Documents vs. Files

In the API, it's important to distinguish between documents and files:

Document: A container (like a folder) identified by a document ID.

File: The actual content, such as a PDF or image. Identified by a file ID.

A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

You can find the file ID for files that are already uploaded in the API response after Checking the Documents for a Payment.

Parameters for the Request Body

No request body needed.

GET/payments/v1/payments/{paymentID}/documents/{documentID}/files/{fileID} 

curl https://base-url-placeholder/payments/UUI754118889/documents/3b156a2e-6fd8-41f1-9efd-c945c26ed73d/files/a4afa704-5102-4f5f-8cac-35c01dfcabad
-X GET
-H "Content-Type: application/json"
-H "X-Authentication-Key: {api_key}

Response

A successful 200 OK response returns the file in the response body. The Content-Type header indicates the file type (for example application/pdf).

200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="passport_front.pdf"

Deleting Files of a Document

Request

Notes for deleting files:

  • You can only delete a file when its status is available or virus_infected.

How to Resolve the Path Placeholders of the Endpoint

Replace {paymentID} in the endpoint with the payment reference.

The payment reference is an ID generated by Flywire to identify a payment.

Format:

Either: ABC123456789

3-letter portal/recipient ID 9 numbers

Or: 1AB12CD452ABC1D

number 8 alphanums number 5-alphanum portal/recipient ID

With the payment reference, the payment can be tracked through the different stages of the payment process.

The payment reference is also important in other situations, for example:

  • When a payer is using bank transfer as payment method, they usually must provide the payment reference when sending the funds.

  • The payment reference helps Flywire to identify the payment if you or your payer needs support.

The payment reference is returned in an API response right after the payment is created .

For existing payments, you have various options to look up a payment reference:

Flywire API: You can find payment references by Getting a List of all Payments.

Callbacks: All payment callbacks contain the payment reference, see Payment Status Notifications.

Replace {documentID} in the endpoint with the document ID.

The document ID is an ID generated by Flywire to identify a document.

Format:

8-4-4-4-12 hexadecimal characters, for example

3b156a2e-6fd8-41f1-9efd-c945c26ed73d

Documents vs. Files

In the API, it's important to distinguish between documents and files:

Document: A container (like a folder) identified by a document ID.

File: The actual content, such as a PDF or image. Identified by a file ID.

A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

The document IDs for all expected documents are returned in the API response after Checking the Documents for a Payment.

Replace {fileID} in the endpoint with the file ID.

The file ID is an ID generated by Flywire to identify a file.

Format:

8-4-4-4-12 hexadecimal characters, for example

a4afa704-5102-4f5f-8cac-35c01dfcabad

Documents vs. Files

In the API, it's important to distinguish between documents and files:

Document: A container (like a folder) identified by a document ID.

File: The actual content, such as a PDF or image. Identified by a file ID.

A document can include multiple files. For example, the "passport" document may contain two files: passport_front.pdf and passport_back.pdf.

You can find the file ID for files that are already uploaded in the API response after Checking the Documents for a Payment.

Parameters for the Request Body

No request body needed.

DELETE/payments/v1/payments/{paymentID}/documents/{documentID}/files/{fileID} 

curl https://base-url-placeholder/payments/UUI754118889/documents/3b156a2e-6fd8-41f1-9efd-c945c26ed73d/files/a4afa704-5102-4f5f-8cac-35c01dfcabad
-X DELETE
-H "Content-Type: application/json"
-H "X-Authentication-Key: {api_key}

Response

A 204 response will let you know that the file has been successfully deleted.

204 NO CONTENT