Transactions - Z2Pay Developers

A transaction (txn_) is the central object of the Core API: it groups what the buyer is paying for (the items) and how they are paying (the payments). Each payment represents an attempt/payment method (card, boleto, or Pix). The transaction status is never set directly — it is always calculated from the aggregate state of its payments.

All routes require the x-api-key header (your sandbox key). See Authentication. The examples below use the sandbox base URL https://api.sandbox.z2pay.com.

Endpoints

Method	Route	Description
`GET`	`/transactions`	Paginated list of transactions, with filters
`GET`	`/transactions/:id`	Fetches a transaction with its payments and items
`GET`	`/transactions/:id/items`	Lists only the transaction’s items
`POST`	`/transactions`	Creates a new transaction
`POST`	`/transactions/:id/refund`	Refunds all paid payments of the transaction

Transaction status

The status is derived from the payments through a central calculation. In summary (rules evaluated in order):

How the status is calculated

Payments with status replaced or deleted are ignored in the calculation.
If the transaction has a zero value → paid.
If there is no active payment → pending.
If all non-failed payments are refused → refused. If all are failed/expired → failed.
Among valid payments (excluding refused/failed/expired): if all are chargeback → chargeback; if all are canceled → canceled; if all are in_protest → in_protest.
If the amount effectively paid covers the total transaction amount → paid (even with a partial refund of the excess).
If there is an amount paid (> 0) less than the total and no refund activity → partially_paid.
If the settled legs are all in a refund cycle: all refunded → refunded; some partially_refunded → partially_refunded; otherwise → waiting_refund.
Remaining paid/held amount alongside active refund → partially_refunded.
Refunded amount covers the total → refunded.
Nothing paid and the amount waiting for payment covers the total → waiting_payment.
If none of the above apply → pending.

Possible status values:

Status	Meaning
`pending`	Created, with no confirmed payment and no defined waiting payment
`waiting_payment`	Awaiting payment (boleto/Pix issued, or payment created without processing)
`partially_paid`	Part of the amount was paid, but not the total
`paid`	Total amount paid
`refused`	Payment refused
`failed`	Terminal failure at the gateway
`canceled`	Canceled
`waiting_refund`	Refund requested, awaiting processing
`partially_refunded`	Part of the paid amount was refunded
`refunded`	Total amount refunded
`chargeback`	Subject to a chargeback
`in_protest`	In protest (chargeback dispute in progress)

Since the status aggregates payments, a transaction with more than one payment (e.g., two cards, or Pix + card) may go through intermediate states such as partially_paid or partially_refunded.

Create transaction

POST /transactions Creates a transaction. You always provide the customer and at least one item. The payments are optional:

With payments and processing data (creditCard/boleto/pix) → payments are processed immediately at the gateway.
With payments without processing data → payments remain awaiting processing.
Without payments → the transaction stays waiting_payment.

Idempotent endpoint. Send the Idempotency-Key header (TTL of 7 days) to ensure that retries of the same request do not create duplicate transactions. See Conventions.

Important business rules

customer and customerId are mutually exclusive. Send one of the two (required): customerId to reuse an existing customer, or customer inline to create/identify the customer on the spot. Sending both, or neither, results in 400.

The sum of the payments must match the sum of the items. When payments is provided, the sum of payment.amount must be exactly equal to the total of the items (Σ item.amount × item.quantity). Otherwise, 400. All values are integers in cents.

Request body

customerId

string

ID of an existing customer (cust_). Mutually exclusive with customer.

customer

object

Inline customer data. Mutually exclusive with customerId.

Show customer fields

customer.name

string

required

Customer name (minimum 2 characters).

customer.email

string

required

Valid email address.

customer.type

string

required

Customer type. Values: individual or company.

customer.document

string

required

Document number (minimum 6 characters).

customer.documentType

string

Document type. Values: cpf, cnpj, or passport.

customer.phone

string

required

Customer phone number.

customer.address

object

Buyer’s address. Fields: street, number, complement, neighborhood, city, state, postalCode, country (all optional, may be null). Missing fields may be completed by the gateway configuration.

referenceCode

string

required

Your reference code for the transaction (1 to 255 characters). Use it to correlate with your own system.

items

array

required

List of items (minimum 1).

Show fields for each item

items[].description

string

required

Item description (1 to 255 characters).

items[].quantity

integer

required

Quantity (integer, minimum 1).

items[].amount

integer

required

Unit amount in cents (integer, minimum 1).

items[].code

string

Item code/SKU (1 to 255 characters).

items[].type

string

Item type (up to 50 characters).

items[].imageUrl

string

Item image URL (valid URL, up to 500 characters).

payments

array

Payment methods. If omitted, the transaction stays waiting_payment.

Show fields for each payment

payments[].paymentMethod

string

required

Method. Values: credit_card, boleto, or pix.

payments[].amount

integer

required

Payment amount in cents (integer, minimum 1).

payments[].installments

integer

default:"1"

Number of installments (integer, minimum 1). Installments (> 1) are only allowed for credit_card.

payments[].additionalInfo

