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 when a transaction is reconciled with the card network's settlement, whether or not its amounts change.

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).
`three_ds_fee.tenant_subaccount_amount`	When no 3DS fee was registered for the transaction.
`three_ds_fee.mono_tenant_amount`	When no 3DS fee was registered for the transaction.
`declination_reason`	When the operation was successful.
`original_transaction_id`	When the operation does not involve a previous transaction.
`previous_values`	In every event except `credit_adjustment`, `debit_adjustment` and `reconciliation`.

fx_rates is never null. It is an empty object for transactions of zero amount.

3D Secure (3DS) is the authentication step for online card purchases. Each online purchase carries a 3DS fee, whether or not the cardholder is asked to authenticate. Every card transaction webhook shows that fee and the channel the transaction was made through.

Field	Description
`three_ds_fee.tenant_subaccount_amount`	Fee you charge your subaccount, in the currency of the account.
`three_ds_fee.mono_tenant_amount`	Fee Mono charges you, in the settlement currency.
`transaction_channel`	`online`, `physical` or `atm`.
`merchant.country`	Country where the merchant is located.

Each fee part is named after who charges it and who pays it.

When the Fee Is Charged

three_ds_fee shows the fee evaluated for the purchase. Mono charges it only when the purchase settles, even partially, as part of the debited amount. It isn't returned afterwards: refunds and partial reversals return only the merchant amount.

The fee is never charged when the authorization is declined, or fully reversed before it settles. Those events still show the evaluated fee. A refund always carries a 3DS fee of 0.

Every webhook about the same purchase repeats the fee. Count it once per purchase id.

Zero and Null

A fee part is null when no fee was registered for it. A 0 means the fee was registered as zero. It doesn't prove that the purchase went through 3DS, that the fee is configured as 0, or that anything was charged.

previous_values doesn't include the 3DS fee. The fee belongs to the purchase and doesn't change on adjustments.

Channel

Value	Transactions
`online`	Purchases made on the internet.
`physical`	Purchases at a point of sale, including mail and phone orders.
`atm`	Every withdrawal.

