# Add an attachment to a processing account

Upload a document to a processing account by sending a POST request to the Processing Accounts attachments endpoint, then optionally check the upload status via the Attachments endpoint.

**Prerequisites:** [Authentication](/api/authentication)

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.

<a id="integration-steps"></a>
## Integration steps

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

<a id="before-you-begin"></a>
## Before you begin

[Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors).

**Important:** This endpoint accepts a file upload. Set the value of the Content-Type header to `multipart/form-data` instead of `application/json`.

<a id="step-1-upload-an-attachment"></a>
## Step 1. Upload an attachment

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

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/processing-accounts/\{processingAccountId\}/attachments](https://api.uat.payroc.com/v1/processing-accounts/%7BprocessingAccountId%7D/attachments) |
| Production | [https://api.payroc.com/v1/processing-accounts/\{processingAccountId\}/attachments](https://api.payroc.com/v1/processing-accounts/%7BprocessingAccountId%7D/attachments) |

<a id="request-parameters"></a>
### Request parameters

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

<a id="schema-requestbody"></a>
### Schema (`request.body`)

[Request body schema for `POST /processing-accounts/{processingAccountId}/attachments`](/api/create-processing-account-attachment)

<a id="example-request"></a>
### Example request

<a id="request"></a>
### Request

POST [https://api.payroc.com/v1/processing-accounts/\{processingAccountId\}/attachments](https://api.payroc.com/v1/processing-accounts/%7BprocessingAccountId%7D/attachments)

```curl
curl -X POST https://api.payroc.com/v1/processing-accounts/38765/attachments \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: multipart/form-data" \
     -F attachment='{
  "type": "personalIdentification",
  "description": "Passport as identification for lease agreement",
  "metadata": {
    "documentId": "2345"
  }
}' \
     -F file=@<file1>
```

```python
import requests

url = "https://api.payroc.com/v1/processing-accounts/38765/attachments"

files = { "file": "open('<file1>', 'rb')" }
payload = { "attachment": "{
  \"type\": \"personalIdentification\",
  \"description\": \"Passport as identification for lease agreement\",
  \"metadata\": {
    \"documentId\": \"2345\"
  }
}" }
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.payroc.com/v1/processing-accounts/38765/attachments';
const form = new FormData();
form.append('attachment', '{
  "type": "personalIdentification",
  "description": "Passport as identification for lease agreement",
  "metadata": {
    "documentId": "2345"
  }
}');
form.append('file', '<file1>');

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>'
  }
};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/processing-accounts/38765/attachments"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"attachment\"\r\n\r\n{\n  \"type\": \"personalIdentification\",\n  \"description\": \"Passport as identification for lease agreement\",\n  \"metadata\": {\n    \"documentId\": \"2345\"\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/processing-accounts/38765/attachments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"attachment\"\r\n\r\n{\n  \"type\": \"personalIdentification\",\n  \"description\": \"Passport as identification for lease agreement\",\n  \"metadata\": {\n    \"documentId\": \"2345\"\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/processing-accounts/38765/attachments")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"attachment\"\r\n\r\n{\n  \"type\": \"personalIdentification\",\n  \"description\": \"Passport as identification for lease agreement\",\n  \"metadata\": {\n    \"documentId\": \"2345\"\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/processing-accounts/38765/attachments', [
  'multipart' => [
    [
        'name' => 'attachment',
        'contents' => '{
  "type": "personalIdentification",
  "description": "Passport as identification for lease agreement",
  "metadata": {
    "documentId": "2345"
  }
}'
    ],
    [
        'name' => 'file',
        'filename' => '<file1>',
        'contents' => null
    ]
  ]
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/processing-accounts/38765/attachments");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"attachment\"\r\n\r\n{\n  \"type\": \"personalIdentification\",\n  \"description\": \"Passport as identification for lease agreement\",\n  \"metadata\": {\n    \"documentId\": \"2345\"\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>"
]
let parameters = [
  [
    "name": "attachment",
    "value": "{
  \"type\": \"personalIdentification\",
  \"description\": \"Passport as identification for lease agreement\",
  \"metadata\": {
    \"documentId\": \"2345\"
  }
}"
  ],
  [
    "name": "file",
    "fileName": "<file1>"
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/processing-accounts/38765/attachments")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

<a id="response-fields"></a>
### Response fields

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

<a id="schema-responsebody"></a>
### Schema (`response.body`)

[Response body schema for `POST /processing-accounts/{processingAccountId}/attachments`](/api/create-processing-account-attachment)

<a id="example-response"></a>
### Example response

<a id="response-201"></a>
### Response (201)

```json
{
  "attachmentId": "2587",
  "type": "personalIdentification",
  "uploadStatus": "pending",
  "fileName": "JaneDoePassport.pdf",
  "contentType": "application/pdf",
  "entity": {
    "type": "processingAccount",
    "id": "38765"
  },
  "createdDate": "2024-07-02T12:00:00.000Z",
  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
  "description": "Passport as identification for lease agreement",
  "metadata": {
    "documentId": "2345"
  }
}
```

<a id="step-2-optional-check-the-upload-status-of-the-attachment"></a>
## 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.

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/attachments/\{attachmentId\}](https://api.uat.payroc.com/v1/attachments/%7BattachmentId%7D) |
| Production | [https://api.payroc.com/v1/attachments/\{attachmentId\}](https://api.payroc.com/v1/attachments/%7BattachmentId%7D) |

<a id="example-request-1"></a>
### Example request

<a id="request-1"></a>
### Request

GET [https://api.payroc.com/v1/attachments/\{attachmentId\}](https://api.payroc.com/v1/attachments/%7BattachmentId%7D)

**`Upload Attachment`**

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

**`Upload Attachment`**

```python
import requests

url = "https://api.payroc.com/v1/attachments/12876"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

**`Upload Attachment`**

```javascript
const url = 'https://api.payroc.com/v1/attachments/12876';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Upload Attachment`**

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/attachments/12876"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Upload Attachment`**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/attachments/12876")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

**`Upload Attachment`**

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.payroc.com/v1/attachments/12876")
  .header("Authorization", "Bearer <token>")
  .asString();
```

**`Upload Attachment`**

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.payroc.com/v1/attachments/12876', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

**`Upload Attachment`**

```csharp
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/attachments/12876");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

**`Upload Attachment`**

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/attachments/12876")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

<a id="response-fields-1"></a>
### Response fields

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

<a id="schema-responsebody-1"></a>
### Schema (`response.body`)

[Response body schema for `GET /attachments/{attachmentId}`](/api/get-attachment)

<a id="example-response-1"></a>
### Example response

<a id="response-200"></a>
### Response (200)

```json
{
  "attachmentId": "15387",
  "type": "personalIdentification",
  "uploadStatus": "accepted",
  "fileName": "JaneDoePassport.pdf",
  "contentType": "application/pdf",
  "entity": {
    "type": "processingAccount",
    "id": "2585"
  },
  "createdDate": "2025-09-18T10:19:18.522Z",
  "lastModifiedDate": "2025-09-18T10:19:18.522Z",
  "description": "Passport for Jane Doe",
  "metadata": {
    "passportId": "123456789"
  }
}
```