Add an attachment to a processing account

Prerequisites: 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.

Integration steps

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

Before you begin

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

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

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
Production	https://api.payroc.com/v1/processing-accounts/{processingAccountId}/attachments

Request parameters

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

Schema (`request.body`)

Request body schema for POST /processing-accounts/{processingAccountId}/attachments

Example request

Request

POST https://api.payroc.com/v1/processing-accounts/{processingAccountId}/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);
}

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();

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()

Response fields

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

Schema (`response.body`)

Response body schema for POST /processing-accounts/{processingAccountId}/attachments

Example response

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"
  }
}

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}
Production	https://api.payroc.com/v1/attachments/{attachmentId}

Example request

Request

GET https://api.payroc.com/v1/attachments/{attachmentId}

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

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

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()

Response fields

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

Schema (`response.body`)

Response body schema for GET /attachments/{attachmentId}

Example response

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"
  }
}

Integration steps

Before you begin

Step 1. Upload an attachment

Request parameters

Schema (`request.body`)

Example request

Request

Response fields

Schema (`response.body`)

Example response

Response (201)

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

Example request

Request

Response fields

Schema (`response.body`)

Example response

Response (200)

Browse guides

Menu

Sign out

Talk to an engineer

Integration steps

Before you begin

Step 1. Upload an attachment

Request parameters

Schema (request.body)

Example request

Request

Response fields

Schema (response.body)

Example response

Response (201)

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

Example request

Request

Response fields

Schema (response.body)

Example response

Response (200)

Schema (`request.body`)

Schema (`response.body`)

Schema (`response.body`)