New values may be added. Handle unknown values without failing.

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",
        "country": "USA",
        "amount": {
          "amount": 1600,
          "currency": "USD"
        }
      },
      "amount": {
        "amount": 1600,
        "currency": "USD"
      },
      "settlement_amount": {
        "amount": 1600,
        "currency": "USD"
      },
      "withdrawal_fee": null,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 2,
          "currency": "USD"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "transaction_channel": "online",
      "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",
        "country": "USA",
        "amount": {
          "amount": 160,
          "currency": "USD"
        }
      },
      "amount": {
        "amount": 160,
        "currency": "USD"
      },
      "settlement_amount": {
        "amount": 160,
        "currency": "USD"
      },
      "withdrawal_fee": null,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 2,
          "currency": "USD"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "transaction_channel": "online",
      "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"
      },
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 0,
          "currency": "COP"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "COP"
        }
      },
      "transaction_channel": "atm",
      "merchant": {
        "id": "merchant_789012345",
        "name": "Nombre del Comercio",
        "mcc": "string",
        "country": "COL",
        "amount": {
          "amount": 5000000,
          "currency": "COP"
        }
      },
      "amount": {
        "amount": 5000000,
        "currency": "COP"
      },
      "settlement_amount": {
        "amount": 5000000,
        "currency": "COP"
      },
      "fx_rates": {
        "USD": "1",
        "COP": "4002.24"
      }
    }
  },
  "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",
        "country": "COL",
        "amount": {
          "amount": 160000,
          "currency": "COP"
        }
      },
      "amount": {
        "amount": 160000,
        "currency": "COP"
      },
      "settlement_amount": {
        "amount": 160000,
        "currency": "COP"
      },
      "withdrawal_fee": null,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 0,
          "currency": "COP"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "COP"
        }
      },
      "transaction_channel": "physical",
      "fx_rates": {
        "USD": "1",
        "COP": "4002.24"
      },
      "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": {
        "USD": "1",
        "COP": "4002.24"
      },
      "id": "ctx_02vSpSMwSwIETjc7di98zU",
      "inserted_at": "2024-01-16T20:06:18.397776Z",
      "merchant": {
        "id": "111111111111111",
        "name": "Computer Software",
        "mcc": "5045",
        "country": "USA",
        "amount": {
          "amount": 200,
          "currency": "USD"
        }
      },
      "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,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 0,
          "currency": "COP"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "transaction_channel": "physical"
    },
    "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": {
        "USD": "1",
        "COP": "4002.24"
      },
      "id": "ctx_02vSmf8pSW4HqcViMjaC6a",
      "inserted_at": "2024-01-16T18:12:27.393051Z",
      "merchant": {
        "id": "111111111111111",
        "name": "Computer Software",
        "mcc": "5045",
        "country": "USA",
        "amount": {
          "amount": 100,
          "currency": "USD"
        }
      },
      "original_transaction_id": null,
      "previous_values": null,
      "settlement_amount": {
        "amount": 100,
        "currency": "USD"
      },
      "state": "approved",
      "type": "force_debit",
      "withdrawal_fee": null,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 8000,
          "currency": "COP"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "transaction_channel": "online"
    },
    "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": {
        "id": "111111111111111",
        "name": "Computer Software",
        "mcc": "5045",
        "country": "USA",
        "amount": {
          "amount": 100,
          "currency": "USD"
        }
      },
      "original_transaction_id": null,
      "previous_values": null,
      "settlement_amount": {
        "amount": 100,
        "currency": "USD"
      },
      "state": "reversed",
      "type": "authorization_reversed",
      "withdrawal_fee": null,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 8000,
          "currency": "COP"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "transaction_channel": "online"
    },
    "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": {
        "USD": "1",
        "COP": "4002.24"
      },
      "id": "ctx_02vSq0LFdgOjYzv7vtfbr9",
      "inserted_at": "2024-01-16T20:28:38.067403Z",
      "merchant": {
        "id": "111111111111111",
        "name": "Computer Software",
        "mcc": "5045",
        "country": "COL",
        "amount": {
          "amount": 3500000,
          "currency": "COP"
        }
      },
      "original_transaction_id": null,
      "previous_values": null,
      "settlement_amount": {
        "amount": 2715000,
        "currency": "COP"
      },
      "state": "approved",
      "type": "refund",
      "withdrawal_fee": null,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 0,
          "currency": "COP"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "COP"
        }
      },
      "transaction_channel": "online"
    },
    "type": "card_transaction"
  },
  "timestamp": "2024-01-16T20:29:35.474393Z"
}

reconciliation

{
  "event": {
    "type": "card_transaction",
    "data": {
      "type": "reconciliation",
      "id": "ctx_02vSpSMwSwIETjc7di98zU",
      "inserted_at": "2024-01-16T20:06:18.397776Z",
      "state": "reconciled",
      "card": {
        "id": "car_02v8ucNWMnt0qvOIG1Cx9Y",
        "last_four": "4952"
      },
      "account_id": "lacc_16ktUqSO7G0qTHDz8I3qrG",
      "cardholder_id": "carh_02v8ucNVmEQWOhFmA8KJX4",
      "declination_reason": null,
      "original_transaction_id": null,
      "merchant": {
        "id": "111111111111111",
        "name": "Computer Software",
        "mcc": "5045",
        "country": "USA",
        "amount": {
          "amount": 200,
          "currency": "USD"
        }
      },
      "amount": {
        "amount": 808000,
        "currency": "COP"
      },
      "settlement_amount": {
        "amount": 200,
        "currency": "USD"
      },
      "withdrawal_fee": null,
      "three_ds_fee": {
        "tenant_subaccount_amount": {
          "amount": 8000,
          "currency": "COP"
        },
        "mono_tenant_amount": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "transaction_channel": "online",
      "fx_rates": {
        "USD": "1",
        "COP": "4002.24"
      },
      "previous_values": {
        "amount": {
          "amount": 404000,
          "currency": "COP"
        },
        "merchant_amount": {
          "amount": 100,
          "currency": "USD"
        },
        "settlement_amount": {
          "amount": 100,
          "currency": "USD"
        }
      }
    }
  },
  "timestamp": "2024-01-16T20:07:31.979159Z"
}