Payments - Z2Pay Developers

Un payment es un pago individual dentro de una transacción. Una misma transacción puede tener varios payments (por ejemplo, parte con tarjeta y parte con PIX), por eso todos los endpoints de esta página viven bajo /transactions/:transactionId/payments.

Todas las solicitudes usan el header x-api-key: TU_CLAVE_DE_SANDBOX. Consulta Autenticación para más detalles. La URL base del sandbox es https://api.sandbox.z2pay.com.

Endpoints

Método	Ruta	Descripción
`GET`	`/transactions/{transactionId}/payments`	Lista los payments de la transacción
`GET`	`/transactions/{transactionId}/payments/{paymentId}`	Obtiene un payment por ID
`POST`	`/transactions/{transactionId}/payments/process`	Procesa los payments pendientes vía gateway
`POST`	`/transactions/{transactionId}/payments/{paymentId}/refund`	Reembolsa (refund) un payment

El objeto Payment

Los campos a continuación conforman el objeto Payment retornado por los endpoints de listar y consultar. Los valores monetarios son enteros en centavos (ej.: 15000 = R$ 150,00). Las fechas son strings ISO 8601 con zona horaria y vienen como null cuando aún no han ocurrido.

string

Identificador del payment (prefijo pay_).

transactionId

string

ID de la transacción a la que pertenece el payment (prefijo txn_).

replacedByPaymentId

string | null

Cuando el payment fue reemplazado (status replaced), apunta al nuevo payment que lo sustituyó. null en caso contrario.

companyId

string

ID de la company dueña del payment.

amount

integer

Valor del payment, en centavos.

currency

string

Moneda del payment. Por defecto: BRL.

installments

integer

Número de cuotas. Por defecto: 1.

paymentMethod

string

Método de pago. Uno de: credit_card, boleto, pix.

provider

string | null

Identificador interno del proveedor que procesó el payment. null mientras no haya sido procesado.

gatewayConfigId

string | null

ID de la configuración de gateway elegida por el routing. null mientras no haya sido procesado.

cardId

string | null

ID de la tarjeta utilizada (prefijo card_), cuando corresponda. null para boleto/PIX.

status

string

Estado actual del payment. Consulta la lista de valores en Estado del payment.

additionalInfo

object | null

Metadatos libres asociados al payment. null cuando no están presentes.

statementDescriptor

string | null

Soft descriptor enviado al titular en el estado de cuenta (ya normalizado, máximo 13 caracteres). null cuando no está definido.

boletoUrl

string | null

URL del boleto (PDF/visualización). Se completa tras el procesamiento de un payment de boleto.

boletoDigitableLine

string | null

Línea digitável del boleto.

boletoBarcode

string | null

Código de barras del boleto.

pixUrl

string | null

URL de la imagen del QR Code PIX (para mostrar/escanear).

pixCopyPaste

string | null

Payload BR Code del PIX (copia y pega, EMV iniciando en 00020126...), para pegar en la app del banco.

splitConfigId

string | null

ID de la configuración de split aplicada al payment, si la hubiere.

originalAmount

integer | null

Valor original antes de ajustes (en centavos), cuando corresponda.

acquirerReturnCode

string | null

Código de retorno del adquirente.

acquirerReturnMessage

string | null

Mensaje de retorno del adquirente.

retryable

boolean | null

Indica si un fallo puede ser reintentado. null cuando no aplica.

declineCode

string | null

Código de rechazo, cuando el payment fue rechazado.

errorMessage

string | null

Mensaje de error del procesamiento, cuando lo haya.

createdAt

string

Fecha de creación (ISO 8601).

updatedAt

string

Fecha de la última actualización (ISO 8601).

paidAt

string | null

Fecha en que el payment fue pagado. null mientras no haya sido pagado.

expiresAt

string | null

Fecha de expiración del instrumento (ej.: TTL del QR Code PIX, vencimiento del boleto). null cuando no aplica.

canceledAt

string | null

Fecha de cancelación. null cuando no fue cancelado.

refundedAt

string | null

Fecha del reembolso. null cuando no fue reembolsado.

chargedbackAt

string | null

Fecha del chargeback. null cuando no ocurrió.

protestedAt

string | null

Fecha de entrada en protesto. null cuando no aplica.

deletedAt

string | null

Fecha de eliminación lógica (soft delete). null para payments activos.

version

integer | null

Versión de concurrencia optimista del registro.

Estado del payment

El campo status puede tomar uno de los siguientes valores:

