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.

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