curl --request POST \
--url https://api.fintoc.com/v2/transfers \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Fintoc-JWS-Signature: <fintoc-jws-signature>' \
--data '
{
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"currency": "MXN",
"counterparty": {
"account_number": "132000000000000004",
"holder_id": "11111111-1",
"holder_name": "Test Customer 1",
"institution_id": "40012",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": {
"test_key": "test_value"
}
}
'import requests
url = "https://api.fintoc.com/v2/transfers"
payload = {
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"currency": "MXN",
"counterparty": {
"account_number": "132000000000000004",
"holder_id": "11111111-1",
"holder_name": "Test Customer 1",
"institution_id": "40012",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": { "test_key": "test_value" }
}
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({
account_id: 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
amount: 50000,
currency: 'MXN',
counterparty: {
account_number: '132000000000000004',
holder_id: '11111111-1',
holder_name: 'Test Customer 1',
institution_id: '40012',
account_type: 'checking_account',
email: 'jared@piedpiper.com'
},
comment: 'Payout March',
reference_id: '1234567',
metadata: {test_key: 'test_value'}
})
};
fetch('https://api.fintoc.com/v2/transfers', 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/transfers",
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([
'account_id' => 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
'amount' => 50000,
'currency' => 'MXN',
'counterparty' => [
'account_number' => '132000000000000004',
'holder_id' => '11111111-1',
'holder_name' => 'Test Customer 1',
'institution_id' => '40012',
'account_type' => 'checking_account',
'email' => 'jared@piedpiper.com'
],
'comment' => 'Payout March',
'reference_id' => '1234567',
'metadata' => [
'test_key' => 'test_value'
]
]),
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/transfers"
payload := strings.NewReader("{\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"currency\": \"MXN\",\n \"counterparty\": {\n \"account_number\": \"132000000000000004\",\n \"holder_id\": \"11111111-1\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"40012\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"test_key\": \"test_value\"\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/transfers")
.header("Fintoc-JWS-Signature", "<fintoc-jws-signature>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"currency\": \"MXN\",\n \"counterparty\": {\n \"account_number\": \"132000000000000004\",\n \"holder_id\": \"11111111-1\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"40012\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"test_key\": \"test_value\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fintoc.com/v2/transfers")
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 \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"currency\": \"MXN\",\n \"counterparty\": {\n \"account_number\": \"132000000000000004\",\n \"holder_id\": \"11111111-1\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"40012\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"test_key\": \"test_value\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "tr_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"object": "transfer",
"account_number": {
"id": "acno_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"object": "account_number",
"account_id": "acc_2hQ9vBmKpR7xLtZ3sWn1fJ4dGcA",
"created_at": "2026-03-01T12:00:00.000Z",
"deleted_at": null,
"description": "Payouts CLABE",
"is_root": false,
"last_transfer_at": null,
"metadata": {
"invoice_id": "12345"
},
"mode": "test",
"number": "646180111800000004",
"options": {
"min_amount": 1000,
"max_amount": 1000000
},
"status": "enabled",
"updated_at": "2026-03-01T12:00:00.000Z"
},
"amount": 50000,
"comment": "Payout March",
"counterparty": {
"account_number": "132000000000000004",
"account_type": "clabe",
"email": null,
"holder_id": null,
"holder_name": "Test Customer 1",
"institution": {
"id": "40132",
"name": "MULTIVA BANCO",
"country": "mx"
}
},
"currency": "MXN",
"direction": "outbound",
"entity": {
"id": "ent_2eGhTp1rLqWnXkZbYc4JsKmAvD9",
"holder_id": "000000000",
"holder_name": "Test Customer 1",
"is_root": true
},
"metadata": {
"test_key": "test_value"
},
"error_reason": null,
"mode": "test",
"post_date": null,
"receipt_url": null,
"reject_reason": null,
"reference_id": null,
"return_reason": null,
"reversed_at": null,
"failed_at": null,
"rejected_at": null,
"settled_amount": 50000,
"status": "succeeded",
"tracking_key": null,
"transaction_date": "2026-03-01T12:00:00.000Z"
}{
"error": {
"type": "invalid_request_error",
"code": "missing_parameter",
"message": "Missing required param: amount"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API Key: invalid-*oken"
}
}{
"error": {
"type": "invalid_request_error",
"code": "insufficient_balance",
"message": "Account acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN has insufficient balance"
}
}Create a transfer
Creates an outbound transfer from one of your accounts, in the live or test mode of the API key used. Requirements differ by country. In Chile, the currency is CLP and the counterparty needs a holder_id, which is the Chilean tax ID (RUT), and an institution_id. In Mexico, the currency is MXN and the counterparty’s account_number is a standardized Mexican bank account number (CLABE). Requires a JSON Web Signature (JWS) in the Fintoc-JWS-Signature header.
curl --request POST \
--url https://api.fintoc.com/v2/transfers \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Fintoc-JWS-Signature: <fintoc-jws-signature>' \
--data '
{
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"currency": "MXN",
"counterparty": {
"account_number": "132000000000000004",
"holder_id": "11111111-1",
"holder_name": "Test Customer 1",
"institution_id": "40012",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": {
"test_key": "test_value"
}
}
'import requests
url = "https://api.fintoc.com/v2/transfers"
payload = {
"account_id": "acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"amount": 50000,
"currency": "MXN",
"counterparty": {
"account_number": "132000000000000004",
"holder_id": "11111111-1",
"holder_name": "Test Customer 1",
"institution_id": "40012",
"account_type": "checking_account",
"email": "jared@piedpiper.com"
},
"comment": "Payout March",
"reference_id": "1234567",
"metadata": { "test_key": "test_value" }
}
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({
account_id: 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
amount: 50000,
currency: 'MXN',
counterparty: {
account_number: '132000000000000004',
holder_id: '11111111-1',
holder_name: 'Test Customer 1',
institution_id: '40012',
account_type: 'checking_account',
email: 'jared@piedpiper.com'
},
comment: 'Payout March',
reference_id: '1234567',
metadata: {test_key: 'test_value'}
})
};
fetch('https://api.fintoc.com/v2/transfers', 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/transfers",
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([
'account_id' => 'acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN',
'amount' => 50000,
'currency' => 'MXN',
'counterparty' => [
'account_number' => '132000000000000004',
'holder_id' => '11111111-1',
'holder_name' => 'Test Customer 1',
'institution_id' => '40012',
'account_type' => 'checking_account',
'email' => 'jared@piedpiper.com'
],
'comment' => 'Payout March',
'reference_id' => '1234567',
'metadata' => [
'test_key' => 'test_value'
]
]),
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/transfers"
payload := strings.NewReader("{\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"currency\": \"MXN\",\n \"counterparty\": {\n \"account_number\": \"132000000000000004\",\n \"holder_id\": \"11111111-1\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"40012\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"test_key\": \"test_value\"\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/transfers")
.header("Fintoc-JWS-Signature", "<fintoc-jws-signature>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"currency\": \"MXN\",\n \"counterparty\": {\n \"account_number\": \"132000000000000004\",\n \"holder_id\": \"11111111-1\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"40012\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"test_key\": \"test_value\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fintoc.com/v2/transfers")
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 \"account_id\": \"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN\",\n \"amount\": 50000,\n \"currency\": \"MXN\",\n \"counterparty\": {\n \"account_number\": \"132000000000000004\",\n \"holder_id\": \"11111111-1\",\n \"holder_name\": \"Test Customer 1\",\n \"institution_id\": \"40012\",\n \"account_type\": \"checking_account\",\n \"email\": \"jared@piedpiper.com\"\n },\n \"comment\": \"Payout March\",\n \"reference_id\": \"1234567\",\n \"metadata\": {\n \"test_key\": \"test_value\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "tr_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"object": "transfer",
"account_number": {
"id": "acno_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
"object": "account_number",
"account_id": "acc_2hQ9vBmKpR7xLtZ3sWn1fJ4dGcA",
"created_at": "2026-03-01T12:00:00.000Z",
"deleted_at": null,
"description": "Payouts CLABE",
"is_root": false,
"last_transfer_at": null,
"metadata": {
"invoice_id": "12345"
},
"mode": "test",
"number": "646180111800000004",
"options": {
"min_amount": 1000,
"max_amount": 1000000
},
"status": "enabled",
"updated_at": "2026-03-01T12:00:00.000Z"
},
"amount": 50000,
"comment": "Payout March",
"counterparty": {
"account_number": "132000000000000004",
"account_type": "clabe",
"email": null,
"holder_id": null,
"holder_name": "Test Customer 1",
"institution": {
"id": "40132",
"name": "MULTIVA BANCO",
"country": "mx"
}
},
"currency": "MXN",
"direction": "outbound",
"entity": {
"id": "ent_2eGhTp1rLqWnXkZbYc4JsKmAvD9",
"holder_id": "000000000",
"holder_name": "Test Customer 1",
"is_root": true
},
"metadata": {
"test_key": "test_value"
},
"error_reason": null,
"mode": "test",
"post_date": null,
"receipt_url": null,
"reject_reason": null,
"reference_id": null,
"return_reason": null,
"reversed_at": null,
"failed_at": null,
"rejected_at": null,
"settled_amount": 50000,
"status": "succeeded",
"tracking_key": null,
"transaction_date": "2026-03-01T12:00:00.000Z"
}{
"error": {
"type": "invalid_request_error",
"code": "missing_parameter",
"message": "Missing required param: amount"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "Invalid API Key: invalid-*oken"
}
}{
"error": {
"type": "invalid_request_error",
"code": "insufficient_balance",
"message": "Account acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN has insufficient balance"
}
}Authorizations
Headers
JWS signature of the request body. See Generate JWS keys to set up request signing.
Body
Identifier of the account the transfer is sent from.
"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN"
Amount to transfer, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit. The minimum is 1.
50000
Currency of the transfer. One of CLP, MXN.
CLP, MXN "MXN"
Recipient of the transfer.
Show child attributes
Show child attributes
Comment shown to the counterparty. Up to 40 characters.
"Payout March"
Numeric reference shown in the counterparty statement in Mexico. Up to 7 digits, with no leading zeros.
"1234567"
Set of key-value pairs you can attach to the transfer for storing additional structured information. Up to 50 pairs, with keys of up to 40 characters and string values of up to 500 characters. Values cannot be arrays or nested objects.
{ "test_key": "test_value" }
Response
The created transfer.
A movement of money between one of your accounts and a counterparty. A transfer is outbound when you send money to a counterparty, or inbound when money arrives in one of your account numbers. Fintoc settles transfers over local payment rails in Chile and Mexico.
Unique identifier of the transfer.
"tr_2daFu0zqqDtZGJaSi2TGI2Mm1nN"
Type of the object. Always transfer.
Show child attributes
Show child attributes
Amount of the transfer, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit.
50000
Comment shown to the counterparty, or null.
"Payout March"
Details of the counterparty of the transfer.
Show child attributes
Show child attributes
Currency of the transfer. One of CLP, MXN.
CLP, MXN "MXN"
Whether the transfer is inbound or outbound.
inbound, outbound "outbound"
Entity that owns the account involved in the transfer. For an inbound transfer this is the entity that received the money; for an outbound transfer, the entity that sent it.
Show child attributes
Show child attributes
Set of key-value pairs attached to the transfer.
{ "test_key": "test_value" }
Reason code for a failed transfer, or null. This field is available for Chilean transfers only. One of recipient_account_disabled_for_tef, recipient_institution_timeout, recipient_institution_unavailable, invalid_recipient_account, recipient_account_closed, invalid_recipient_holder_id, invalid_holder_id_account_relationship, account_type_not_enabled, recipient_account_not_found, product_account_not_enabled, recipient_account_credit_restricted, recipient_institution_amount_limit_exceeded, system_amount_limit_exceeded, and unknown.
recipient_account_disabled_for_tef, recipient_institution_timeout, recipient_institution_unavailable, invalid_recipient_account, recipient_account_closed, invalid_recipient_holder_id, invalid_holder_id_account_relationship, account_type_not_enabled, recipient_account_not_found, product_account_not_enabled, recipient_account_credit_restricted, recipient_institution_amount_limit_exceeded, system_amount_limit_exceeded, unknown, null null
Whether the transfer is live or test data.
live, test "test"
Time the transfer was posted, as an ISO 8601 datetime in UTC, or null.
null
URL of the transfer receipt, or null.
null
Reason code for a rejected transfer, or null. This field is available for Chilean transfers only. One of recipient_account_closed, recipient_account_credit_restricted, and unknown.
recipient_account_closed, recipient_account_credit_restricted, unknown, null null
Numeric reference shown in the counterparty statement in Mexico, or null.
null
Reason code when the transfer was returned, or null.
null
Time the transfer was reversed, as an ISO 8601 datetime in UTC, or null. This field is available for Chilean transfers only.
null
Time the transfer failed, as an ISO 8601 datetime in UTC, or null. This field is available for Chilean transfers only.
null
Time the transfer was rejected, as an ISO 8601 datetime in UTC, or null. This field is available for Chilean transfers only.
null
Settled portion of the transfer, in the smallest currency unit: centavos for MXN and pesos for CLP. Equals amount when status is succeeded, equals the settled portion when status is partially_succeeded, and equals 0 for all other statuses.
50000
Lifecycle status of the transfer. One of pending (being processed), succeeded (settled), partially_succeeded (only part of the amount settled), rejected (rejected before settling), failed (could not be processed), returned (settled, then returned to the sender), return_pending (a return is in progress), reject_failed (the rejection could not be completed), reverse_pending (a reversal is in progress), or reversed (settled, then reversed). A Chilean transfer can move from succeeded to reverse_pending and then reversed when a payment network issue requires a reversal. partially_succeeded, reverse_pending, and reversed occur for Chilean transfers only.
pending, succeeded, failed, returned, return_pending, rejected, reject_failed, partially_succeeded, reverse_pending, reversed "succeeded"
Interbank tracking key (clave de rastreo) of the transfer, or null.
null
Time the transfer occurred, as an ISO 8601 datetime in UTC, or null.
"2026-03-01T12:00:00.000Z"
Was this page helpful?