Transacciones de tarjeta

Eventos de webhook para transacciones de tarjeta, incluyendo autorizaciones, retiros y reembolsos.

Cuando se realiza una operación que involucra una transacción de tarjeta, se genera una petición de webhook según el tipo de transacción.

Tipos de evento

Evento	Descripción
`authorization_approved`	Se dispara cuando una transacción de tarjeta ha sido autorizada. Se reflejará un cargo sobre el saldo de la cuenta.
`authorization_declined`	Se dispara cuando una transacción de tarjeta no ha sido autorizada. Incluye un `declination_reason`. No hay cambio sobre el saldo de la cuenta.
`withdrawal`	Se dispara cuando un retiro ha sido autorizado (por ejemplo, ATM). Incluye un detalle `withdrawal_fee`.
`credit_adjustment`	Se dispara cuando una autorización se actualiza por un reembolso parcial. Se reflejará un reembolso en el saldo de la cuenta.
`debit_adjustment`	Se dispara cuando una autorización se actualiza con un nuevo monto. Se hace un nuevo cargo para actualizar la autorización anterior.
`force_debit`	Se dispara cuando una transacción se hace sin una autorización previa. Sin `original_transaction_id` ni `previous_values`.
`authorization_reversed`	Se dispara cuando una transacción se revierte y el valor del cargo inicial se devuelve completamente a la cuenta.
`refund`	Se dispara cuando se hace un reembolso a la cuenta. El valor puede o no estar relacionado con una autorización previa.
`reconciliation`	Se dispara después del settlement final cuando el monto autorizado se ajusta al monto efectivamente liquidado por la red de la tarjeta.

Campos nullable

Dependiendo del tipo de notificación, los siguientes campos pueden ser null:

Campo	Cuándo es null
`withdrawal_fee`	Cuando no hubo comisión (es decir, la transacción no fue en un ATM).
`fx_rates`	Cuando el monto se cargó en COP.
`declination_reason`	Cuando la operación fue exitosa.
`original_transaction_id`	Cuando la operación no involucra una transacción previa.
`previous_values`	Cuando no hay valores previos para comparar.

Ejemplos de payload

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

Transacciones de tarjeta

En esta página