Create a transfer batch
curl --request POST \
--url https://api.fintoc.com/v2/transfer_batches \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Fintoc-JWS-Signature: <fintoc-jws-signature>' \
--data '
{
"description": "Supplier payouts March",
"currency": "MXN",
"transfers": [
{
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"counterparty": {
"account_number": "000000000000000000",
"holder_id": "111111111",
"holder_name": "Test Customer 1",
"institution_id": "cl_banco_de_chile",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": {
"invoice_id": "12345"
}
}
]
}
'import requests
url = "https://api.fintoc.com/v2/transfer_batches"
payload = {
"description": "Supplier payouts March",
"currency": "MXN",
"transfers": [
{
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"counterparty": {
"account_number": "000000000000000000",
"holder_id": "111111111",
"holder_name": "Test Customer 1",
"institution_id": "cl_banco_de_chile",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": { "invoice_id": "12345" }
}
]
}
headers = {
"Fintoc-JWS-Signature": "<fintoc-jws-signature>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Fintoc-JWS-Signature': '<fintoc-jws-signature>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
description: 'Supplier payouts March',
currency: 'MXN',
transfers: [
{
account_id: 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
amount: 50000,
counterparty: {
account_number: '000000000000000000',
holder_id: '111111111',
holder_name: 'Test Customer 1',
institution_id: 'cl_banco_de_chile',
account_type: 'checking_account',
email: 'jared@piedpiper.com'
},
comment: 'Payout March',
reference_id: '1234567',
metadata: {invoice_id: '12345'}
}
]
})
};
fetch('https://api.fintoc.com/v2/transfer_batches', 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.fintoc.com/v2/transfer_batches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Supplier payouts March',
'currency' => 'MXN',
'transfers' => [
[
'account_id' => 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
'amount' => 50000,
'counterparty' => [
'account_number' => '000000000000000000',
'holder_id' => '111111111',
'holder_name' => 'Test Customer 1',
'institution_id' => 'cl_banco_de_chile',
'account_type' => 'checking_account',
'email' => 'jared@piedpiper.com'
],
'comment' => 'Payout March',
'reference_id' => '1234567',
'metadata' => [
'invoice_id' => '12345'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Fintoc-JWS-Signature: <fintoc-jws-signature>"
],
]);
$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.fintoc.com/v2/transfer_batches"
payload := strings.NewReader("{\n \"description\": \"Supplier payouts March\",\n \"currency\": \"MXN\",\n \"transfers\": [\n {\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"counterparty\": {\n \"account_number\": \"000000000000000000\",\n \"holder_id\": \"111111111\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"cl_banco_de_chile\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"invoice_id\": \"12345\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Fintoc-JWS-Signature", "<fintoc-jws-signature>")
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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.fintoc.com/v2/transfer_batches")
.header("Fintoc-JWS-Signature", "<fintoc-jws-signature>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"description\": \"Supplier payouts March\",\n \"currency\": \"MXN\",\n \"transfers\": [\n {\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"counterparty\": {\n \"account_number\": \"000000000000000000\",\n \"holder_id\": \"111111111\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"cl_banco_de_chile\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"invoice_id\": \"12345\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fintoc.com/v2/transfer_batches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Fintoc-JWS-Signature"] = '<fintoc-jws-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Supplier payouts March\",\n \"currency\": \"MXN\",\n \"transfers\": [\n {\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"counterparty\": {\n \"account_number\": \"000000000000000000\",\n \"holder_id\": \"111111111\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"cl_banco_de_chile\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"invoice_id\": \"12345\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "trbatch_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"object": "transfer_batch",
"amount": 150000,
"authorized_at": "2026-03-01T12:05:00Z",
"created_at": "2026-03-01T12:00:00Z",
"currency": "MXN",
"description": "Supplier payouts March",
"expired_at": null,
"mode": "test",
"partially_succeeded_at": null,
"rejected_at": null,
"settled_amount": 0,
"status": "in_progress",
"succeeded_at": null,
"succeeded_count": 0,
"transfer_count": 3
}
Transfer batches
Create a transfer batch
Creates a batch of outbound transfers from your accounts, in the live or test mode of the API key used. The batch starts in pending_authorization and Fintoc sends its transfers only after you approve the batch from the Dashboard. An approved batch moves to in_progress. Requirements differ by country. In Chile, the currency is CLP and each counterparty needs a holder_id, which is the Chilean tax ID (RUT), a holder_name, an account_type, and an institution_id. In Mexico, the currency is MXN and each counterparty’s account_number can be a standardized Mexican bank account number (CLABE), debit card, or phone number. When account_number is a debit card or phone number, the counterparty also needs an institution_id. To read the transfers of the batch, call GET /v2/transfers with the transfer_batch_id query parameter. Requires a JSON Web Signature (JWS) in the Fintoc-JWS-Signature header.
POST
/
v2
/
transfer_batches
Create a transfer batch
curl --request POST \
--url https://api.fintoc.com/v2/transfer_batches \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Fintoc-JWS-Signature: <fintoc-jws-signature>' \
--data '
{
"description": "Supplier payouts March",
"currency": "MXN",
"transfers": [
{
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"counterparty": {
"account_number": "000000000000000000",
"holder_id": "111111111",
"holder_name": "Test Customer 1",
"institution_id": "cl_banco_de_chile",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": {
"invoice_id": "12345"
}
}
]
}
'import requests
url = "https://api.fintoc.com/v2/transfer_batches"
payload = {
"description": "Supplier payouts March",
"currency": "MXN",
"transfers": [
{
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"counterparty": {
"account_number": "000000000000000000",
"holder_id": "111111111",
"holder_name": "Test Customer 1",
"institution_id": "cl_banco_de_chile",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": { "invoice_id": "12345" }
}
]
}
headers = {
"Fintoc-JWS-Signature": "<fintoc-jws-signature>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Fintoc-JWS-Signature': '<fintoc-jws-signature>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
description: 'Supplier payouts March',
currency: 'MXN',
transfers: [
{
account_id: 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
amount: 50000,
counterparty: {
account_number: '000000000000000000',
holder_id: '111111111',
holder_name: 'Test Customer 1',
institution_id: 'cl_banco_de_chile',
account_type: 'checking_account',
email: 'jared@piedpiper.com'
},
comment: 'Payout March',
reference_id: '1234567',
metadata: {invoice_id: '12345'}
}
]
})
};
fetch('https://api.fintoc.com/v2/transfer_batches', 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.fintoc.com/v2/transfer_batches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Supplier payouts March',
'currency' => 'MXN',
'transfers' => [
[
'account_id' => 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
'amount' => 50000,
'counterparty' => [
'account_number' => '000000000000000000',
'holder_id' => '111111111',
'holder_name' => 'Test Customer 1',
'institution_id' => 'cl_banco_de_chile',
'account_type' => 'checking_account',
'email' => 'jared@piedpiper.com'
],
'comment' => 'Payout March',
'reference_id' => '1234567',
'metadata' => [
'invoice_id' => '12345'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Fintoc-JWS-Signature: <fintoc-jws-signature>"
],
]);
$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.fintoc.com/v2/transfer_batches"
payload := strings.NewReader("{\n \"description\": \"Supplier payouts March\",\n \"currency\": \"MXN\",\n \"transfers\": [\n {\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"counterparty\": {\n \"account_number\": \"000000000000000000\",\n \"holder_id\": \"111111111\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"cl_banco_de_chile\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"invoice_id\": \"12345\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Fintoc-JWS-Signature", "<fintoc-jws-signature>")
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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.fintoc.com/v2/transfer_batches")
.header("Fintoc-JWS-Signature", "<fintoc-jws-signature>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"description\": \"Supplier payouts March\",\n \"currency\": \"MXN\",\n \"transfers\": [\n {\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"counterparty\": {\n \"account_number\": \"000000000000000000\",\n \"holder_id\": \"111111111\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"cl_banco_de_chile\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"invoice_id\": \"12345\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fintoc.com/v2/transfer_batches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Fintoc-JWS-Signature"] = '<fintoc-jws-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Supplier payouts March\",\n \"currency\": \"MXN\",\n \"transfers\": [\n {\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"counterparty\": {\n \"account_number\": \"000000000000000000\",\n \"holder_id\": \"111111111\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"cl_banco_de_chile\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"invoice_id\": \"12345\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "trbatch_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"object": "transfer_batch",
"amount": 150000,
"authorized_at": "2026-03-01T12:05:00Z",
"created_at": "2026-03-01T12:00:00Z",
"currency": "MXN",
"description": "Supplier payouts March",
"expired_at": null,
"mode": "test",
"partially_succeeded_at": null,
"rejected_at": null,
"settled_amount": 0,
"status": "in_progress",
"succeeded_at": null,
"succeeded_count": 0,
"transfer_count": 3
}
Authorizations
Headers
JSON Web Signature (JWS) of the request body. See Generate JWS keys to set up request signing.
Body
application/json
Human-readable label shown in the Dashboard when you approve the batch. Up to 40 characters.
Example:
"Supplier payouts March"
Currency of every transfer in the batch. One of CLP, MXN.
Available options:
CLP, MXN Example:
"MXN"
Transfers to send in the batch. From 1 to 5000 transfers.
Show child attributes
Show child attributes
Response
The created transfer batch, in pending_authorization.
A group of outbound transfers that you create in one request and approve once from the Dashboard. Fintoc sends the transfers in the batch after you approve the batch. List them with GET /v2/transfers and the transfer_batch_id query parameter.
Unique identifier of the transfer batch.
Example:
"trbatch_2daFu0zqqDtZGJaSi2TGI2Mm1nN"
Type of the object. Always transfer_batch.
Sum of the amounts of the transfers in the batch, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit.
Example:
150000
Time the batch was approved from the Dashboard, as an ISO 8601 datetime in UTC, or null.
Example:
"2026-03-01T12:05:00Z"
Time the batch was created, as an ISO 8601 datetime in UTC.
Example:
"2026-03-01T12:00:00Z"
Currency of the transfers in the batch. One of CLP, MXN.
Available options:
CLP, MXN Example:
"MXN"
Human-readable label for the batch. Up to 40 characters.
Example:
"Supplier payouts March"
Time the batch expired without approval, as an ISO 8601 datetime in UTC, or null.
Example:
null
Whether the batch is live or test data.
Available options:
live, test Example:
"test"
Time the batch finished after only some transfers succeeded, as an ISO 8601 datetime in UTC, or null.
Example:
null
Time the batch was rejected from the Dashboard, as an ISO 8601 datetime in UTC, or null.
Example:
null
Sum of the settled_amount of the transfers in the batch, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit.
Example:
0
Lifecycle status of the batch. One of pending_authorization (waiting for approval in the Dashboard), rejected (rejected in the Dashboard), expired (not approved in time), in_progress (approved, with transfers being sent), succeeded (every transfer succeeded), partially_succeeded (some transfers succeeded), or failed (no transfer succeeded).
Available options:
pending_authorization, rejected, expired, in_progress, succeeded, partially_succeeded, failed Example:
"in_progress"
Time every transfer of the batch succeeded, as an ISO 8601 datetime in UTC, or null.
Example:
null
Number of transfers in the batch that succeeded.
Example:
0
Number of transfers in the batch.
Example:
3
Was this page helpful?