webhooks documentation
Card transactions events
When an operation involving a card transaction is done, a webhook request is generated based on
the transaction type. This documentation outlines the event types related to card transactions.
Event types
-
authorization_approved: This event is triggered when a card transaction has been authorized. For example, after making a purchase or a payment with a card. It means a card transaction has been approved and therefore a charge will be reflected on the account's balance. -
authorization_declined: This event is triggered when a card transaction has not been authorized. It includes adeclination_reasonto understand better the reason behind the denied card transaction. It doesn't reflect any change on the account's balance. -
withdrawal: This event is triggered when a withdrawal has been authorized. For example, when the card owner withdraws money from a ATM. It includes awithdrawal_feedetail. -
credit_adjustment: This event is triggered when an authorization is updated by a partial refund. This means a card transaction has been approved and there will be a refund reflected in the account balance. Apartial refundis when part of the purchase value is returned to the account. -
debit_adjustment: This event is triggered when an authorization is updated with a new amount. This means a card transaction has been approved and charged, and then a new charge is done to update the previous authorization. -
force_debit: This event is triggered when a transaction is made without a previous authorization. This means that a charge will be done without taking into account the account's balance. It also means that there is nooriginal_transaction_idnorprevious_values. -
authorization_reversed: This event is triggered when a transaction is reversed and the value of the initial charge is returned fully to the account. -
refund: This event is triggered when a refund is made to the account. The value of the refund can be related or not to a previous authorization.
Nullable fields
Depending on the type of the notification, the following fields could be null:
- withdrawal_fee: is null when there was no fee (ie: the card transaction was not in an ATM).
- fx_rates: is null when the amount was charged in COP.
- declination_reason: is null when the operation was successful.
- original_transaction_id: then the operation does not involve a previous transaction.
- previous_values
Payload examples
authorization_approved:
{
"event": {
"type": "card_transaction",
"data": {
"type": "authorization_approved",
"id": "ctx_5tgliBmzj6thQPRbQjfKj",
"inserted_at": "2023-06-15T10:30:00.000Z",
"state": "approved",
"card": {
"id": "car_5tgliBmlpZ6mpQPRbQjfKj",
"last_four": "1234"
},
"cardholder_id": "cah_7MkWDrqvfosB8fzHhb1Eql",
"declination_reason": null,
"original_transaction_id": null,
"merchant": {
"id": "merchant_789012345",
"name": "Nombre del Comercio",
"mcc": "string",
"amount": {
"amount": 1600,
"currency": "USD"
}
},
"amount": {
"amount": 1600,
"currency": "USD"
},
"settlement_amount": {
"amount": 1600,
"currency": "USD"
},
"withdrawal_fee": null,
"fx_rates": {
"USD": "1",
"COP": "4002,24"
},
"previous_values": null
},
"timestamp": "2023-06-15T10:35:00.000Z"
}
}
authorization_declined:
{
"event": {
"type": "card_transaction",
"data": {
"type": "authorization_declined",
"id": "ctx_5tgliBmzjZ6mpQPRbQjfKj",
"inserted_at": "2023-06-15T10:30:00.000Z",
"state": "declined",
"card": {
"id": "car_5tgliBmzjZ6mpQPRbQjfKj",
"last_four": "1234"
},
"cardholder_id": "cah_7MkWaFqvfosB8fzHhb1Eql",
"declination_reason": "insufficient_funds",
"original_transaction_id": null,
"merchant": {
"id": "merchant_789012345",
"name": "Nombre del Comercio",
"mcc": "string",
"amount": {
"amount": 160,
"currency": "USD"
}
},
"amount": {
"amount": 160,
"currency": "USD"
},
"settlement_amount": {
"amount": 160,
"currency": "USD"
},
"withdrawal_fee": null,
"fx_rates": {
"USD": "1",
"COP": "4002,24"
},
"previous_values": null
},
"timestamp": "2023-06-15T10:35:00.000Z"
}
}
withdrawal:
{
"event": {
"type": "card_transaction",
"data": {
"type": "withdrawal",
"id": "ctx_5tgliBrejZ6mpQPRbQjfKj",
"inserted_at": "2023-06-15T10:30:00.000Z",
"state": "approved",
"card": {
"id": "car_5tgliBmzjZ6mpQPRbQjfKj",
"last_four": "1234"
},
"cardholder_id": "cah_7MkAqFqvfosB8fzHhb1Eql",
"declination_reason": null,
"original_transaction_id": null,
"withdrawal_fee": {
"amount": 240000,
"currency": "COP"
},
"merchant": {
"id": "merchant_789012345",
"name": "Nombre del Comercio",
"mcc": "string",
"amount": {
"amount": 5000000,
"currency": "COP"
}
},
"amount": {
"amount": 5000000,
"currency": "COP"
},
"settlement_amount": {
"amount": 5000000,
"currency": "COP"
},
"fx_rates": null
},
"timestamp": "2023-06-15T10:35:00.000Z"
}
}
credit_adjustment:
{
"event": {
"type": "card_transaction",
"data": {
"type": "credit_adjustment",
"id": "ctx_5tgliBmzjZ6mpQSDbQjfKj",
"inserted_at": "2023-06-15T10:30:00.000Z",
"state": "approved",
"card": {
"id": "car_5tgliBmzjZ6mpQPRbQjfKj",
"last_four": "1234"
},
"cardholder_id": "cah_7MkWaFqvfusB8fzHhb1Eql",
"declination_reason": null,
"original_transaction_id": "ctx_5tgliBmzjZ9kpQPRbQjfKj",
"merchant": {
"id": "merchant_789012345",
"name": "Nombre del Comercio",
"mcc": "0000",
"amount": {
"amount": 160000,
"currency": "COP"
}
},
"amount": {
"amount": 160000,
"currency": "COP"
},
"settlement_amount": {
"amount": 160000,
"currency": "COP"
},
"withdrawal_fee": null,
"fx_rates": null,
"previous_values": {
"amount": {
"amount": 1000000,
"currency": "COP"
},
"merchant_amount": {
"amount": 1000000,
"currency": "COP"
}
}
},
"timestamp": "2023-06-15T10:35:00.000Z"
}
}
debit_adjustment:
{
"event": {
"data": {
"amount": {
"amount": 808000,
"currency": "COP"
},
"card": {
"id": "car_02v8ucNWMnt0qvOIG1Cx9Y",
"last_four": "4952"
},
"cardholder_id": "carh_02v8ucNVmEQWOhFmA8KJX4",
"declination_reason": null,
"fx_rates": null,
"id": "ctx_02vSpSMwSwIETjc7di98zU",
"inserted_at": "2024-01-16T20:06:18.397776Z",
"merchant": {
"amount": {
"amount": 200,
"currency": "USD"
},
"id": "111111111111111",
"mcc": "5045",
"name": "Computer Software"
},
"original_transaction_id": null,
"previous_values": {
"amount": {
"amount": 404000,
"currency": "COP"
},
"merchant_amount": {
"amount": 100,
"currency": "USD"
}
},
"settlement_amount": {
"amount": 100,
"currency": "USD"
},
"state": "approved",
"type": "debit_adjustment",
"withdrawal_fee": null
},
"type": "card_transaction"
},
"timestamp": "2024-01-16T20:07:31.979159Z"
}
force_debit:
{
"event": {
"data": {
"amount": {
"amount": 404000,
"currency": "COP"
},
"card": {
"id": "car_02v8ucNWMnt0qvOIG1Cx9Y",
"last_four": "4952"
},
"cardholder_id": "carh_02v8ucNVmEQWOhFmA8KJX4",
"declination_reason": null,
"fx_rates": null,
"id": "ctx_02vSmf8pSW4HqcViMjaC6a",
"inserted_at": "2024-01-16T18:12:27.393051Z",
"merchant": {
"amount": {
"amount": 100,
"currency": "USD"
},
"id": "111111111111111",
"mcc": "5045",
"name": "Computer Software "
},
"original_transaction_id": null,
"previous_values": null,
"settlement_amount": {
"amount": 100,
"currency": "USD"
},
"state": "approved",
"type": "force_debit",
"withdrawal_fee": null
},
"type": "card_transaction"
},
"timestamp": "2024-01-16T18:12:40.364194Z"
}
authorization_reversed:
{
"event": {
"data": {
"amount": {
"amount": 400224,
"currency": "COP"
},
"card": {
"id": "car_02v8ucNWMnt0qvOIG1Cx9Y",
"last_four": "4952"
},
"cardholder_id": "carh_02v8ucNVmEQWOhFmA8KJX4",
"declination_reason": null,
"fx_rates": {
"USD": "1",
"COP": "4002,24"
},
"id": "ctx_02vSq0LFdgOjYzv7vtfbr9",
"inserted_at": "2024-01-16T20:28:38.067403Z",
"merchant": {
"amount": {
"amount": 100,
"currency": "USD"
},
"id": "111111111111111",
"mcc": "5045",
"name": "Computer Software"
},
"original_transaction_id": null,
"previous_values": null,
"settlement_amount": {
"amount": 100,
"currency": "USD"
},
"state": "reversed",
"type": "authorization_reversed",
"withdrawal_fee": null
},
"type": "card_transaction"
},
"timestamp": "2024-01-16T20:29:35.474393Z"
}
refund:
{
"event": {
"data": {
"amount": {
"amount": 3500000,
"currency": "COP"
},
"card": {
"id": "car_02v8ucNWMnt0qvOIG1Cx9Y",
"last_four": "4952"
},
"cardholder_id": "carh_02v8ucNVmEQWOhFmA8KJX4",
"declination_reason": null,
"fx_rates": null,
"id": "ctx_02vSq0LFdgOjYzv7vtfbr9",
"inserted_at": "2024-01-16T20:28:38.067403Z",
"merchant": {
"amount": {
"amount": 3500000,
"currency": "COP"
},
"id": "111111111111111",
"mcc": "5045",
"name": "Computer Software"
},
"original_transaction_id": null,
"previous_values": null,
"settlement_amount": {
"amount": 2715000,
"currency": "COP"
},
"state": "approved",
"type": "refund",
"withdrawal_fee": null
},
"type": "card_transaction"
},
"timestamp": "2024-01-16T20:29:35.474393Z"
}