Transactions - Z2Pay Developers

La transacción (txn_) es el objeto central de la Core API: agrupa lo que el comprador está pagando (los items) y cómo está pagando (los payments). Cada payment representa un intento/método de pago (tarjeta, boleto o Pix). El estado de la transacción nunca se define directamente — siempre es calculado a partir del estado agregado de sus payments.

Todas las rutas requieren el header x-api-key (su clave de sandbox). Consulte Autenticación. Los ejemplos a continuación usan la URL base de sandbox https://api.sandbox.z2pay.com.

Endpoints

Método	Ruta	Descripción
`GET`	`/transactions`	Lista paginada de transacciones, con filtros
`GET`	`/transactions/:id`	Obtiene una transacción con sus payments e ítems
`GET`	`/transactions/:id/items`	Lista únicamente los ítems de la transacción
`POST`	`/transactions`	Crea una nueva transacción
`POST`	`/transactions/:id/refund`	Revierte todos los payments pagados de la transacción

Estado de la transacción

El estado se deriva de los payments mediante un cálculo centralizado. En resumen (reglas evaluadas en orden):

Cómo se calcula el estado

Los payments con estado replaced o deleted se ignoran en el cálculo.
Si la transacción tiene valor cero → paid.
Si no hay payment activo → pending.
Si todos los payments no fallidos son refused → refused. Si todos son failed/expired → failed.
Entre los payments válidos (excluyendo refused/failed/expired): si todos son chargeback → chargeback; si todos son canceled → canceled; si todos son in_protest → in_protest.
Si el monto efectivamente pagado cubre el total de la transacción → paid (incluso con reversión parcial de excedente).
Si hay monto pagado (> 0) menor que el total y sin actividad de reversión → partially_paid.
Si las liquidaciones están todas en ciclo de reversión: todas refunded → refunded; alguna partially_refunded → partially_refunded; en caso contrario → waiting_refund.
Queda monto pagado/retenido junto con reversión activa → partially_refunded.
El monto revertido cubre el total → refunded.
Sin nada pagado y el monto en espera de pago cubre el total → waiting_payment.
Si ninguno de los anteriores aplica → pending.

Valores posibles de estado:

Estado	Significado
`pending`	Creada, sin pago confirmado ni en espera de pago definido
`waiting_payment`	En espera de pago (boleto/Pix emitido, o payment creado sin procesar)
`partially_paid`	Parte del monto fue pagada, pero no el total
`paid`	Monto total pagado
`refused`	Pago rechazado
`failed`	Fallo terminal en el gateway
`canceled`	Cancelada
`waiting_refund`	Reversión solicitada, en espera de procesamiento
`partially_refunded`	Parte del monto pagado fue revertida
`refunded`	Monto total revertido
`chargeback`	Sufrió un chargeback
`in_protest`	En protesta (disputa de chargeback en curso)

Como el estado agrega los payments, una transacción con más de un payment (ej.: dos tarjetas, o Pix + tarjeta) puede pasar por estados intermedios como partially_paid o partially_refunded.

Crear transacción

POST /transactions Crea una transacción. Siempre debe indicar el cliente y al menos un ítem. Los payments son opcionales:

Con payments y datos de procesamiento (creditCard/boleto/pix) → los payments se procesan inmediatamente en el gateway.
Con payments sin datos de procesamiento → los payments quedan en espera de procesamiento.
Sin payments → la transacción queda en waiting_payment.

Endpoint idempotente. Envíe el header Idempotency-Key (TTL de 7 días) para garantizar que los reenvíos de la misma solicitud no creen transacciones duplicadas. Consulte Convenciones.

Reglas de negocio importantes

customer y customerId son mutuamente excluyentes. Envíe uno de los dos (obligatorio): customerId para reutilizar un cliente ya registrado, o customer en línea para crear/identificar al cliente en el momento. Enviar ambos, o ninguno, resulta en 400.

La suma de los payments debe coincidir con la suma de los ítems. Cuando se envía payments, la suma de payment.amount debe ser exactamente igual al total de los ítems (Σ item.amount × item.quantity). De lo contrario, 400. Todos los valores son enteros en centavos.

