Payments - Z2Pay Developers

A payment is an individual payment entry within a transaction. A single transaction can have multiple payments (for example, part charged to a card and part via PIX), which is why all endpoints on this page live under /transactions/:transactionId/payments.

All requests use the header x-api-key: YOUR_SANDBOX_KEY. See Authentication for details. The sandbox base URL is https://api.sandbox.z2pay.com.

Endpoints

Method	Route	Description
`GET`	`/transactions/{transactionId}/payments`	Lists all payments for the transaction
`GET`	`/transactions/{transactionId}/payments/{paymentId}`	Retrieves a payment by ID
`POST`	`/transactions/{transactionId}/payments/process`	Processes pending payments through the gateway
`POST`	`/transactions/{transactionId}/payments/{paymentId}/refund`	Refunds a payment

The Payment object

The fields below make up the Payment object returned by the list and retrieve endpoints. Monetary values are integers in cents (e.g., 15000 = R$ 150.00). Dates are ISO 8601 strings with timezone and are null when they have not occurred yet.

string

Payment identifier (prefix pay_).

transactionId

string

ID of the transaction this payment belongs to (prefix txn_).

replacedByPaymentId

string | null

When the payment was replaced (status replaced), points to the new payment that replaced it. null otherwise.

companyId

string

ID of the company that owns the payment.

amount

integer

Payment amount, in cents.

currency

string

Payment currency. Default: BRL.

installments

integer

Number of installments. Default: 1.

paymentMethod

string

Payment method. One of: credit_card, boleto, pix.

provider

string | null

Internal identifier of the provider that processed the payment. null while not yet processed.

gatewayConfigId

string | null

ID of the gateway configuration selected by the routing engine. null while not yet processed.

cardId

string | null

ID of the card used (prefix card_), when applicable. null for boleto/PIX.

status

string

Current status of the payment. See the list of values in Payment status.

additionalInfo

object | null

Free-form metadata associated with the payment. null when absent.

statementDescriptor

string | null

Soft descriptor sent to the cardholder on their statement (already normalized, maximum 13 characters). null when not set.

boletoUrl

string | null

Boleto URL (PDF/view). Populated after a boleto payment is processed.

boletoDigitableLine

string | null

Boleto digitable line (linha digitável).

boletoBarcode

string | null

Boleto barcode.

pixUrl

string | null

URL of the PIX QR Code image (for display/scanning).

pixCopyPaste

string | null

PIX BR Code payload (copy-and-paste, EMV starting with 00020126...), to be pasted into the banking app.

splitConfigId

string | null

ID of the split configuration applied to the payment, if any.

originalAmount

integer | null

Original amount before adjustments (in cents), when applicable.

acquirerReturnCode

string | null

Return code from the acquirer.

acquirerReturnMessage

string | null

Return message from the acquirer.

retryable

boolean | null

Indicates whether a failure can be retried. null when not applicable.

declineCode

string | null

Decline code, when the payment was declined.

errorMessage

string | null

Processing error message, when present.

createdAt

string

Creation date (ISO 8601).

updatedAt

string

Last updated date (ISO 8601).

paidAt

string | null

Date when the payment was paid. null while not yet paid.

expiresAt

string | null

Expiration date of the payment instrument (e.g., PIX QR Code TTL, boleto due date). null when not applicable.

canceledAt

string | null

Cancellation date. null when not canceled.

refundedAt

string | null

Refund date. null when not refunded.

chargedbackAt

string | null

Chargeback date. null when no chargeback occurred.

protestedAt

string | null

Date when the payment entered protest. null when not applicable.

deletedAt

string | null

Logical deletion date (soft delete). null for active payments.

version

integer | null

Optimistic concurrency version of the record.

Payment status

The status field takes one of the following values:

Status	Meaning
`pending`	Created, not yet processed
`waiting_payment`	Awaiting payment (boleto/PIX issued)
`authorized`	Authorized (card), not yet captured/settled
`paid`	Paid
`partially_paid`	Partially paid
`refused`	Declined by the acquirer
`failed`	Processing failure
`canceled`	Canceled
`expired`	Expired before completion (e.g., PIX QR Code or overdue boleto)
`replaced`	Replaced by another payment
`waiting_refund`	Refund requested, awaiting processing
`refunded`	Fully refunded
`partially_refunded`	Partially refunded
`chargeback`	Chargeback registered
`in_protest`	Under protest
`deleted`	Logically removed

List payments for a transaction

GET /transactions/{transactionId}/payments

Returns all payments associated with a specific transaction.

transactionId

string

required

Transaction ID (prefix txn_).

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

The response (200) wraps the list in the data field:

