Refunds - Z2Pay Developers

A refund returns the amount of a settled payment to the customer. In Z2Pay, a refund originates from a payment (pay_...) and goes through a lifecycle of statuses until it is processed at the gateway or via bank transfer (in the case of boleto). This page covers the retrieval and manual decision endpoints for refunds: fetch by ID, list by transaction or by payment, and approve or decline a pending refund.

Creating a refund is not done here. To open a refund request, use the refund endpoint in Payments (POST /transactions/{transactionId}/payments/{paymentId}/refund). This page documents what happens after the refund already exists.

All requests use the x-api-key header. See Authentication.

Endpoints

Method	Route	Description
`GET`	`/refunds/{id}`	Fetch a refund by ID
`GET`	`/refunds/transaction/{transactionId}`	List all refunds for a transaction
`GET`	`/refunds/payment/{paymentId}`	List all refunds for a payment
`POST`	`/refunds/{id}/approve`	Approve a pending refund and send it for processing
`POST`	`/refunds/{id}/refuse`	Decline a pending refund

Refund statuses

The status field indicates where in the lifecycle the refund currently is. Terminal statuses (no further transitions) are refunded, refused, and failed.

Status	Meaning
`pending`	Awaiting manual decision (approve or decline)
`approved`	Approved; transitioning to processing
`processing`	Being processed at the gateway
`refunded`	Refund completed (terminal)
`refused`	Request declined (terminal)
`failed`	Processing failed (terminal)
`awaiting_bank_details`	Boleto: waiting for the customer to provide bank account details
`bank_details_received`	Boleto: bank details received, ready for transfer
`invalid_bank_details`	Boleto: bank details invalid; a new request for details has been sent
`ted_processing`	Boleto: bank transfer (PIX/TED) in progress

Company auto-approve. Each company has an automatic refund approval setting (enabled by default). With auto-approve on, a card refund is created, approved, and processed immediately — meaning it may be born in approved/processing and never pass through pending. With auto-approve off, the refund starts in pending and must be approved via the endpoints below.

Boleto flow. Boleto refunds are not reversed at the gateway: the amount is returned via bank transfer (PIX/TED), so the customer’s bank details must be collected. For this reason, when a boleto refund is approved, it moves to awaiting_bank_details instead of processing. Once the details arrive (bank_details_received), the transfer is processed (ted_processing) until completion (refunded). Bank detail collection happens via a link/invitation sent to the customer, outside this set of endpoints.

Fetch refund by ID

GET /refunds/{id}

Returns the full details of a refund.

string

required

Refund ID (prefix ref_).

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

{
  "id": "ref_3kf9d2a7b1c5e8",
  "companyId": "comp_a1b2c3d4e5",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "refunded",
  "reason": "Cliente solicitou cancelamento",
  "requestedBy": "api",
  "requestedByType": "api",
  "paymentMethod": "credit_card",
  "failureReason": null,
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:45:02.000Z",
  "refundedAt": "2026-06-24T13:45:05.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:45:05.000Z",
  "deletedAt": null
}

string

Refund ID (ref_...).

transactionId

string

Transaction ID (txn_...).

paymentId

string

ID of the refunded payment (pay_...).

amount

integer

Refunded amount in cents (e.g., 4990 = R$ 49.90).

currency

string

Currency. Always BRL.

status

string

Current refund status (see the status table above).

reason

string

Reason provided when the refund was created.

requestedBy

string

Identifier of whoever requested the refund.

requestedByType

string

Source of the request: api, admin, customer, or gateway.

paymentMethod

string | null

Payment method of the refunded payment (e.g., credit_card, boleto). Can be null.

failureReason

string | null

Failure reason when status is failed. Otherwise null.

reviewedBy

string | null

Who approved or declined the refund. null while not yet reviewed.

reviewedAt

string | null

Date/time of the review (ISO 8601). null while not yet reviewed.

refundedAt

string | null

Date/time the refund was completed (ISO 8601). null while not yet completed.

createdAt

string

Creation date/time (ISO 8601).

updatedAt

string

Date/time of the last update (ISO 8601).

deletedAt

string | null

Soft-deletion date/time. Normally null.

Errors

Status	When it occurs
`404`	Refund not found

See Errors for the error response format.

List refunds by transaction

GET /refunds/transaction/{transactionId}

Returns a paginated list of all refunds associated with a transaction.

