Bank Transfers

When bank transfers are created and then either approved, rejected, or retried with a fallback routing, a webhook event will be sent to a specified URL with details of the transfer and its current state. This allows clients to receive real-time updates on the status of their transfers and take appropriate actions based on the events received.

Event Types

The following event types are related to bank transfers:

Event	Description
`bank_transfer_approved`	Triggered when a bank transfer is approved.
`bank_transfer_rejected`	Triggered when a bank transfer is declined.
`bank_transfer_fallback_routing`	Triggered when a bank transfer is attempted with another routing.

Payload Example

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

Rejected Transfer

When the event type is bank_transfer_rejected, the field declination_reason will be a string indicating the reason for the rejection:

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

Batch Events

A webhook request is sent related to a batch when:

The batch was created with all its transfers as duplicated (with previously registered entity_id)
The batch was requested for authorization
The batch was sent to process
The batch was canceled

Batch Payload Example

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

The state field will vary according to the type of event that occurred. The possible states are:

duplicated
pending_otp
processing_transactions
cancelled

Account Credited

When a transfer is successful and the money is in your account, a webhook request will be sent.

Payload Example

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

Transfer Types

There are two types of transfers, which can be identified by the type field in the data object:

Type	Description
`bank_transfer_mono`	A real-time transfer made via Mono's internal system.
`incoming_wire`	A wire transfer made via ACH.

If the type is incoming_wire, the extra field in the data object will be empty.

Extra Object Fields

The extra object in the data object contains the following fields:

entity_id: The ID of the entity for the transfer.
reference: The reference of the transfer.

These fields are set when you create a bank transfer using the API.

Bank Transfers

On this page