Upload a payout RFI file

curl --request POST \
  --url https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'fileMetadata={
  "fileName": "invoice.pdf",
  "fileType": "application/pdf",
  "fileKey": "proofOfFunds"
}' \
  --form encryptedFile=@example-file \
  --form file=@example-file

import requests

url = "https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files"

files = {
    "encryptedFile": ("example-file", open("example-file", "rb")),
    "file": ("example-file", open("example-file", "rb"))
}
payload = { "fileMetadata": "{
  \"fileName\": \"invoice.pdf\",
  \"fileType\": \"application/pdf\",
  \"fileKey\": \"proofOfFunds\"
}" }
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('fileMetadata', '{
  "fileName": "invoice.pdf",
  "fileType": "application/pdf",
  "fileKey": "proofOfFunds"
}');
form.append('encryptedFile', '<string>');
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

{
  "code": 404,
  "message": "Not found."
}

Upload a payout RFI file

Uploads a file in response to a file requirement of the specified RFI of a fiat payout.

The fileKey in fileMetadata must match one of the fileKey values from the fileRequirements array returned by GET /v1/payouts/{id}/rfi/{rfiId}.

Encryption — required for BFI-generated RFIs, optional for internally-generated RFIs:

Check whether GET /v1/payouts/{id}/rfi/{rfiId} returns a non-null certificate field:

certificate present (BFI-generated RFI): encrypt the file client-side before upload.
1. Extract certificate.jwk — an EC public key in JWK format.
2. Generate a random AES-128 key and encrypt the file bytes using AES-128-GCM. Retain the IV.
3. Wrap the AES-128 key using ECDH-ES + AES-128 Key Wrap (ECDH-ES+A128KW / A128GCM) against the EC public key from step 1. This produces a Compact JWE string (header.encryptedKey.iv.ciphertext.tag).
4. Submit with all three multipart fields (fileMetadata, encryption, encryptedFile).
certificate absent (internally-generated RFI): omit encryption and encryptedFile. Submit only fileMetadata and the raw file field. The file is stored with standard encryption-at-rest; no client-side encryption step is needed.

POST

payouts

{id}

rfi

{rfiId}

files

Upload a payout RFI file

curl --request POST \
  --url https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'fileMetadata={
  "fileName": "invoice.pdf",
  "fileType": "application/pdf",
  "fileKey": "proofOfFunds"
}' \
  --form encryptedFile=@example-file \
  --form file=@example-file

import requests

url = "https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files"

files = {
    "encryptedFile": ("example-file", open("example-file", "rb")),
    "file": ("example-file", open("example-file", "rb"))
}
payload = { "fileMetadata": "{
  \"fileName\": \"invoice.pdf\",
  \"fileType\": \"application/pdf\",
  \"fileKey\": \"proofOfFunds\"
}" }
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('fileMetadata', '{
  "fileName": "invoice.pdf",
  "fileType": "application/pdf",
  "fileKey": "proofOfFunds"
}');
form.append('encryptedFile', '<string>');
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/payouts/{id}/rfi/{rfiId}/files")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"fileMetadata\"\r\n\r\n{\r\n  \"fileName\": \"invoice.pdf\",\r\n  \"fileType\": \"application/pdf\",\r\n  \"fileKey\": \"proofOfFunds\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"encryptedFile\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

{
  "code": 404,
  "message": "Not found."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string<uuid>

required

Universally unique identifier (UUID v4) of a resource.

Example:

"b3d9d2d5-4c12-4946-a09d-953e82fae2b0"

rfiId

string<uuid>

required

Universally unique identifier (UUID v4) of the RFI.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

Body

multipart/form-data

fileMetadata

object

required

Show child attributes

encryption

object

JWE encryption envelope. Required when certificate is present in the RFI response (BFI-generated RFI). Omit for internally-generated RFIs.

Show child attributes

encryptedFile

file

AES-128-GCM encrypted file contents. Required when encryption is present (BFI-generated RFI). Omit for internally-generated RFIs.

file

Raw (unencrypted) file contents. Required for internally-generated RFIs (when certificate is absent in the RFI response). Omit for BFI-generated RFIs.

Response

File uploaded successfully.

API overview

Fiat payouts

Managed Payments

Stablecoin payments

Circle Payments Network

Upload a payout RFI file

Authorizations

Path Parameters

Body

Response