Cuerpo de la solicitud

customerId

string

ID de un cliente existente (cust_). Mutuamente exclusivo con customer.

customer

object

Datos del cliente en línea. Mutuamente exclusivo con customerId.

Mostrar campos de customer

customer.name

string

requerido

Nombre del cliente (mínimo 2 caracteres).

customer.email

string

requerido

Correo electrónico válido.

customer.type

string

requerido

Tipo de cliente. Valores: individual o company.

customer.document

string

requerido

Documento (mínimo 6 caracteres).

customer.documentType

string

Tipo de documento. Valores: cpf, cnpj o passport.

customer.phone

string

requerido

Teléfono del cliente.

customer.address

object

Dirección del comprador. Campos: street, number, complement, neighborhood, city, state, postalCode, country (todos opcionales, pueden ser null). Los campos faltantes pueden ser completados por la configuración del gateway.

referenceCode

string

requerido

Su código de referencia para la transacción (1 a 255 caracteres). Úselo para correlacionar con su sistema.

items

array

requerido

Lista de ítems (mínimo 1).

Mostrar campos de cada ítem

items[].description

string

requerido

Descripción del ítem (1 a 255 caracteres).

items[].quantity

integer

requerido

Cantidad (entero, mínimo 1).

items[].amount

integer

requerido

Valor unitario en centavos (entero, mínimo 1).

items[].code

string

Código/SKU del ítem (1 a 255 caracteres).

items[].type

string

Tipo de ítem (hasta 50 caracteres).

items[].imageUrl

string

URL de la imagen del ítem (URL válida, hasta 500 caracteres).

payments

array

Métodos de pago. Si se omite, la transacción queda en waiting_payment.

Mostrar campos de cada payment

payments[].paymentMethod

string

requerido

Método. Valores: credit_card, boleto o pix.

payments[].amount

integer

requerido

Monto del payment en centavos (entero, mínimo 1).

payments[].installments

integer

predeterminado:"1"

Número de cuotas (entero, mínimo 1). El pago en cuotas (> 1) solo está permitido para credit_card.

payments[].additionalInfo

object

Metadatos libres (objeto clave-valor).

payments[].creditCard

object

Datos de procesamiento de tarjeta (solo con paymentMethod: credit_card). Requiere id o token de la tarjeta. Campos: id (crd_), token, statementDescriptor (soft descriptor, hasta 100 caracteres) y billingAddress.

payments[].boleto

object

Datos del boleto (solo con paymentMethod: boleto). Campos: expirationDate (fecha), instructions (1 a 255 caracteres).

payments[].pix

object

Datos del Pix (solo con paymentMethod: pix). Campo: expirationDate (fecha).

payments[].splitId

string

ID de una configuración de split guardada. Mutuamente exclusivo con split.

payments[].split

array

Configuración de split en línea. Mutuamente exclusivo con splitId. Consulte Split.

currency

string

Código de moneda ISO 4217 (3 letras, ej.: BRL). Por defecto: configuración de la company o BRL.

redirectUrl

string

URL de redirección tras el pago (URL válida).

postbackUrl

string

URL para recibir notificaciones de esta transacción (URL válida). Consulte Webhooks.

string

IP del comprador.

additionalInfo

object

Metadatos libres de la transacción (objeto clave-valor). Permite búsqueda mediante el filtro metadataSearch.

maxInstallments

integer

Número máximo de cuotas permitido (entero, mínimo 1).

routerConfigId

string

Override de la configuración de enrutamiento (opcional).

Ejemplo: crear transacción con Pix

curl -X POST https://api.sandbox.z2pay.com/transactions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: pedido-2026-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceCode": "pedido-2026-0001",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "type": "individual",
      "document": "12345678909",
      "documentType": "cpf",
      "phone": "+5511999998888"
    },
    "items": [
      { "description": "Plano Pro (mensal)", "quantity": 1, "amount": 9990 }
    ],
    "payments": [
      { "paymentMethod": "pix", "amount": 9990 }
    ]
  }'

El ítem cuesta 9990 centavos (R$ 99,90) y el payment suma 9990 — las sumas coinciden, por lo que la solicitud es válida.

