Card Transactions

Webhook events for card transactions including authorizations, withdrawals, and refunds.

When an operation involving a card transaction is done, a webhook request is generated based on the transaction type.

Event Types

Event	Description
`authorization_approved`	Triggered when a card transaction has been authorized. A charge will be reflected on the account's balance.
`authorization_declined`	Triggered when a card transaction has not been authorized. Includes a `declination_reason`. No change on the account's balance.
`withdrawal`	Triggered when a withdrawal has been authorized (e.g., ATM). Includes a `withdrawal_fee` detail.
`credit_adjustment`	Triggered when an authorization is updated by a partial refund. A refund will be reflected in the account balance.
`debit_adjustment`	Triggered when an authorization is updated with a new amount. A new charge is done to update the previous authorization.
`force_debit`	Triggered when a transaction is made without a previous authorization. No `original_transaction_id` nor `previous_values`.
`authorization_reversed`	Triggered when a transaction is reversed and the value of the initial charge is returned fully to the account.
`refund`	Triggered when a refund is made to the account. The value can be related or not to a previous authorization.
`reconciliation`	Triggered after final settlement when the authorized amount is adjusted to the amount actually settled by the card network.

Nullable Fields

Depending on the type of the notification, the following fields could be null:

Field	When it's null
`withdrawal_fee`	When there was no fee (i.e., the card transaction was not in an ATM).
`fx_rates`	When the amount was charged in COP.
`declination_reason`	When the operation was successful.
`original_transaction_id`	When the operation does not involve a previous transaction.
`previous_values`	When there are no previous values to compare.

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

Card Transactions

On this page