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:
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_monois a real-time transfer that was made via Mono's internal system.incoming_wireis 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_idThe ID of the entity for the transfer, for more details seereferenceThe reference of the transfer, for more detail see.
Note that the above fields are set when you create a bank transfer using the API.