{
  "id": "txn_3xK9aQ2bR7tV1mN0",
  "referenceCode": "pedido-2026-0001",
  "status": "waiting_payment",
  "amount": 9990,
  "currency": "BRL",
  "customerId": "cust_8Hn2Lp4Wq6Yz0Bc",
  "payments": [
    {
      "id": "pay_5Rg7Df3Ka9Xs2Vn1",
      "paymentMethod": "pix",
      "status": "waiting_payment",
      "amount": 9990
    }
  ],
  "items": [
    {
      "id": "item_1Ab2Cd3Ef4Gh5Ij",
      "description": "Plano Pro (mensal)",
      "quantity": 1,
      "amount": 9990
    }
  ],
  "createdAt": "2026-06-24T12:00:00.000Z"
}

Respuesta 201 Created. El ejemplo de JSON es ilustrativo — verifique los campos reales en la respuesta de su entorno.

Ejemplo: crear y cobrar con tarjeta tokenizada

curl -X POST https://api.sandbox.z2pay.com/transactions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: pedido-2026-0002" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceCode": "pedido-2026-0002",
    "customerId": "cust_8Hn2Lp4Wq6Yz0Bc",
    "items": [
      { "description": "Camiseta", "quantity": 2, "amount": 5000 }
    ],
    "payments": [
      {
        "paymentMethod": "credit_card",
        "amount": 10000,
        "installments": 1,
        "creditCard": {
          "token": "tok_exemplo_sandbox",
          "statementDescriptor": "MINHALOJA"
        }
      }
    ]
  }'

Dos ítems de 5000 × 2 = 10000 centavos; el payment suma 10000. Las sumas coinciden. La tarjeta se envía como token (generado por el Tokenizer) — nunca envíe datos en bruto de la tarjeta a la Core API.

Listar transacciones

GET /transactions Devuelve una lista paginada. Todos los filtros son opcionales y pueden combinarse.

Parámetros de query

page

integer

Página (paginación). Consulte Convenciones.

limit

integer

Ítems por página.

status

string

Filtra por estado de la transacción.

currency

string

Filtra por moneda.

paymentMethod

string

Filtra por método de pago.

string

ID de la transacción (búsqueda parcial, ILIKE).

referenceCode

string

Filtra por su código de referencia.

customerName

string

Filtra por nombre del cliente.

customerEmail

string

Filtra por correo electrónico del cliente.

customerDocument

string

Filtra por documento del cliente.

customerSearch

string

Búsqueda combinada en nombre/correo/documento del cliente.

recipientIds

string

Lista de IDs de destinatarios (separados por coma) que deben aparecer en algún split de la transacción.

metadataSearch

string

Búsqueda textual en cualquier valor almacenado en additionalInfo.

string

Búsqueda genérica.

startDate

string

Fecha inicial. ISO 8601 con timezone (ej.: 2026-06-01T00:00:00.000Z).

endDate

string

Fecha final. ISO 8601 con timezone.

dateField

string

Campo de fecha utilizado por startDate/endDate. Valores: createdAt, paidAt, refundedAt, canceledAt, chargedbackAt, protestedAt.

sortBy

string

Campo de ordenamiento. Valores: createdAt, paidAt, amount, status, customerName.

sortDir

string

Dirección del ordenamiento. Valores: asc o desc.

Ejemplo

curl "https://api.sandbox.z2pay.com/transactions?status=paid&sortBy=createdAt&sortDir=desc&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "txn_3xK9aQ2bR7tV1mN0",
      "referenceCode": "pedido-2026-0001",
      "status": "paid",
      "amount": 9990,
      "currency": "BRL",
      "customerId": "cust_8Hn2Lp4Wq6Yz0Bc",
      "createdAt": "2026-06-24T12:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

El formato exacto del envelope de paginación está en Convenciones. El JSON anterior es ilustrativo.

Obtener transacción por ID

GET /transactions/:id Devuelve los datos completos de la transacción, incluyendo sus payments e items.

string

requerido

ID de la transacción (txn_).

