> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Enviar transferencias > Inicia pagos en tiempo real usando nuestra API de Transferencias salientes Para crear transferencias salientes con la API de Transferencias de Fintoc, completa la guía de configuración y luego sigue estos pasos: 1. Configura las llaves de firma JSON Web Signature (JWS) y genera una firma JWS. 2. Agrega fondos al `root_account_number` de la cuenta. 3. Desde tu backend, crea una transferencia usando tu **Secret Key** y una **firma JWS**. 4. Monitorea el estado de la transferencia. El siguiente diagrama muestra cómo Fintoc interactúa contigo y con la contraparte que recibe el payout. ## Paso 1: Configurar las llaves de firma JWS y generar una firma JWS Cada solicitud a los endpoints de Transferencias de Fintoc requiere una firma JWS. JWS es un mecanismo estándar utilizado para firmar digitalmente una pieza de datos con el fin de garantizar su integridad y autenticidad. Para aprender a firmar una llamada a la API, sigue los pasos de la [guía de firma JWS](/es/docs/transfers/transfers-setup/setting-up-jws-keys). ## Paso 2: Agregar fondos a Fintoc Para crear transferencias, primero fondea tu `Account` agregando fondos al `root_account_number`. El depósito aparece como una transferencia entrante. ## Paso 3: Crear una transferencia Después de agregar fondos a tu cuenta, crea una transferencia desde tu backend. Incluye tu **Secret Key** de prueba, **firma JWS**, cuenta de origen, monto, moneda y contraparte. Los ejemplos siguientes muestran respuestas exitosas de transferencia. Para probar resultados fallidos, usa la tabla de estados terminales en la sección [Probar la integración](#test-the-integration) más abajo. ### Usa una clave de idempotencia Fintoc admite [idempotencia](https://en.wikipedia.org/wiki/Idempotence) para reintentar transferencias de manera segura sin crear una transferencia duplicada. Al crear una transferencia, usa una clave de idempotencia. Si ocurre un error de conexión, repite la solicitud de manera segura. Para realizar una solicitud idempotente, proporciona un header `Idempotency-Key` en la solicitud. [Aprende más sobre solicitudes idempotentes en esta guía](/es/reference/fintoc-api/idempotent-requests). ### Crear una transferencia para México 🇲🇽 A continuación se muestra un ejemplo que crea una transferencia de $590.13 MXN. El campo `amount` está en la unidad mínima de la moneda, por lo que $590.13 es el entero `59013`. ```curl curl theme={null} curl --request POST \ --url https://api.fintoc.com/v2/transfers \ --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \ --header 'Fintoc-JWS-Signature: CNMaYaDGU3ZhFV1ve6p3sAdYXhEklej8DVIAMqIWCkpNmT6Jp7iigcndXwH5q3WQFHiswgIQU5-_-4rV3jKGptCROmEyWPW8_elhYH1apzAyjOjyZ55ygv37xKHzIFhixzAwmXlAv4pfD4lVelYWVNOSN7REA0QJeCy2vKdqZ5cjqCXQ1lkQUlzOE7dpuNoAkhAhAJJ8HaamFKy7Gl7uwmqbIr-dVYv21d_9O7mO26n0gy3zWXD2nJDxU5Mzl2pZd8-sFvUr9Kmp_YkeRMh4bSe0fr1Uc_YgkjpmYUyu7kaxRWTbAdJ3GwqWFMUDiyfhHdzvZPZyU4VkWreimoydMA' \ --header 'Idempotency-Key: 1ebfd86c-a75b-4606-872f-9f1cdd9724ca' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "amount": 59013, "currency": "mxn", "account_id": "acc_M8sKf230BgHjD4", "comment": "Pago de credito 10451", "reference_id": "150195", "counterparty": { "account_number": "000000000000000000" }, "metadata": { "customer_id": "12050123" } } ' ``` ```node Node theme={null} const transfer = await fintoc.v2.transfers.create({ idempotency_key: '1ebfd86c-a75b-4606-872f-9f1cdd9724ca', amount: 59013, currency: 'mxn', account_id: 'acc_M8sKf230BgHjD4', comment: 'Pago de credito 10451', reference_id: '150195', counterparty: { account_number: '000000000000000000' }, metadata: { customer_id: '12050123' } }); ``` ```python Python theme={null} transfer = client.v2.transfers.create( idempotency_key="1ebfd86c-a75b-4606-872f-9f1cdd9724ca", amount=59013, currency="mxn", account_id="acc_M8sKf230BgHjD4", comment="Pago de credito 10451", reference_id="150195", counterparty={"account_number": "000000000000000000"}, metadata={"customer_id": "12050123"} ) ``` Una respuesta exitosa se ve así: ```json theme={null} { "object": "transfer", "id": "tr_jKaHD105H", "amount": 59013, "currency": "mxn", "direction": "outbound", "status": "succeeded", "transaction_date": "2020-04-17T05:12:41.462Z", "post_date": "2020-04-17T00:00:00.000Z", "comment": "Pago de credito 10451", "reference_id": "150195", "tracking_key": "s2123423423324334", "receipt_url": "https://www.banxico.org.mx/cep/", "mode": "test", "return_reason": null, "counterparty": { "holder_id": "AAA010101AAA", "holder_name": "Test Customer 1", "account_number": "000000000000000000", "account_type": "clabe", "institution": { "id": "mx_bbva_mexico", "name": "BBVA Mexico", "country": "mx" } }, "account_number": { "id": "acno_Kasf91034gj1AD", "account_id": "acc_Jas92lf9adg94ka", "number": "111111111111111111", "created_at": "2024-03-01T20:09:42.949787176Z", "mode": "test", "description": null, "metadata": {}, "object": "account_number" }, "metadata": { "customer_id": "12050123" } } ``` **Las monedas se representan como enteros** Por ejemplo, Fintoc representa **MXN \$10.29** como `1029`. Puedes [leer más sobre monedas aquí](/es/docs/home/currencies). **Recuerda agregar el institution ID** Al transferir a una CLABE, no es necesario un institution ID de contraparte. Fintoc deduce la institución a partir del número de CLABE. Si tu contraparte es un **número de teléfono móvil** o una **tarjeta de débito**, incluye el institution ID como un número de 5 dígitos, como se muestra [aquí](https://www.banxico.org.mx/cep-scl/listaInstituciones.do). De lo contrario, obtendrás un error `400 Bad Request`. En México, el objeto `Counterparty` requiere un atributo: | Parámetro | Descripción | | :--------------- | :------------------------------------------------------------------------------------------------------ | | `account_number` | Número de cuenta bancaria del destinatario (🇲🇽 CLABE, número de móvil o número de tarjeta de débito). |
### Crear una transferencia para Chile 🇨🇱 A continuación se muestra un ejemplo que crea una transferencia de \$1,869 CLP. Como CLP no tiene unidad menor, el campo `amount` es el mismo entero, `1869`. ```curl curl theme={null} curl --request POST \ --url https://api.fintoc.com/v2/transfers \ --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \ --header 'Fintoc-JWS-Signature: CNMaYaDGU3ZhFV1ve6p3sAdYXhEklej8DVIAMqIWCkpNmT6Jp7iigcndXwH5q3WQFHiswgIQU5-_-4rV3jKGptCROmEyWPW8_elhYH1apzAyjOjyZ55ygv37xKHzIFhixzAwmXlAv4pfD4lVelYWVNOSN7REA0QJeCy2vKdqZ5cjqCXQ1lkQUlzOE7dpuNoAkhAhAJJ8HaamFKy7Gl7uwmqbIr-dVYv21d_9O7mO26n0gy3zWXD2nJDxU5Mzl2pZd8-sFvUr9Kmp_YkeRMh4bSe0fr1Uc_YgkjpmYUyu7kaxRWTbAdJ3GwqWFMUDiyfhHdzvZPZyU4VkWreimoydMA' \ --header 'Idempotency-Key: 1ebfd86c-a75b-4606-872f-9f1cdd9724ca' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "amount": 1869, "currency": "clp", "account_id": "acc_M8sKf230BgHjD4", "comment": "Pago de credito 10451", "counterparty": { "holder_id": "11.111.111-1", "holder_name": "Test Customer 1", "account_number": "000000000", "account_type": "checking_account", "institution_id": "cl_banco_de_chile" }, "metadata": { "customer_id": "12050123" } } ' ``` ```node Node theme={null} const transfer = await fintoc.v2.transfers.create({ idempotency_key: '1ebfd86c-a75b-4606-872f-9f1cdd9724ca', amount: 1869, currency: 'clp', account_id: 'acc_M8sKf230BgHjD4', comment: 'Pago de credito 10451', counterparty: { holder_id: '11.111.111-1', holder_name: 'Test Customer 1', account_number: '000000000', account_type: 'checking_account', institution_id: 'cl_banco_de_chile' }, metadata: { customer_id: '12050123' } }); ``` ```python Python theme={null} transfer = client.v2.transfers.create( idempotency_key="1ebfd86c-a75b-4606-872f-9f1cdd9724ca", amount=1869, currency="clp", account_id="acc_M8sKf230BgHjD4", comment="Pago de credito 10451", counterparty={ "holder_id": "11.111.111-1", "holder_name": "Test Customer 1", "account_number": "000000000", "account_type": "checking_account", "institution_id": "cl_banco_de_chile" }, metadata={"customer_id": "12050123"} ) ``` Una respuesta exitosa se ve así: ```json theme={null} { "object": "transfer", "id": "tr_jKaHD105H", "amount": 1869, "currency": "clp", "direction": "outbound", "status": "succeeded", "transaction_date": "2020-04-17T05:12:41.462Z", "post_date": "2020-04-17T00:00:00.000Z", "comment": "Pago de credito 10451", "reference_id": null, "receipt_url": null, "tracking_key": null, "mode": "test", "return_reason": null, "counterparty": { "holder_id": "11.111.111-1", "holder_name": "Test Customer 1", "account_number": "000000000", "account_type": "checking_account", "institution": { "id": "cl_banco_de_chile", "name": "Banco de Chile", "country": "cl" } }, "account_number": { "id": "acno_Kasf91034gj1AD", "account_id": "acc_Jas92lf9adg94ka", "number": "111111111111111111", "created_at": "2024-03-01T20:09:42.949787176Z", "mode": "test", "object": "account_number", "description": null, "metadata": {} }, "metadata": { "customer_id": "12050123" } } ``` En Chile, el objeto `Counterparty` requiere cinco atributos: | Parámetro | Descripción | | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `holder_id` | El [RUT chileno](https://es.wikipedia.org/wiki/Rol_%C3%9Anico_Tributario) del titular de la cuenta. | | `holder_name` | Nombre completo del titular de la cuenta. | | `account_number` | Número de cuenta bancaria del destinatario en la institución de la contraparte. | | `account_type` | Tipo de cuenta. Los tipos admitidos son `checking_account` y `sight_account`. | | `institution_id` | El institution ID de Fintoc para el banco que recibe la transferencia. Puedes ver el [código de cada institución aquí](/es/reference/fintoc-api/chile-institution-codes). | ## Paso 4: Monitorear el estado de la transferencia ### Flujo de estados de la transferencia El estado de una transferencia es uno de `pending`, `succeeded`, `failed`, `returned`, `return_pending` o `rejected`. Para más detalles sobre los estados de transferencia, consulta el [modelo de datos de Transferencias](/es/docs/transfers/transfers-overview/v2-transfers-data-model). ### Monitorear el estado usando webhooks Fintoc envía un evento `transfer.outbound.succeeded` cuando la transferencia se liquida. Usa la [guía de webhooks](/es/docs/resources/webhooks-walkthrough) para recibir estos eventos y ejecutar acciones, como enviar un correo de notificación a tu cliente o registrar la transferencia en tu ERP. Recomendamos manejar los siguientes eventos: | Evento | Descripción | | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transfer.outbound.succeeded` | Se envía cuando la transferencia se envía exitosamente. | | `transfer.outbound.rejected` | 🇲🇽 En México, Fintoc envía este evento cuando Banco de México o la institución de la contraparte rechaza la transferencia. Consulta las [causas de rechazo](/es/reference/transfers-api/transfers/spei-codes).

