Add an attachment to a processing account

You can use the attachments feature of our API to add a document to a processing account to support a merchant’s application, for example, questionnaires, banking evidence, and personal identification.

You can add only one attachment in each request to our API, and each attachment must be an uncompressed file under 50 MB in one of the following formats:

• .bmp, .csv, .doc, .docx, .gif, .htm, .html, .jpg, .jpeg, .msg, .pdf, .png, .ppt, .pptx, .tif, .tiff, .txt, .xls, .xlsx

After we receive your request, we upload the document and attach it to the processing account. You can use our API to check the upload status of the document and to view information about the document.

Integration steps

1. Upload an attachment.
2. (Optional) Check the upload status of the attachment.

Before you begin

Authenticate your requests before making API calls. If your request fails, see Errors.

Step 1. Upload an attachment

To upload an attachment, send a POST request to our Processing Accounts endpoint.

Request parameters

To create the body of your request, use the following parameters:

Example request

1
curl -X POST https://api.payroc.com/v1/processing-accounts/38765/attachments \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: multipart/form-data" \
5
     -F attachment='{
6
  "type": "personalIdentification"
7
}' \
8
     -F file=@string

Response fields

If your request is successful, our gateway uploads the attachment.

Example response

1
{
2
  "attachmentId": "2587",
3
  "type": "personalIdentification",
4
  "uploadStatus": "pending",
5
  "fileName": "JohnSmithPassport.pdf",
6
  "contentType": "application/pdf",
7
  "entity": {
8
    "type": "processingAccount",
9
    "id": "12667"
10
  },
11
  "createdDate": "2024-07-02T12:00:00.000Z",
12
  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
13
  "description": "Passport as identification for lease agreement",
14
  "metadata": {
15
    "passportId": "123456789"
16
  }
17
}

Step 2. (Optional) Check the upload status of the attachment

To check the upload status of the attachment, send a GET request to our Attachments endpoint.

Example request

1
curl https://api.payroc.com/v1/attachments/12876 \
2
     -H "Authorization: Bearer <token>"

Response fields

If your request is successful, our gateway returns details about the attachment.

Example response

1
{
2
  "attachmentId": "15387",
3
  "type": "personalIdentification",
4
  "uploadStatus": "accepted",
5
  "fileName": "oliviaDoePassport.pdf",
6
  "contentType": "application/pdf",
7
  "entity": {
8
    "type": "processingAccount",
9
    "id": "2585"
10
  },
11
  "createdDate": "2025-09-18T10:19:18.522Z",
12
  "lastModifiedDate": "2025-09-18T10:19:18.522Z",
13
  "description": "Passport for Olivia Doe",
14
  "metadata": {
15
    "passportId": "123456789"
16
  }
17
}