Tipos de eventos

Los eventos son la forma en que Bidzi notificará qué está sucediendo con los pagos y liquidaciones de tu comercio.

Formato del evento

Cada notificación llega envuelta en un sobre (envelope) con dos campos:

Campo	Tipo	Descripción
`event_type`	`string`	Tipo de evento a nivel de mensaje: `TRANSACTION` o `SETTLEMENT`.
`payload`	`object`	Cuerpo del evento. Su forma depende del `event_type` del sobre.

{
  "event_type": "TRANSACTION",
  "payload": { ... }
}

Eventos de transacción (`event_type: "TRANSACTION"`)

Se disparan cuando un pago cambia de estado:

Evento	Descripción
`payment.authorize`	Autorización únicamente
`payment.cancel`	Cancelación de un pago autorizado
`payment.capture`	Efectivo de un pago autorizado
`payment.purchase`	Pago exitoso
`payment.refund`	Reembolso aplicado

Todos comparten el mismo payload; se distinguen por el campo payload.event_type (distinto del event_type del sobre, que siempre es "TRANSACTION" en estos casos).

Ejemplo — `payment.purchase`

{
  "event_type": "TRANSACTION",
  "payload": {
    "transaction_id": 123456,
    "operation_number": 789,
    "external_id": "ext-abc123",
    "amount": 150.00,
    "tip_amount": 10.00,
    "subtotal": 140.00,
    "currency": "MXN",
    "description": "Venta mostrador",
    "reference": "REF-001",
    "charge_id": "chg_abc",
    "authorization_code": "AUTH123",
    "event_type": "PURCHASE",
    "status": "CAPTURED",
    "transaction_date": "2026-09-11T12:00:00Z",
    "affiliation": "AFF001",
    "installments": 1,
    "product": "POS",
    "merchant": {
      "id": 123,
      "name": "COMERCIO DE PRUEBA",
      "rfc": "XAXX010101000"
    },
    "terminal": {
      "serial_number": "TERM001",
      "alias": "Caja 1",
      "entry_mode": "CHIP",
      "aid": "A0000000041010",
      "arqc": "1234567890ABCDEF"
    },
    "card": {
      "card_holder": "JUAN PEREZ",
      "bin": "411111",
      "last_four": "1111",
      "card_type": "CREDIT",
      "brand": "VISA",
      "bank": "BANAMEX"
    },
    "commissions": {
      "fixed": 2.00,
      "percentage": 2.50,
      "amount": 4.50,
      "tax": 0.72
    }
  }
}

Ejemplo — `payment.authorize`

{
  "transaction_id": 900004,
  "operation_number": 300004,
  "amount": 500.00,
  "tip_amount": 0,
  "subtotal": 500.00,
  "currency": "MXN",
  "description": "AUTORIZACIÓN APROBADA",
  "reference": "TEST-AUTHORIZE-001",
  "authorization_code": "456789",
  "event_type": "AUTHORIZE",
  "status": "AUTHORIZED",
  "transaction_date": 1786131000,
  "affiliation": "9000001",
  "installments": 0,
  "product": "POS",
  "merchant": {
    "id": 5001,
    "name": "COMERCIO DE PRUEBA",
    "rfc": "XAXX010101000"
  },
  "terminal": {
    "serial_number": "TESTTERM0003",
    "entry_mode": "CHIP",
    "aid": "a000000000000004",
    "arqc": "0000000000000004"
  },
  "card": {
    "bin": "55555500",
    "last_four": "3333",
    "card_type": "CREDIT",
    "brand": "MASTERCARD",
    "bank": "BANCO DE PRUEBA"
  },
  "commissions": {
    "fixed": 0,
    "percentage": 1.6,
    "amount": 8.00,
    "tax": 1.28
  }
}

Ejemplo — `payment.cancel`

{
  "transaction_id": 900002,
  "operation_number": 300002,
  "amount": 250.00,
  "tip_amount": 0,
  "subtotal": 250.00,
  "currency": "MXN",
  "description": "CANCELACIÓN APROBADA",
  "reference": "TEST-CANCEL-001",
  "authorization_code": "234567",
  "event_type": "CANCEL",
  "status": "CANCELLED",
  "transaction_date": 1786129000,
  "affiliation": "9000001",
  "installments": 0,
  "product": "POS",
  "merchant": {
    "id": 5001,
    "name": "COMERCIO DE PRUEBA",
    "rfc": "XAXX010101000"
  },
  "terminal": {
    "serial_number": "TESTTERM0002",
    "entry_mode": "CHIP",
    "aid": "a000000000000002",
    "arqc": "0000000000000002"
  },
  "card": {
    "bin": "55555500",
    "last_four": "4444",
    "card_type": "CREDIT",
    "brand": "MASTERCARD",
    "bank": "BANCO DE PRUEBA"
  },
  "commissions": {
    "fixed": 0,
    "percentage": 1.6,
    "amount": 4.00,
    "tax": 0.64
  }
}