Status	Significado
`pending`	Creado, aún no procesado
`waiting_payment`	Aguardando pago (boleto/PIX emitido)
`authorized`	Autorizado (tarjeta), aún no capturado/liquidado
`paid`	Pagado
`partially_paid`	Pagado parcialmente
`refused`	Rechazado por el adquirente
`failed`	Error en el procesamiento
`canceled`	Cancelado
`expired`	Expiró antes de completarse (ej.: QR Code PIX o boleto vencido)
`replaced`	Reemplazado por otro payment
`waiting_refund`	Reembolso solicitado, en espera de procesamiento
`refunded`	Reembolsado íntegramente
`partially_refunded`	Reembolsado parcialmente
`chargeback`	Chargeback registrado
`in_protest`	En protesto
`deleted`	Eliminado lógicamente

Listar payments de la transacción

GET /transactions/{transactionId}/payments

Retorna todos los payments asociados a una transacción específica.

transactionId

string

requerido

ID de la transacción (prefijo txn_).

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

La respuesta (200) envuelve la lista en el campo data:

{
  "data": [
    {
      "id": "pay_8h2k4m6n9p1q3r",
      "transactionId": "txn_3kf9a2b7c1d4e5",
      "replacedByPaymentId": null,
      "companyId": "comp_1a2b3c4d5e6f",
      "amount": 15000,
      "currency": "BRL",
      "installments": 1,
      "paymentMethod": "pix",
      "provider": "provider_x",
      "gatewayConfigId": "gwc_9z8y7x6w5v",
      "cardId": null,
      "status": "waiting_payment",
      "additionalInfo": null,
      "statementDescriptor": "LOJA EXEMPLO",
      "boletoUrl": null,
      "boletoDigitableLine": null,
      "boletoBarcode": null,
      "pixUrl": "https://api.sandbox.z2pay.com/qr/pay_8h2k4m6n9p1q3r.png",
      "pixCopyPaste": "00020126580014br.gov.bcb.pix...5204000053039865802BR6304ABCD",
      "splitConfigId": null,
      "originalAmount": null,
      "acquirerReturnCode": null,
      "acquirerReturnMessage": null,
      "retryable": null,
      "declineCode": null,
      "errorMessage": null,
      "createdAt": "2026-06-24T13:00:00.000Z",
      "updatedAt": "2026-06-24T13:00:01.000Z",
      "paidAt": null,
      "expiresAt": "2026-06-24T13:30:00.000Z",
      "canceledAt": null,
      "refundedAt": null,
      "chargedbackAt": null,
      "protestedAt": null,
      "deletedAt": null,
      "version": 1
    }
  ]
}

data

Payment[]

Lista de payments de la transacción. Consulta El objeto Payment.

Códigos de estado

Código	Cuándo
`200`	Lista retornada
`404`	Transacción no encontrada

Obtener payment por ID

GET /transactions/{transactionId}/payments/{paymentId}

Retorna los datos de un payment específico.

transactionId

string

requerido

ID de la transacción (prefijo txn_).

paymentId

string

requerido

ID del payment (prefijo pay_).

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

La respuesta (200) es el objeto Payment directamente (sin envelope):

{
  "id": "pay_8h2k4m6n9p1q3r",
  "transactionId": "txn_3kf9a2b7c1d4e5",
  "replacedByPaymentId": null,
  "companyId": "comp_1a2b3c4d5e6f",
  "amount": 15000,
  "currency": "BRL",
  "installments": 1,
  "paymentMethod": "boleto",
  "provider": "provider_x",
  "gatewayConfigId": "gwc_9z8y7x6w5v",
  "cardId": null,
  "status": "waiting_payment",
  "additionalInfo": null,
  "statementDescriptor": "LOJA EXEMPLO",
  "boletoUrl": "https://api.sandbox.z2pay.com/boleto/pay_8h2k4m6n9p1q3r.pdf",
  "boletoDigitableLine": "34191.79001 01043.510047 91020.150008 8 99980000015000",
  "boletoBarcode": "34198999800000150001790010104351004791020150",
  "pixUrl": null,
  "pixCopyPaste": null,
  "splitConfigId": null,
  "originalAmount": null,
  "acquirerReturnCode": null,
  "acquirerReturnMessage": null,
  "retryable": null,
  "declineCode": null,
  "errorMessage": null,
  "createdAt": "2026-06-24T13:00:00.000Z",
  "updatedAt": "2026-06-24T13:00:01.000Z",
  "paidAt": null,
  "expiresAt": "2026-06-27T02:59:59.000Z",
  "canceledAt": null,
  "refundedAt": null,
  "chargedbackAt": null,
  "protestedAt": null,
  "deletedAt": null,
  "version": 1
}