{
  "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[]

List of payments for the transaction. See The Payment object.

Status codes

Code	When
`200`	List returned
`404`	Transaction not found

Retrieve a payment by ID

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

Returns the data for a specific payment.

transactionId

string

required

Transaction ID (prefix txn_).

paymentId

string

required

Payment ID (prefix pay_).

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

The response (200) is the Payment object directly (no 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
}

For boleto, use boletoUrl, boletoDigitableLine, and boletoBarcode. For PIX, use pixUrl (QR Code) and pixCopyPaste (copy-and-paste). These fields are only populated after the payment is processed by the gateway.

Status codes

Code	When
`200`	Payment returned
`404`	Payment not found

Process payments

POST /transactions/{transactionId}/payments/process

Processes the pending payments of a transaction through the gateway. This endpoint runs the routing engine to select the gateway and initiates the payment cycle. By default, all payments with status pending or waiting_payment are processed. You can restrict processing to specific payments by providing paymentIds.

This endpoint supports idempotency. Send the Idempotency-Key header with a unique value per request to prevent duplicate processing in case of retries.

Path parameters

transactionId

string

required

Transaction ID (prefix txn_).

Idempotency-Key

string

Unique key to ensure request idempotency. Optional.

Request body

customer

object

required

Customer data, required by the gateway.

Show customer fields

customer.name

string

required

Customer name (minimum 2 characters).

customer.email

string

required

Valid email address.

customer.document

string

required

Document number (minimum 11 characters).

customer.documentType

string

required

Document type. One of: cpf, cnpj, passport.

customer.type

string

required

Person type. One of: individual, company.

customer.phone

object

Customer phone number. When present, requires countryCode, areaCode, and number (all strings, minimum 1 character).

customer.address

object

Customer address. When present, requires street, number, neighborhood, city, state, country, zipCode (strings, minimum 1 character). complement is optional.

creditCard

object

Card data (required for credit_card).

Show creditCard fields

creditCard.cardId

string

ID of a previously saved card (prefix card_).

creditCard.token

string

Card token generated by the Tokenizer (minimum 1 character).

creditCard.billingAddress

object

Billing address. All fields (street, number, complement, neighborhood, city, state, country, zipCode) are optional strings.

boleto

object

Boleto data (required for boleto).

Show boleto fields

boleto.expiresAt

string

required

Boleto due date (ISO 8601).

boleto.instructions

string

Boleto instructions (1 to 255 characters).

pix

object

PIX data (required for pix).

Show pix fields

pix.expiresAt

string

required

QR Code expiration date (ISO 8601).

string

Customer IP address.

metadata

object

Free-form metadata (key/value) for the processing.

routerConfigId

string

ID of the routing configuration to use. When omitted, the company’s default routing is applied.

availableGatewayConfigIds

string[]

Restricts which gateways the routing engine may select.

paymentIds

string[]

Specific payment IDs to process. If omitted or empty, all payments with status pending/waiting_payment in the transaction are processed.

The creditCard, boleto, and pix fields are optional in the schema, but you must send the object that corresponds to the paymentMethod of the payments being processed — otherwise the gateway will not be able to complete the payment.

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

Response

When there are payments to process, the response (200) returns the count and the result for each processing cycle:

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

processed

integer

Number of processing cycles executed.

results

object[]

List of results, one per cycle.

Show results[] fields

payments

object[]

Payments created/updated in the cycle. Each item includes id, status, provider, and gatewayConfigId.

routing

object

Routing result used to select the gateway.

If there are no pending payments to process, the response (200) differs: it returns an empty results array and an informational message.

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

Status codes

Code	When
`200`	Processing completed (or no pending payments)
`404`	Transaction not found

Refund a payment

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

Creates a refund request for a specific payment. Supports partial refunds via the amount field. The approval behavior depends on the company’s refund.auto_approve setting (default: true):

With auto-approve, the refund is created, approved, and processed through the gateway immediately.
Without auto-approve, the refund remains pending manual approval.

This endpoint supports idempotency. Send the Idempotency-Key header to prevent duplicate refunds in case of retries.

Path parameters

transactionId

string

required

Transaction ID (prefix txn_).

paymentId

string

required

ID of the payment to refund (prefix pay_).

Header

Idempotency-Key

string

Unique key to ensure request idempotency. Optional.

Request body

reason

string

required

Refund reason (1 to 4000 characters).

amount

integer

Amount to refund, in cents. Must be a positive integer. When omitted, the full payment amount is refunded.

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

Response

The response (200) is the Refund object created:

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

Refund ID (prefix ref_).

paymentId

string

ID of the refunded payment (prefix pay_).

amount

integer

Refunded amount, in cents.

status

string

Refund status. When the refund is pending manual approval, this will be in a status prior to refunded.

reason

string

Reason provided.

failureReason

string | null

Failure reason, when the refund fails at the gateway.

refundedAt

string | null

Date when the refund was completed. null while pending.

Complete details about the refund resource (all statuses, approval flow, and dedicated endpoints) are available in Refunds.

Status codes

Code	When
`200`	Refund created (and processed, if auto-approve)
`404`	Payment not found
`409`	Payment is not refundable or amount exceeds the limit

For the error format and the full list of status codes, see Errors.

Transactions

The parent resource of payments.

Refunds

Complete details about the refund resource.

Tokenizer

Generate a card token to pay with credit_card.

Simulate payments (Sandbox)

Force the outcome of a PIX/boleto in the test environment.

​Endpoints

​The Payment object

​Payment status

​List payments for a transaction

​Retrieve a payment by ID

​Process payments

​Path parameters

​Header

​Request body

​Response

​Refund a payment

​Path parameters

​Header

​Request body

​Response

​See also

Transactions

Refunds

Tokenizer

Simulate payments (Sandbox)

Endpoints

The Payment object

Payment status

List payments for a transaction

Retrieve a payment by ID

Process payments

Path parameters

Header

Request body

Response

Refund a payment

Path parameters

Header

Request body

Response

See also