Bank transfers webhooks

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:

bank_transfer_approved: This event is triggered when a bank transfer is approved.
bank_transfer_rejected: This event is triggered when a bank transfer is declined.
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"
            },
            "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"
}

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"
                    },
                    "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 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.