curl https://api.sandbox.z2pay.com/transactions/txn_3xK9aQ2bR7tV1mN0 \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "txn_3xK9aQ2bR7tV1mN0",
  "referenceCode": "pedido-2026-0001",
  "status": "paid",
  "amount": 9990,
  "currency": "BRL",
  "customerId": "cust_8Hn2Lp4Wq6Yz0Bc",
  "payments": [
    {
      "id": "pay_5Rg7Df3Ka9Xs2Vn1",
      "paymentMethod": "pix",
      "status": "paid",
      "amount": 9990
    }
  ],
  "items": [
    {
      "id": "item_1Ab2Cd3Ef4Gh5Ij",
      "description": "Plano Pro (mensal)",
      "quantity": 1,
      "amount": 9990
    }
  ]
}

status

string

Estado calculado de la transacción. Consulte la tabla en Estado de la transacción.

payments

array

Payments de la transacción. Para detalles de payment, consulte Payments.

items

array

Ítems de la transacción.

Si el ID no existe, la respuesta es 404. Consulte Errores.

Listar ítems de la transacción

GET /transactions/:id/items Devuelve únicamente los ítems (productos/servicios) de la transacción, dentro de una clave data.

string

requerido

ID de la transacción (txn_).

curl https://api.sandbox.z2pay.com/transactions/txn_3xK9aQ2bR7tV1mN0/items \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "item_1Ab2Cd3Ef4Gh5Ij",
      "description": "Plano Pro (mensal)",
      "quantity": 1,
      "amount": 9990
    }
  ]
}

Si la transacción no existe, la respuesta es 404.

Revertir transacción

POST /transactions/:id/refund Crea solicitudes de refund para todos los payments pagados de la transacción de una sola vez. El comportamiento de aprobación depende de la configuración refund.auto_approve de la company (por defecto: activado):

Con auto-approve: el refund se crea, aprueba y procesa en el gateway inmediatamente.
Sin auto-approve: los refunds quedan pendientes de aprobación manual.

Endpoint idempotente — envíe Idempotency-Key. Para revertir un payment específico (reversión parcial), use el endpoint de Refunds / Payments.

string

requerido

ID de la transacción (txn_).

reason

string

requerido

Motivo de la reversión (1 a 4000 caracteres).

curl -X POST https://api.sandbox.z2pay.com/transactions/txn_3xK9aQ2bR7tV1mN0/refund \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: refund-pedido-0001" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cliente solicitou cancelamento" }'

{
  "data": [
    {
      "id": "rfd_9Zx8Wv7Ut6Sr5Qp",
      "paymentId": "pay_5Rg7Df3Ka9Xs2Vn1",
      "status": "refunded",
      "amount": 9990,
      "reason": "Cliente solicitou cancelamento"
    }
  ]
}

Estados posibles

200 — refunds creados y procesados.
404 — transacción no encontrada.
409 — ningún payment revertible encontrado (ej.: ningún payment está pagado).

Consulte Errores para el formato de los errores.

Ver también

Payments

Detalles de cada método de pago dentro de la transacción.

Refunds

Reversión de un payment específico y reversiones parciales.

Tokenizer

Genere el token de la tarjeta antes de crear la transacción.

Split

Configure transferencias por payment con split o splitId.

Customers

Registre clientes para reutilizarlos mediante customerId.

Webhooks

Reciba notificaciones de cambio de estado de la transacción.

​Endpoints

​Estado de la transacción

​Crear transacción

​Reglas de negocio importantes

​Cuerpo de la solicitud

​Ejemplo: crear transacción con Pix

​Ejemplo: crear y cobrar con tarjeta tokenizada

​Listar transacciones

​Parámetros de query

​Ejemplo

​Obtener transacción por ID

​Listar ítems de la transacción

​Revertir transacción

​Estados posibles

​Ver también

Payments

Refunds

Tokenizer

Split

Customers

Webhooks

Endpoints

Estado de la transacción

Crear transacción

Reglas de negocio importantes

Cuerpo de la solicitud

Ejemplo: crear transacción con Pix

Ejemplo: crear y cobrar con tarjeta tokenizada

Listar transacciones

Parámetros de query

Ejemplo

Obtener transacción por ID

Listar ítems de la transacción

Revertir transacción

Estados posibles

Ver también