Sign in

v1

latestOpenAPI 3.1.02026-07-228956435.8 KB
Transfers

Return a transfer

Returns an inbound transfer to its original sender. You can only return MXN transfers. Requires a JSON Web Signature (JWS) in the Fintoc-JWS-Signature header.

post/transfers/return

Headers

Fintoc-JWS-Signaturestring required

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

Request body

transfer_idstring required

Identifier of the inbound transfer to return.

Example request

{
  "transfer_id": "tr_2daFu0zqqDtZGJaSi2TGI2Mm1nN"
}

Response

The original inbound transfer, now return_pending.

idstring required

Unique identifier of the transfer.

object'transfer' required

Type of the object. Always transfer.

amountinteger required

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

commentstring nullable required

Comment shown to the counterparty, or null.

currency'CLP' | 'MXN' required

Currency of the transfer. One of CLP, MXN.

direction'inbound' | 'outbound' required

Whether the transfer is inbound or outbound.

metadataobject required

Set of key-value pairs attached to the transfer.

mode'live' | 'test' required

Whether the transfer is live or test data.

post_datestring date-time nullable required

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

receipt_urlstring nullable required

URL of the transfer receipt, or null.

reference_idstring nullable required

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

return_reasonstring nullable required

Reason code when the transfer was returned, or null.

status'succeeded' | 'rejected' | 'failed' | 'pending' | 'returned' | 'return_pending' | 'reject_failed' 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).

tracking_keystring nullable required

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

transaction_datestring date-time nullable required

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

Example response

{
  "id": "tr_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "account_number": {
    "id": "acno_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
    "account_id": "acc_2hQ9vBmKpR7xLtZ3sWn1fJ4dGcA",
    "created_at": "2026-03-01T12:00:00.000Z",
    "description": "Payouts CLABE",
    "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",
    "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",
  "status": "succeeded",
  "transaction_date": "2026-03-01T12:00:00.000Z"
}