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 a declination_reason to 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 a withdrawal_fee detail.
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. A partial refund is 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 no original_transaction_id nor previous_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"
}