Transferencias bancarias

Eventos de webhook para transferencias bancarias, lotes y créditos a la cuenta.

Cuando se crean transferencias bancarias y luego son aprobadas, rechazadas o reintentadas con un fallback routing, se envía un evento de webhook a una URL especificada con los detalles de la transferencia y su estado actual. Esto permite a los clientes recibir actualizaciones en tiempo real del estado de sus transferencias y tomar las acciones apropiadas según los eventos recibidos.

Tipos de evento

Los siguientes tipos de evento están relacionados con transferencias bancarias:

Evento	Descripción
`bank_transfer_approved`	Disparado cuando una transferencia bancaria es aprobada.
`bank_transfer_rejected`	Disparado cuando una transferencia bancaria es rechazada.
`bank_transfer_fallback_routing`	Disparado cuando una transferencia bancaria es reintentada con un routing diferente.
`bank_transfer_change_final_state`	Disparado cuando una transferencia ya en estado final pasa a un estado final distinto.
`account_credited`	Disparado cuando una transferencia entrante es acreditada exitosamente a tu cuenta.

Ejemplo de payload

{
  "event": {
    "data": {
      "amount": {
        "amount": 1600000,
        "currency": "COP"
      },
      "batch": {
        "account_id": "acc_16ktUqSO7G0qTHDz8I3qrG",
        "id": "bat_2DpSchlriwoCuyGMOoIuwp",
        "inserted_at": "2022-12-28T16:19:52.471575Z",
        "origin": "api",
        "state": "declined",
        "total_amount": {
          "amount": 1600000,
          "currency": "COP"
        },
        "updated_at": "2022-12-28T16:40:06.822840Z"
      },
      "declination_reason": null,
      "description": "some description",
      "entity_id": "123456789",
      "id": "trn_2PVWOx9dZKJMBZw7opjrrs",
      "inserted_at": "2022-12-28T16:19:52.530158Z",
      "payee": {
        "bank_account": {
          "bank_code": "007",
          "number": "000000009",
          "type": "savings_account"
        },
        "document_number": "1033711400",
        "document_type": "CC",
        "email": "someone@gmail.com",
        "name": "patricio rothschild"
      },
      "recipient_handle": null,
      "reference": "ref # 1231",
      "state": "approved",
      "updated_at": "2022-12-28T16:40:06.812742Z",
      "routing": "ach",
      "fallback_routing": []
    },
    "type": "bank_transfer_approved"
  },
  "timestamp": "2022-12-28T16:54:38.660650Z"
}

Transferencia rechazada

Cuando el tipo de evento es bank_transfer_rejected, el campo declination_reason será un string indicando la razón del rechazo:

{
  "event": {
    "data": {
      "declination_reason": "insufficient_funds",
      "state": "declined"
    },
    "type": "bank_transfer_rejected"
  },
  "timestamp": "2022-12-28T16:54:38.660650Z"
}

Eventos de lote

Se envía una solicitud de webhook relacionada con un lote cuando:

El lote fue creado con todas sus transferencias como duplicadas (con entity_id previamente registrado)
El lote fue solicitado para autorización
El lote fue enviado a procesar
El lote fue cancelado

Ejemplo de payload del lote

{
  "event": {
    "data": {
      "account_id": "acc_16ktUqSO7G0qTHDz8I3qrG",
      "id": "bat_5d60uR36JfH4J4uN9ZEYhL",
      "inserted_at": "2022-12-28T18:01:21.549268Z",
      "origin": "api",
      "state": "duplicated",
      "total_amount": {
        "amount": 100000,
        "currency": "COP"
      },
      "transfers": [
        {
          "amount": {
            "amount": 100000,
            "currency": "COP"
          },
          "declination_reason": null,
          "description": "eaque qui dolorem",
          "entity_id": "d31d1c0d-395b-43f4-b57b-a3ae4b8c34d6",
          "id": "trn_5NYRqKnE17nE0MswylZzq1",
          "inserted_at": "2022-12-28T18:01:21.602854Z",
          "payee": {
            "bank_account": {
              "bank_code": "007",
              "number": "123456789",
              "type": "savings_account"
            },
            "document_number": "123456789",
            "document_type": "CC",
            "email": "someone@gmail.com",
            "name": "Ginger Gutmann"
          },
          "recipient_handle": "573004366648",
          "reference": "quasi sint inventore",
          "state": "duplicated",
          "updated_at": "2022-12-28T18:01:21.602854Z"
        }
      ],
      "updated_at": "2022-12-28T18:01:21.765972Z"
    },
    "type": "batch_duplicated"
  },
  "timestamp": "2022-12-28T18:01:36.586019Z"
}

El tipo de evento del webhook variará según lo que le pasó al lote:

Evento	Descripción
`batch_duplicated`	Todas las transferencias del lote ya fueron recibidas (`entity_id` duplicado).
`batch_authorization_requested`	El lote requiere autorización OTP de un administrador antes de ser enviado.
`batch_sent`	El lote fue autorizado y despachado para procesamiento.
`batch_canceled`	El lote fue cancelado por un administrador antes de ser procesado.

Cuenta acreditada

Cuando una transferencia es exitosa y el dinero está en tu cuenta, se enviará una solicitud de webhook.

Ejemplo de payload

{
  "event": {
    "data": {
      "account": {
        "id": "acc_16ktUqSO7G0qTHDz8I3qrG",
        "number": "095000036"
      },
      "amount": {
        "amount": 105000,
        "currency": "COP"
      },
      "description": "some description, abcde...",
      "extra": {
        "entity_id": null,
        "reference": "some ref: #123..."
      },
      "id": "tx_3RJ9CbZLYq7r1MxH8vAm7Y",
      "payer": {
        "document_number": "9013980684",
        "name": "MONO COLOMBIA S.A.S.",
        "bank": {
          "name": "BANCO COOPERATIVO COOPCENTRAL",
          "code": "066"
        }
      },
      "transaction_at": "2023-03-08T17:20:55.809787Z",
      "type": "bank_transfer_mono"
    },
    "type": "account_credited"
  },
  "timestamp": "2023-03-08T17:21:01.673116Z"
}

Tipos de transferencia

Hay dos tipos de transferencias, que se identifican por el campo type en el objeto data:

Tipo	Descripción
`bank_transfer_mono`	Una transferencia en tiempo real hecha por el sistema interno de Mono.
`incoming_wire`	Una transferencia hecha vía ACH.

Si el tipo es incoming_wire, el campo extra en el objeto data estará vacío.

Campos del objeto extra

El objeto extra en el objeto data contiene los siguientes campos:

entity_id: el ID de la entidad para la transferencia.
reference: la referencia de la transferencia.

Estos campos se configuran cuando creas una transferencia bancaria usando la API.

Transferencias bancarias

En esta página