object

Free-form metadata (key-value object).

payments[].creditCard

object

Card processing data (only with paymentMethod: credit_card). Requires id or token of the card. Fields: id (crd_), token, statementDescriptor (soft descriptor, up to 100 characters), and billingAddress.

payments[].boleto

object

Boleto data (only with paymentMethod: boleto). Fields: expirationDate (date), instructions (1 to 255 characters).

payments[].pix

object

Pix data (only with paymentMethod: pix). Field: expirationDate (date).

payments[].splitId

string

ID of a saved split configuration. Mutually exclusive with split.

payments[].split

array

Inline split configuration. Mutually exclusive with splitId. See Split.

currency

string

ISO 4217 currency code (3 letters, e.g., BRL). Default: company configuration or BRL.

redirectUrl

string

Redirect URL after payment (valid URL).

postbackUrl

string

URL to receive notifications for this transaction (valid URL). See Webhooks.

string

Buyer’s IP address.

additionalInfo

object

Free-form transaction metadata (key-value object). Searchable via the metadataSearch filter.

maxInstallments

integer

Maximum number of installments allowed (integer, minimum 1).

routerConfigId

string

Override for the routing configuration (optional).

Example: create a Pix transaction

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

The item costs 9990 cents (R$ 99.90) and the payment totals 9990 — the sums match, so the request is valid.

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

Response 201 Created. The JSON example is illustrative — verify the actual fields in your environment’s response.

Example: create and charge with a tokenized card

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

Two items at 5000 × 2 = 10000 cents; the payment totals 10000. The sums match. The card is sent as a token (generated by the Tokenizer) — never send raw card data to the Core API.

List transactions

GET /transactions Returns a paginated list. All filters are optional and can be combined.

Query parameters

page

integer

Page number (pagination). See Conventions.

limit

integer

Items per page.

status

string

Filter by transaction status.

currency

string

Filter by currency.

paymentMethod

string

Filter by payment method.

string

Transaction ID (partial match, ILIKE).

referenceCode

string

Filter by your reference code.

customerName

string

Filter by customer name.

customerEmail

string

Filter by customer email.

customerDocument

string

Filter by customer document.

customerSearch

string

Combined search across customer name/email/document.

recipientIds

string

List of recipient IDs (comma-separated) that must appear in any split of the transaction.

metadataSearch

string

Full-text search across any value stored in additionalInfo.

string

Generic search.

startDate

string

Start date. ISO 8601 with timezone (e.g., 2026-06-01T00:00:00.000Z).

endDate

string

End date. ISO 8601 with timezone.

dateField

string

Date field used by startDate/endDate. Values: createdAt, paidAt, refundedAt, canceledAt, chargedbackAt, protestedAt.

sortBy

string

Sort field. Values: createdAt, paidAt, amount, status, customerName.

sortDir

string

Sort direction. Values: asc or desc.

Example

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
}

The exact format of the pagination envelope is described in Conventions. The JSON above is illustrative.

Fetch transaction by ID

GET /transactions/:id Returns the complete transaction data, including its payments and items.

string

required

Transaction ID (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

Calculated transaction status. See the table in Transaction status.

payments

array

Transaction payments. For payment details, see Payments.

items

array

Transaction items.

If the ID does not exist, the response is 404. See Errors.

List transaction items

GET /transactions/:id/items Returns only the items (products/services) of the transaction, under a data key.

string

required

Transaction ID (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
    }
  ]
}

If the transaction does not exist, the response is 404.

Refund transaction

POST /transactions/:id/refund Creates refund requests for all paid payments of the transaction at once. The approval behavior depends on the company’s refund.auto_approve setting (default: enabled):

With auto-approve: the refund is created, approved, and processed at the gateway immediately.
Without auto-approve: the refunds remain pending manual approval.

Idempotent endpoint — send Idempotency-Key. To refund a specific payment (partial refund), use the Refunds / Payments endpoint.

string

required

Transaction ID (txn_).

reason

string

required

Refund reason (1 to 4000 characters).

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

Possible responses

200 — refunds created and processed.
404 — transaction not found.
409 — no refundable payment found (e.g., no payment is in a paid state).

See Errors for the error format.

Payments

Details of each payment method within the transaction.

Refunds

Refunding a specific payment and partial refunds.

Tokenizer

Generate the card token before creating the transaction.

Split

Configure payouts per payment with split or splitId.

Customers

Webhooks

Receive notifications of transaction status changes.

​Endpoints

​Transaction status

​Create transaction

​Important business rules

​Request body

​Example: create a Pix transaction

​Example: create and charge with a tokenized card

​List transactions

​Query parameters

​Example

​Fetch transaction by ID

​List transaction items

​Refund transaction

​Possible responses

​See also

Payments

Refunds

Tokenizer

Split

Customers

Webhooks

Endpoints

Transaction status

Create transaction

Important business rules

Request body

Example: create a Pix transaction

Example: create and charge with a tokenized card

List transactions

Query parameters

Example

Fetch transaction by ID

List transaction items

Refund transaction

Possible responses

See also