Para boleto, utiliza boletoUrl, boletoDigitableLine y boletoBarcode. Para PIX, utiliza pixUrl (QR Code) y pixCopyPaste (copia y pega). Estos campos solo se completan después de que el payment es procesado por el gateway.

Códigos de estado

Código	Cuándo
`200`	Payment retornado
`404`	Payment no encontrado

Procesar payments

POST /transactions/{transactionId}/payments/process

Procesa los payments pendientes de la transacción vía gateway. El endpoint ejecuta el routing para seleccionar el gateway y crea el ciclo de pago. Por defecto, se procesan todos los payments de la transacción en estado pending o waiting_payment. Puedes restringir el procesamiento a payments específicos enviando paymentIds.

Este endpoint soporta idempotencia. Envía el header Idempotency-Key con un valor único por solicitud para evitar procesamientos duplicados en caso de reintento.

Parámetros de ruta

transactionId

string

requerido

ID de la transacción (prefijo txn_).

Idempotency-Key

string

Clave única para garantizar la idempotencia de la solicitud. Opcional.

Cuerpo de la solicitud

customer

object

requerido

Datos del cliente, requeridos por el gateway.

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.document

string

requerido

Documento de identidad (mínimo 11 caracteres).

customer.documentType

string

requerido

Tipo de documento. Uno de: cpf, cnpj, passport.

customer.type

string

requerido

Tipo de persona. Uno de: individual, company.

customer.phone

object

Teléfono del cliente. Cuando está presente, requiere countryCode, areaCode y number (todos string, mínimo 1 carácter).

customer.address

object

Dirección del cliente. Cuando está presente, requiere street, number, neighborhood, city, state, country, zipCode (string, mínimo 1 carácter). complement es opcional.

creditCard

object

Datos de la tarjeta (requerido para credit_card).

Mostrar campos de creditCard

creditCard.cardId

string

ID de una tarjeta ya guardada (prefijo card_).

creditCard.token

string

Token de la tarjeta generado por el Tokenizer (mínimo 1 carácter).

creditCard.billingAddress

object

Dirección de facturación. Todos los campos (street, number, complement, neighborhood, city, state, country, zipCode) son strings opcionales.

boleto

object

Datos del boleto (requerido para boleto).

Mostrar campos de boleto

boleto.expiresAt

string

requerido

Fecha de vencimiento del boleto (ISO 8601).

boleto.instructions

string

Instrucciones del boleto (1 a 255 caracteres).

pix

object

Datos del PIX (requerido para pix).

Mostrar campos de pix

pix.expiresAt

string

requerido

Fecha de expiración del QR Code (ISO 8601).

string

IP del cliente.

metadata

object

Metadatos libres (clave/valor) para el procesamiento.

routerConfigId

string

ID de la configuración de routing a utilizar. Cuando se omite, se aplica el routing predeterminado de la company.

availableGatewayConfigIds

string[]

Restringe qué gateways puede elegir el routing.

paymentIds

string[]

IDs específicos de payments a procesar. Si se omite o está vacío, procesa todos los payments en estado pending/waiting_payment de la transacción.

Los campos creditCard, boleto y pix son opcionales en el schema, pero debes enviar el objeto correspondiente al paymentMethod de los payments que estás procesando; de lo contrario, el gateway no podrá completar el pago.

curl -X POST https://api.sandbox.z2pay.com/transactions/txn_3kf9a2b7c1d4e5/payments/process \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4d2a9c1e-7b30-4f88-9a2c-1e5f7b3c0d11" \
  -d '{
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "document": "12345678909",
      "documentType": "cpf",
      "type": "individual"
    },
    "pix": {
      "expiresAt": "2026-06-24T13:30:00.000Z"
    }
  }'

Respuesta

Cuando hay payments a procesar, la respuesta (200) incluye el conteo y el resultado por ciclo de procesamiento:

{
  "processed": 1,
  "results": [
    {
      "payments": [
        {
          "id": "pay_8h2k4m6n9p1q3r",
          "status": "waiting_payment",
          "provider": "provider_x",
          "gatewayConfigId": "gwc_9z8y7x6w5v"
        }
      ],
      "routing": {}
    }
  ]
}

processed

integer

Número de ciclos de procesamiento ejecutados.

results

object[]

Lista de resultados, uno por ciclo.

Mostrar campos de results[]

payments

object[]

Payments creados/actualizados en el ciclo. Cada elemento incluye id, status, provider y gatewayConfigId.

routing

object

Resultado del routing aplicado para seleccionar el gateway.

Si no hay ningún payment pendiente por procesar, la respuesta (200) es diferente: retorna results vacío y un mensaje informativo.