transactionId

string

required

Transaction ID (prefix txn_).

page

integer

default:"1"

Page number (starts at 1).

limit

integer

default:"20"

Items per page. Minimum 1, maximum 100.

curl "https://api.sandbox.z2pay.com/refunds/transaction/txn_9z8y7x6w5v4u?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "ref_3kf9d2a7b1c5e8",
      "transactionId": "txn_9z8y7x6w5v4u",
      "paymentId": "pay_1a2b3c4d5e6f",
      "amount": 4990,
      "currency": "BRL",
      "status": "refunded",
      "reason": "Cliente solicitou cancelamento",
      "paymentMethod": "credit_card",
      "refundedAt": "2026-06-24T13:45:05.000Z",
      "createdAt": "2026-06-24T13:44:58.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

data

array

List of refunds (same structure as Fetch refund by ID).

pagination

object

Show fields

page

integer

Current page.

limit

integer

Items per page.

total

integer

Total number of refunds found.

totalPages

integer

Total number of pages.

List refunds by payment

GET /refunds/payment/{paymentId}

Same as the previous endpoint, but filters refunds for a specific payment.

paymentId

string

required

Payment ID (prefix pay_).

page

integer

default:"1"

Page number (starts at 1).

limit

integer

default:"20"

Items per page. Minimum 1, maximum 100.

curl "https://api.sandbox.z2pay.com/refunds/payment/pay_1a2b3c4d5e6f?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

The response follows the same format (data + pagination) as the by-transaction endpoint.

Approve refund

POST /refunds/{id}/approve

Approves a pending refund and sends it for processing. For card payments, the refund is forwarded to the gateway. For boleto, the refund moves to awaiting_bank_details, waiting for the customer’s bank account information.

string

required

Refund ID (prefix ref_).

This endpoint is idempotent: resending the same request with the Idempotency-Key header does not produce a duplicate effect. See Conventions.

Idempotency-Key

string

Unique key to ensure the approval is applied only once.

curl -X POST https://api.sandbox.z2pay.com/refunds/ref_3kf9d2a7b1c5e8/approve \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 7c1f0e2a-9b3d-4a6e-8f12-5d0c9b8a7e6f"

{
  "id": "ref_3kf9d2a7b1c5e8",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "processing",
  "reason": "Cliente solicitou cancelamento",
  "paymentMethod": "credit_card",
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:50:11.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:50:11.000Z"
}

The returned status depends on the payment method: card refunds typically transition to processing (and then refunded), while boleto refunds move to awaiting_bank_details.

Errors

Status	When it occurs
`404`	Refund not found
`409`	The refund cannot be approved in its current status (e.g., already in a terminal state)

See Errors for the response format.

Decline refund

POST /refunds/{id}/refuse

Declines a pending refund, moving it to the terminal state refused.

string

required

Refund ID (prefix ref_).

The request body is optional and accepts a single field:

reason

string

Reason for the decline. When provided, must be between 1 and 4000 characters. The field is validated but does not replace the original reason of the refund in the response (which retains the reason provided at creation time).

This endpoint is idempotent — include the Idempotency-Key header for safe retries.

Idempotency-Key

string

Unique key to ensure the decline is applied only once.

curl -X POST https://api.sandbox.z2pay.com/refunds/ref_3kf9d2a7b1c5e8/refuse \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 1b2c3d4e-5f60-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Reembolso fora do prazo de política" }'

{
  "id": "ref_3kf9d2a7b1c5e8",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "refused",
  "reason": "Cliente solicitou cancelamento",
  "paymentMethod": "credit_card",
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:52:40.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:52:40.000Z"
}

Errors

Status	When it occurs
`404`	Refund not found
`409`	The refund cannot be declined in its current status (e.g., already in a terminal state)

See Errors for the response format.

Payments

Create a refund by reversing a payment.

Transactions

Understand the transaction that originated the payment.

Chargebacks

Reversals initiated by the card issuer.

Errors

Error format and how to handle them.

​Endpoints

​Refund statuses

​Fetch refund by ID

​List refunds by transaction

​List refunds by payment

​Approve refund

​Decline refund

​See also

Payments

Transactions

Chargebacks

Errors

Endpoints

Refund statuses

Fetch refund by ID

List refunds by transaction

List refunds by payment

Approve refund

Decline refund

See also