Ejemplo — `payment.capture`

{
  "transaction_id": 900005,
  "operation_number": 300005,
  "amount": 500.00,
  "tip_amount": 0,
  "subtotal": 500.00,
  "currency": "MXN",
  "description": "CAPTURA APROBADA",
  "reference": "TEST-CAPTURE-001",
  "authorization_code": "456789",
  "event_type": "CAPTURE",
  "status": "APPROVED",
  "transaction_date": 1786132000,
  "affiliation": "9000001",
  "installments": 0,
  "product": "POS",
  "merchant": {
    "id": 5001,
    "name": "COMERCIO DE PRUEBA",
    "rfc": "XAXX010101000"
  },
  "terminal": {
    "serial_number": "TESTTERM0003",
    "entry_mode": "CHIP",
    "aid": "a000000000000004",
    "arqc": "0000000000000005"
  },
  "card": {
    "bin": "55555500",
    "last_four": "3333",
    "card_type": "CREDIT",
    "brand": "MASTERCARD",
    "bank": "BANCO DE PRUEBA"
  },
  "commissions": {
    "fixed": 0,
    "percentage": 1.6,
    "amount": 8.00,
    "tax": 1.28
  }
}

Ejemplo — `payment.refund`

{
  "transaction_id": 900003,
  "operation_number": 300003,
  "amount": 125.50,
  "tip_amount": 0,
  "subtotal": 125.50,
  "currency": "MXN",
  "description": "DEVOLUCIÓN APROBADA",
  "reference": "TEST-REFUND-001",
  "authorization_code": "345678",
  "event_type": "REFUND",
  "status": "APPROVED",
  "transaction_date": 1786130000,
  "affiliation": "9000001",
  "installments": 0,
  "product": "POS",
  "merchant": {
    "id": 5001,
    "name": "COMERCIO DE PRUEBA",
    "rfc": "XAXX010101000"
  },
  "terminal": {
    "serial_number": "TESTTERM0001",
    "entry_mode": "CONTACTLESS",
    "aid": "a000000000000003",
    "arqc": "0000000000000003"
  },
  "card": {
    "bin": "41111100",
    "last_four": "2222",
    "card_type": "DEBIT",
    "brand": "VISA",
    "bank": "BANCO DE PRUEBA"
  },
  "commissions": {
    "fixed": 0,
    "percentage": 1.6,
    "amount": 2.008,
    "tax": 0.32128
  }
}

Eventos de liquidación (`event_type: "SETTLEMENT"`)

Notifica que un depósito a tu cuenta fue liquidado. A diferencia de los eventos de transacción, el payload no incluye un campo event_type interno — el tipo ya queda indicado en el sobre.

Campo	Tipo	Descripción
`deposit_id`	`integer`	Identificador del depósito
`merchant_id`	`integer`	Identificador de tu comercio
`deposit_date`	`string`	Fecha del depósito (`yyyy-mm-dd`)
`payments`	`array`	Detalle de las piernas de pago del depósito
`payments[].tracking_id`	`string`	Clave de rastreo de la transferencia
`payments[].concept`	`string`	Concepto de la transferencia
`payments[].account`	`string`	CLABE destino
`payments[].amount`	`number`	Monto de esta pierna
`payments[].currency`	`string`	Moneda
`payments[].percentage`	`number`	Porcentaje del depósito que representa esta pierna
`payments[].status`	`string`	Estado de la transferencia
`deposit_status`	`string`	Estado agregado del depósito (p. ej. `COMPLETED`)
`transaction_ids`	`array<integer>`	IDs de las transacciones incluidas en este depósito

Ejemplo — liquidación de depósito

{
  "event_type": "SETTLEMENT",
  "payload": {
    "deposit_id": 456,
    "merchant_id": 123,
    "deposit_date": "2026-09-11",
    "payments": [
      {
        "tracking_id": "TRK-0001",
        "concept": "Liquidación de ventas",
        "account": "012180001234567895",
        "amount": 12500.00,
        "currency": "MXN",
        "percentage": 100.00,
        "status": "LIQUIDATED"
      }
    ],
    "deposit_status": "COMPLETED",
    "transaction_ids": [1001, 1002, 1003]
  }
}

Updated 13 days ago

Did this page help you?