{
  "message": {
    "key": "errors.payments.no_pending",
    "fallback": "Nenhum payment pendente para processar"
  },
  "results": []
}

Códigos de estado

Código	Cuándo
`200`	Procesamiento completado (o ningún payment pendiente)
`404`	Transacción no encontrada

Reembolsar payment

POST /transactions/{transactionId}/payments/{paymentId}/refund

Crea una solicitud de refund (reembolso) para un payment específico. Soporta reembolso parcial a través del campo amount. El comportamiento de aprobación depende de la configuración refund.auto_approve de la company (por defecto: true):

Con auto-approve, el refund se crea, aprueba y procesa en el gateway de forma inmediata.
Sin auto-approve, el refund queda pendiente de aprobación manual.

Este endpoint soporta idempotencia. Envía el header Idempotency-Key para evitar reembolsos duplicados en caso de reintento.

Parámetros de ruta

transactionId

string

requerido

ID de la transacción (prefijo txn_).

paymentId

string

requerido

ID del payment a reembolsar (prefijo pay_).

Header

Idempotency-Key

string

Clave única para garantizar la idempotencia de la solicitud. Opcional.

Cuerpo de la solicitud

reason

string

requerido

Motivo del reembolso (1 a 4000 caracteres).

amount

integer

Valor a reembolsar, en centavos. Debe ser un entero positivo. Cuando se omite, reembolsa el valor total del payment.

curl -X POST https://api.sandbox.z2pay.com/transactions/txn_3kf9a2b7c1d4e5/payments/pay_8h2k4m6n9p1q3r/refund \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7e1b5d9a-2c44-4a10-8f33-6b9e2d1c0a55" \
  -d '{
    "reason": "Cliente desistiu da compra",
    "amount": 5000
  }'

Respuesta

La respuesta (200) es el objeto Refund creado:

{
  "id": "ref_2c5e8a1b4d7f9",
  "companyId": "comp_1a2b3c4d5e6f",
  "transactionId": "txn_3kf9a2b7c1d4e5",
  "paymentId": "pay_8h2k4m6n9p1q3r",
  "amount": 5000,
  "currency": "BRL",
  "status": "refunded",
  "reason": "Cliente desistiu da compra",
  "requestedBy": "api",
  "requestedByType": "api",
  "paymentMethod": "pix",
  "failureReason": null,
  "reviewedBy": null,
  "reviewedAt": null,
  "refundedAt": "2026-06-24T14:00:00.000Z",
  "createdAt": "2026-06-24T14:00:00.000Z",
  "updatedAt": "2026-06-24T14:00:00.000Z",
  "deletedAt": null
}

string

ID del refund (prefijo ref_).

paymentId

string

ID del payment reembolsado (prefijo pay_).

amount

integer

Valor reembolsado, en centavos.

status

string

Estado del refund. Cuando el refund queda pendiente de aprobación manual, llega en un estado anterior a refunded.

reason

string

Motivo informado.

failureReason

string | null

Motivo del fallo, cuando el reembolso falla en el gateway.

refundedAt

string | null

Fecha en que el reembolso fue efectuado. null mientras esté pendiente.

Los detalles completos del recurso de refund (todos los estados, flujo de aprobación y endpoints dedicados) están en Refunds.

Códigos de estado

Código	Cuándo
`200`	Refund creado (y procesado, si auto-approve)
`404`	Payment no encontrado
`409`	Payment no reembolsable o monto excede el límite

Para el formato de error y la lista general de códigos, consulta Errores.

Ver también

Transactions

El recurso padre de los payments.

Refunds

Detalles completos del recurso de reembolso.

Tokenizer

Genera el token de tarjeta para pagar con credit_card.

Simular pagos (Sandbox)

Fuerza el resultado de un PIX/boleto en el entorno de pruebas.

​Endpoints

​El objeto Payment

​Estado del payment

​Listar payments de la transacción

​Obtener payment por ID

​Procesar payments

​Parámetros de ruta

​Header

​Cuerpo de la solicitud

​Respuesta

​Reembolsar payment

​Parámetros de ruta

​Header

​Cuerpo de la solicitud

​Respuesta

​Ver también

Transactions

Refunds

Tokenizer

Simular pagos (Sandbox)

Endpoints

El objeto Payment

Estado del payment

Listar payments de la transacción

Obtener payment por ID

Procesar payments

Parámetros de ruta

Header

Cuerpo de la solicitud

Respuesta

Reembolsar payment

Parámetros de ruta

Header

Cuerpo de la solicitud

Respuesta

Ver también