Bank transfers webhooks

webhooks documentation

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.

The following event types are related to bank transfers:

  1. bank_transfer_approved: This event is triggered when a bank transfer is approved.
  2. bank_transfer_rejected: This event is triggered when a bank transfer is declined.
  3. bank_transfer_fallback_routing: This event is triggered when a bank transfer is attempted with another routing.

An example of how the webhook event payload will be structured:

{
    "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": "[email protected]",
                "name": "patricio rothschild"
            },
            "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"
}

Note that 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 of transfers, authorizaton requested, sent, canceled and duplicated

A webhook request is going to be send 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
{
    "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": "[email protected]",
                        "name": "Ginger Gutmann"
                    },
                    "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 difference to be highlighted in the event data is the state field that will vary according to the type of event that occurred. The possible states can be:

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

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

  • bank_transfer_mono is a real-time transfer that was made via Mono's internal system.
  • incoming_wire is a wire transfer that was made via ACH.

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

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

  • entity_id The ID of the entity for the transfer, for more details see
  • reference The reference of the transfer, for more detail see.
    Note that the above fields are set when you create a bank transfer using the API.