🇨🇱 En Chile: Se envía cuando la institución de la contraparte ha rechazado la transferencia.

`rejected` es un estado final y no sufre cambios posteriores. | | `transfer.outbound.failed` | Se envía cuando la transferencia no ha podido llegar a su cuenta destino debido a un error durante el proceso. | **Los webhooks pueden llegar en desorden** Por ejemplo: un evento de webhook `transfer.outbound.rejected` podría llegar antes que el webhook `transfer.outbound.succeeded` de la misma transferencia, aunque la transferencia primero haya tenido éxito y luego haya sido rechazada. ## Probar la integración Usa tu **Secret Key** de prueba (`sk_test_...`) para ejecutar transferencias en modo `test` sin mover dinero real. Cada respuesta incluye `"mode": "test"`. En modo `test`, una transferencia alcanza los mismos estados terminales que en producción. El resultado no se fuerza mediante una entrada predefinida. Depende de cómo la parte receptora resuelva la transferencia. Usa los tres estados terminales para confirmar tu manejo de webhooks: | Resultado | Estado resultante | Evento del webhook | | :-------- | :---------------- | :---------------------------- | | Exitoso | `succeeded` | `transfer.outbound.succeeded` | | Rechazado | `rejected` | `transfer.outbound.rejected` | | Fallido | `failed` | `transfer.outbound.failed` |