This guide will help you with the setup to receive notifications everytime you get a money in transaction
In order to get a notification, first, you have to register the endpoint where you expect the webhook.
Endpoint POST /v1/webhooks
Request
Path parameters: none Query Parameters: none
Request Body:
{
"client_id":"{{clientId}}",
"url":"https://example.com/money-in-webhook",
"token": "secretToken0123",
"webhook_type": "MONEY_IN"
}Response
Status Code: 200 OK
Response Body:
{
"id": "0c2d358f-0626-4c4e-b40b-9ab7c9dffe71",
"clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
"url": "https://example.com/webhook2",
"token": "secretToken0123",
"webhookType": "MONEY_IN",
"webhookStatus": "ACTIVE",
"createdAt": "2025-05-19 15:52:51.593012-06:00",
"updatedAt": "2025-05-19 15:52:51.593012-06:00",
"deletedAt": "None",
"blockedAt": "None",
"deletedBy": "None",
"blockedBy": "None"
}Once you register your endpoint for our webhook, you will get a request every time a money in arrive. The request will be a POST with a payload like this:
{
"id_msg": "a7a126e8-fa74-411c-ad2b-b000f277bb0d",
"msg_name": "MONEY_IN",
"msg_date": "2025-04-02",
"body": {
"id": "0196da9a-8947-703e-9a3b-bf8c7d9f6059",
"beneficiary_account": "734180123045603216", // beneficiary CLABE
"beneficiary_name": "John Smith",
"beneficiary_rfc": "XYZ123456789",
"payer_account": "137180210044008609",
"payer_name": "Juan Perez",
"payer_rfc": "XYZ987654321",
"payer_institution": "40002",
"amount": "123.00",
"transaction_date": "20250402",
"tracking_key": "50118609TBRNZ00I07219647",
"payment_concept": "Payment for invoice 4567",
"numeric_reference": "2504021"
}
}You can accept or reject a money in directly in the money in webhook, or later with a refund.
Respond to a Money in webhook with an HTTP 201 and we will consider that you accepted the money in.
Respond to a Money in webhook with an HTTP 422 and the money in will be automatically refunded. Aditionally, you can send a reason for the rejection in the Response
{
"refundReason": "Invalid Amount"
}There will be some times were you accept a money in, but for any reason, you have to refund it. You can do it with the refund endpoint
Endpoint POST /v1/clients/{{clientId}}/transactions/{{transactionId}}/refund
Request
Path parameters:
- clientId:
c2d1d1e3-3340-4170-980e-e9269bbbc551 - transactionId:
e43171ad-af3b-40e3-913c-24cc386bf5ffThis is send in the money in webhook Query Parameters: none
Request Body:
{
"description": "Lorem ipsum",
"amount": "9.99"
}Response
Status Code: 200 OK
Response Body:
{
"id": "e43171ad-af3b-40e3-913c-24cc386bf5ff",
"bankId": "1953a92c-11e5-4315-b406-b89dd6b699b4",
"clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
"externalReference": "2505201",
"trackingId": "20250520FINCHARNJK5NHQG",
"description": "Lorem ipsum",
"amount": "9.99",
"currency": "MXN",
"category": "DEBIT_TRANS",
"subCategory": "SPEI_DEBIT",
"transactionStatus": "LIQUIDATED",
"audit": {
"createdAt": "2025-05-20 10:57:44.220281-06:00",
"updatedAt": "2025-05-20 10:57:44.220281-06:00",
"deletedAt": "None",
"blockedAt": "None"
},
"originalTransactionId": "a1392ef1-75f2-457a-8203-d4fd4b435559"
}Take note that the /refund endpoint return a transaction data, this is because we need to create a new SPEI transaction to return the money to the original sourcing account.
In this case, you will have 2 transaction, the original with transactionStatus REFUNDED and the return, with transactionStatus LIQUIDATED.
You can retrieve the details of a transaction with a call to:
Endpoint GET /v1/clients/{{clientId}}/transactions/{{transactionId}}
Request
Path parameters:
- clientId:
c2d1d1e3-3340-4170-980e-e9269bbbc551 - transactionId:
e43171ad-af3b-40e3-913c-24cc386bf5ffThis is send in the money in webhook Query Parameters: none
Response
Status Code: 200 OK
Response Body:
{
"id": "e43171ad-af3b-40e3-913c-24cc386bf5ff",
"bankId": "1953a92c-11e5-4315-b406-b89dd6b699b4",
"clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
"externalReference": "2505201",
"trackingId": "20250520FINCHARNJK5NHQG",
"description": "Lorem ipsum",
"amount": "9.99",
"currency": "MXN",
"category": "DEBIT_TRANS",
"subCategory": "SPEI_DEBIT",
"transactionStatus": "LIQUIDATED",
"audit": {
"createdAt": "2025-05-20 10:57:44.220281-06:00",
"updatedAt": "2025-05-20 10:57:44.220281-06:00",
"deletedAt": "None",
"blockedAt": "None"
},
"jsonReference": "{'transaction_date': '2025-05-20 10:14:05', 'payer_institution': '40012', 'beneficiary_institution': '90734', 'tracking_key': '20250520FINCHBQ1XEUUSP02', 'amount': '9.99', 'payment_type': '1', 'payer_name': 'Client MX', 'payer_account': '014910606138059212', 'payer_rfc': 'ND', 'destination_instrument_id': '709448c3-7cbf-454d-a87e-feb23801269a', 'destination_account_id': '24a726ac-180d-48df-82bc-711f2788a46f', 'payer_account_type': '40', 'payment_concept': 'Fondeo Redocly CS MoneyIn', 'numeric_reference': '2505201', 'beneficiary_account_type': '40', 'beneficiary_account': '734180000001000004', 'beneficiary_rfc': 'XXXA010101000', 'beneficiary_name': 'Finch Principal', 'client_id': 'c2d1d1e3-3340-4170-980e-e9269bbbc551', 'vat': '', 'package_folio': '4', 'spei_folio': '000005', 'indirect_payer_institution_name': '', 'indirect_payer_institution_account': '', 'indirect_payer_institution_rfc': ''}",
"sourceInstrument": {
"id": "709448c3-7cbf-454d-a87e-feb23801269a",
"bankId": "9d84b03a-28d1-4898-a69c-38824239e2b1",
"clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
"ownerId": "24a726ac-180d-48df-82bc-711f2788a46f",
"instrumentAlias": "InternalAccount",
"instrumentStatus": "ACTIVE",
"instrumentType": "SENDER_RECEIVER",
"instrumentDetail": {
"accountNumber": "000001000004",
"clabeNumber": "734180123045603216",
"holderName": "Test my Test"
},
"rfc": "ND"
},
"destinationInstrument": {
"id": "9486251b-6706-4aa1-b844-8531de595244",
"bankId": "1953a92c-11e5-4315-b406-b89dd6b699b4",
"clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
"ownerId": "24a726ac-180d-48df-82bc-711f2788a46f",
"instrumentAlias": "Client MX",
"instrumentStatus": "ACTIVE",
"instrumentType": "SENDER_RECEIVER",
"instrumentDetail": {
"accountNumber": "06138059212",
"clabeNumber": "014910606138059212",
"holderName": "Client MX"
},
"rfc": "ND"
}
}