Create a transfer

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": "<unknown>",
  "account_number": {
    "id": "acno_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "object": "<unknown>",
    "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": "646180111800000000",
    "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"
  },
  "mode": "test",
  "post_date": null,
  "receipt_url": null,
  "reference_id": null,
  "return_reason": null,
  "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"
  }
}

POST

transfers

Create a transfer

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": "<unknown>",
  "account_number": {
    "id": "acno_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "object": "<unknown>",
    "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": "646180111800000000",
    "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"
  },
  "mode": "test",
  "post_date": null,
  "receipt_url": null,
  "reference_id": null,
  "return_reason": null,
  "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"
  }
}

v2 · Base URL https://api.fintoc.com/v2

Authorizations

Authorization

string

header

required

Headers

Fintoc-JWS-Signature

string

required

JWS signature of the request body. See Generate JWS keys to set up request signing.

Body

application/json

account_id

string

required

Identifier of the account the transfer is sent from.

Example:

"acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN"

amount

integer

required

Amount to transfer, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit. The minimum is 1.

Example:

50000

currency

enum<string>

required

Currency of the transfer. One of CLP, MXN.

Available options:

CLP,

MXN

Example:

"MXN"

counterparty

object

required

Recipient of the transfer.

Show child attributes

comment

string

Comment shown to the counterparty.

Example:

"Payout March"

reference_id

string

Numeric reference shown in the counterparty statement in Mexico. Up to 7 digits, with no leading zeros.

Example:

"1234567"

metadata

object

Set of key-value pairs you can attach to the transfer for storing additional structured information.

Example:

{ "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.

string

required

Unique identifier of the transfer.

Example:

"tr_2daFu0zqqDtZGJaSi2TGI2Mm1nN"

object

any

required

Type of the object. Always transfer.

account_number

object

required

Show child attributes

amount

integer

required

Amount of the transfer, in the smallest currency unit. For MXN this is centavos; CLP has no minor unit.

Example:

50000

comment

string | null

required

Comment shown to the counterparty, or null.

Example:

"Payout March"

counterparty

object

required

Details of the counterparty of the transfer.

Show child attributes

currency

enum<string>

required

Currency of the transfer. One of CLP, MXN.

Available options:

CLP,

MXN

Example:

"MXN"

direction

enum<string>

required

Whether the transfer is inbound or outbound.

Available options:

inbound,

outbound

Example:

"outbound"

entity

object

required

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

metadata

object

required

Set of key-value pairs attached to the transfer.

Example:

{ "test_key": "test_value" }

mode

enum<string>

required

Whether the transfer is live or test data.

Available options:

live,

test

Example:

"test"

post_date

string<date-time> | null

required

Time the transfer was posted, as an ISO 8601 datetime in UTC, or null.

Example:

null

receipt_url

string | null

required

URL of the transfer receipt, or null.

Example:

null

reference_id

string | null

required

Numeric reference shown in the counterparty statement in Mexico, or null.

Example:

null

return_reason

string | null

required

Reason code when the transfer was returned, or null.

Example:

null

status

enum<string>

required

Lifecycle status of the transfer. One of pending (being processed), succeeded (settled), rejected (rejected before settling), failed (could not be processed), returned (settled, then returned to the sender), return_pending (a return is in progress), or reject_failed (the rejection could not be completed).

Available options:

succeeded,

rejected,

failed,

pending,

returned,

return_pending,

reject_failed

Example:

"succeeded"

tracking_key

string | null

required

Interbank tracking key (clave de rastreo) of the transfer, or null.

Example:

null

transaction_date

string<date-time> | null

required

Time the transfer occurred, as an ISO 8601 datetime in UTC, or null.

Example:

"2026-03-01T12:00:00.000Z"

Transfer object List transfers

Fintoc API

Main Resources

Payments API

Transfers API

Movements API

Direct Debit (Legacy)

Fiscal API

Create a transfer

Authorizations

Headers

Body

Response