📘
"paymentMethodName": "PIX"

Payment Method Features

Feature	Value
Country	Brazil
Processing Currencies	BRL
Payments	Yes
*-- Min per transaction amount*	0.10 BRL, unless another limit is defined in your contract
*-- Max per transaction amount*	50,000.00 BRL, unless another limit is defined in your contract
Refunds	Full & Partial
*-- Full Refund*	Yes
*-- Partial Refund*	Yes
*-- Multiple Partial Refunds*
Chargebacks	No

Workflow: Payments

Create an Intent containing one PIX payment.
The platform validates the request and creates the payment.
The synchronous response contains the PIX Copy and Paste payload and a Base64-encoded QR image.
Display the QR code to the payer or provide a button for copying the PIX payload.
The payer scans the QR code or pastes the payload into a PIX-enabled banking or wallet application and confirms the payment.
Wait for the payment webhook. A successful PIX payment reaches the CAPTURED status.

⚠️
The synchronous Intent response confirms that the PIX payment was created; it does not confirm that the payer completed the transfer. Treat the payment as successful only after its status becomes CAPTURED.

List of used API Requests

Request	Endpoint	Description
Intent Creation	`POST /processing/api/v1/intents`	Creates a new Intent with a PIX payment. The response contains the payment identifier, current status, PIX Copy and Paste payload, and QR image.
Refund Creation	`POST /api/v1/refunds`	Creates a full or partial refund for a previously captured PIX payment. The refund is returned to the original payment source.

Intent Creation Request/Response

📓
Request specifics

Endpoint: POST /processing/api/v1/intents

Purpose: Creates an Intent and a PIX Payment.

Structure: The standard Intent request is used.

For PIX:

paymentMethodName must be set to PIX.

submittedAmount.currency can be BRL or another supported currency when FX conversion is used.

authCurrencyCode must be BRL.

incomingDetails.documentType and incomingDetails.documentNumber must contain the payer's valid CPF or CNPJ details.

payer.firstname, payer.lastname, and payer.merchantPayerReference are required for PIX processing.

payer.email and payer.phone are optional and should be sent only when available.

Provide a meaningful description either at the Intent level or in the Payment object. The Payment-level value takes precedence. If both descriptions are omitted, the platform sends a generic static description to the payment partner; the reduced transaction context may negatively affect payment conversion.

Intent Request: Example

{
  "clientReferenceId": "order-123456789",
  "useCheckoutForm": false,
  "payments": [
    {
      "payer": {
        "firstname": "Maria",
        "lastname": "Oliveira",
        "merchantPayerReference": "customer-123456"
      },
      "paymentInstrument": {
        "paymentMethodName": "PIX",
        "incomingDetails": {
          "documentType": "CPF",
          "documentNumber": "52998224725"
        }
      },
      "submittedAmount": {
        "value": 100.00,
        "currency": "BRL"
      },
      "authCurrencyCode": "BRL",
      "description": "Order 123456789",
      "webhookUrl": "https://merchant.example.com/webhooks/payments"
    }
  ]
}

Intent Request: Fields Description

Top-Level Request Parameters

Parameter	Type	Required	Description
`clientReferenceId`	String	`Required`	Order or Intent reference in the merchant system.
`useCheckoutForm`	Boolean	`Optional`	Determines whether the platform Checkout form is used. For a direct server-to-server PIX integration, set this field to `false`. If omitted, it is treated as `false`.
`payments`	Array of Objects	`Required`	List of payments to create within the Intent. For the flow described on this page, include one PIX payment.
`description`	String	`Optional`	Intent-level description. It may be used as a fallback when the payment-level `description` is omitted.
`merchant`	Object	`Optional`	Merchant information associated with the request.
`extensionAttributes`	Object	`Optional`	Additional key-value attributes forwarded to the payment partner as agreed with our integration team. Do not use this object to send ordinary PIX or payer parameters.

payment

Parameter	Type	Required	Description
`clientReferenceId`	String	`Optional`	Merchant reference for this individual payment. It must be unique per settlement account. When supplied, it is returned as `clientReferenceTransactionId`. Maximum length: 2,048 characters.
`payer`	Object	`Required`	Payer information required to create the PIX payment.
`paymentInstrument`	Object	`Required`	Payment method and method-specific input.
`submittedAmount`	Object	`Required`	Payment amount in `BRL` or another supported submitted currency when FX conversion is enabled.
`authCurrencyCode`	String	`Required`	Authorisation currency. For PIX, use `BRL`.
`description`	String	`Optional`	Payment reason or order title. Maximum 128 characters for PIX. If omitted, the platform uses the Intent description or a platform-generated fallback when creating the partner payment.
`webhookUrl`	String	`Required`	HTTPS URL to which payment status change webhooks will be sent.
`clientData`	Object	`Optional`	Merchant-defined data stored and returned without affecting PIX processing.

payer

Parameter	Type	Required	Description
`firstname`	String	`Required`	Payer's first name.
`lastname`	String	`Required`	Payer's last name.
`email`	String	`Optional`	Payer's email address, for example `[email protected]`.
`phone`	String	`Optional`	Payer's phone number in international format, for example `+5511999999999`.
`merchantPayerReference`	String	`Required`	Stable identifier of the payer in the merchant system. It is used as the payer identifier for PIX processing. Do not send random or fictitious values in production.

paymentInstrument

Parameter	Type	Required	Description
`paymentMethodName`	String	`Required`	Payment method name. For this flow, use `PIX`.
`incomingDetails`	Object	`Required`	PIX-specific payer identification details.

incomingDetails

Parameter	Type	Required	Description
`documentType`	String	`Required`	Brazilian tax document type. Possible values: `CPF` or `CNPJ`.
`documentNumber`	String	`Required`	Valid document number matching `documentType`, containing digits only: 11 digits for CPF or 14 digits for CNPJ.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Payment amount.
`currency`	String	`Required`	Payment currency in ISO 4217 alpha-3 format. Use `BRL` when no FX conversion is required; another supported currency may be used when FX is enabled.

merchant

Parameter	Type	Required	Description
`name`	String	`Optional`	Store or merchant name.
`website`	String	`Optional`	Store or merchant website.

extensionAttributes

A free-form set of key-value attributes that the platform forwards to the payment partner as agreed with our integration team.

Send this object only when its use has been explicitly agreed for your account.
Do not place CPF/CNPJ, payer name, amount, payment reference, or webhook URL in this object. Use the standard fields documented above.
The object is not returned in Intent or Payment responses and is not included in webhooks.

Parameter	Type	Required	Description
`{attributeName}`	String	`Optional`	Attribute name and value supplied by our integration team.

📓
Response specifics

The successful creation response normally returns the PIX payment with status AUTHORIZATION_REQUESTED.

payments[].additionalData.details.url contains the PIX Copy and Paste payload, also known as the EMV BR Code payload.

payments[].additionalData.details.qrBase64 contains a Base64-encoded PNG image generated from the same payload.

The value in details.url is payment data, not an HTTP URL and not a universal mobile-app deep link.

Intent Response: Example

{
  "intentId": "232510340021612544",
  "payments": [
    {
      "id": "232510340646563840",
      "payer": {
        "firstname": "Maria",
        "lastname": "Oliveira",
        "merchantPayerReference": "customer-123456"
      },
      "submittedAmount": {
        "value": 100.00,
        "currency": "BRL"
      },
      "authAmount": {
        "value": 100.00,
        "currency": "BRL"
      },
      "paymentInstrument": {
        "id": "PI204264628196626432",
        "paymentMethodId": "PM199507277233246209",
        "paymentMethodName": "PIX"
      },
      "status": "AUTHORIZATION_REQUESTED",
      "additionalData": {
        "details": {
          "url": "00020126580014br.gov.bcb.pix013627a44d0a-0736-4bbf-a4a4-6e11063973315204000053039865406100.005802BR5908PAGSMILE6008So Paulo62230519mpqrinter123742074363049E0B",
          "qrBase64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5Mz"
        }
      }
    }
  ],
  "disbursements": [],
  "clientReferenceIntentId": "order-123456789",
  "paymentCreationErrors": [],
  "disbursementCreationErrors": [],
  "intentStatus": "IN_PROGRESS"
}

Response Description

Top-Level Response Parameters

Parameter	Type	Required	Description
`intentId`	String	`Required`	Unique identifier of the Intent in our platform.
`payments`	Array of Objects	`Required`	Payments created within the Intent.
`disbursements`	Array	`Optional`	Disbursements created within the Intent. Empty for a PIX pay-in-only request.
`clientReferenceIntentId`	String	`Required`	Merchant's Intent reference returned from the request.
`paymentCreationErrors`	Array	`Required`	Payment creation errors. Empty when the PIX payment was created successfully.
`disbursementCreationErrors`	Array	`Required`	Disbursement creation errors. Empty for a PIX pay-in-only request.
`intentStatus`	String	`Required`	Current Intent status. While the payer has not completed the PIX transfer, the value is normally `IN_PROGRESS`.

payment

Parameter	Type	Required	Description
`id`	String	`Required`	Unique payment identifier. Store this value because it is required to create a refund.
`payer`	Object	`Required`	Payer details returned from the request.
`submittedAmount`	Object	`Required`	Submitted payment amount and currency.
`authAmount`	Object	`Required`	Authorised payment amount and currency. For PIX without FX, it matches `submittedAmount`.
`paymentInstrument`	Object	`Required`	PIX payment instrument information.
`processingStatusCode`	String	`Optional`	Platform processing status code. It may indicate successful processing or an error.
`statusMessage`	String	`Optional`	Processing status message, normally returned when an error occurs.
`status`	String	`Required`	Current payment status. `AUTHORIZATION_REQUESTED` means the PIX payment is awaiting the payer; `CAPTURED` means the payment succeeded.
`additionalData`	Object	`Required`	PIX data required to present and complete the payment.
`clientReferenceTransactionId`	String	`Optional`	Merchant's payment-level reference, returned when `payments[].clientReferenceId` was supplied in the request.

paymentInstrument

Parameter	Type	Required	Description
`id`	String	`Optional`	Unique identifier of the payment instrument.
`paymentMethodId`	String	`Optional`	Unique identifier of the configured payment method.
`paymentMethodName`	String	`Required`	Payment method name. For this flow, the value is `PIX`.
`storedDetails`	Object	`Optional`	Stored method details. This field may be omitted for PIX.

additionalData

Parameter	Type	Required	Description
`details`	Object	`Required`	PIX presentation data required to complete the payment.

details

Parameter	Type	Required	Description
`url`	String	`Required`	PIX Copy and Paste payload in EMV BR Code format. Display it as copyable text or encode it as a QR code. Despite the generic field name, this value is not an HTTP URL and must not be treated as a universal deep link.
`qrBase64`	String	`Required`	Base64-encoded PNG containing the QR code for the value in `url`. The value may be returned with or without the `data:image/png;base64,` prefix.

Presenting PIX to the Payer

Payer environment	Recommended experience
Desktop	Render `qrBase64` as an image and also provide the value from `url` behind a Copy PIX code button.
Mobile	Provide a Copy PIX code button using `url`. The payer can paste the value into a PIX-enabled banking or wallet application.
App-to-app	Do not prepend an invented URI scheme to `url`. The EMV payload is not itself a universal deep link. Use a bank-specific or an approved app-picker flow only when separately agreed and documented.

📘
The QR image and the Copy and Paste value represent the same PIX payment. Do not alter the payload, amount, CRC, or any character inside it.

Payment Statuses

Status	Meaning	Merchant action
`AUTHORIZATION_REQUESTED`	The PIX payment was created and is waiting for the payer to complete the transfer.	Display the QR code or Copy and Paste payload and wait for a webhook.
`CAPTURED`	The PIX transfer was successfully completed.	Fulfil the order.
`DECLINED`	The payment was rejected.	Do not fulfil the order. A new payment may be created if the payer wants to try again.
`CANCELLED`	The payment was expired before completion.	Do not fulfil the order.
`ERROR`	A technical or processing error prevented the payment from completing.	Do not fulfil the order. Use the error fields for diagnostics and create a new payment only when appropriate.

Refunds

PIX refunds are returned to the payer's original payment source.

To initiate a full or partial refund, send a separate request to Create Refund.

⚠️
A refund can be created only for a payment in the CAPTURED status. The synchronous refund response confirms that the refund was accepted for processing; wait for the refund webhook or retrieve the refund by ID to obtain its final status.

Full Refund Request

{
  "paymentId": 232510340646563840,
  "partial": false,
  "reason": "Customer requested a refund",
  "webhookUrl": "https://merchant.example.com/webhooks/refunds",
  "clientReferenceId": "refund-20260909-0001"
}

For a full refund, partial may be set to false or omitted. Do not send paymentSubmittedAmount or paymentAuthAmount; the platform calculates the remaining refundable amount.

Partial Refund Request

{
  "paymentId": 232510340646563840,
  "partial": true,
  "paymentSubmittedAmount": {
    "value": 5.00,
    "currency": "BRL"
  },
  "reason": "Partial return of the order",
  "webhookUrl": "https://merchant.example.com/webhooks/refunds",
  "clientReferenceId": "refund-20260909-0002"
}

Use exactly one amount object for a partial refund. Use paymentSubmittedAmount to define the refund in the original submitted currency, or paymentAuthAmount to define it in the PIX authorisation currency (BRL). If the original payment involved FX, the platform calculates the other amount using the exchange rate stored for the original payment.

Refund amount rules

Rule	Description
Eligible payment	The original payment must have status `CAPTURED` and must belong to the settlement account making the refund request.
Full refund	Set `partial` to `false` or omit it. Do not send an amount object. The remaining refundable amount is refunded.
Partial refund	Set `partial` to `true` and provide one positive refund amount using either `paymentSubmittedAmount` or `paymentAuthAmount`.
Mutually exclusive amount objects	Do not send `paymentSubmittedAmount` and `paymentAuthAmount` in the same PIX refund request.
Currency	Each refund amount currency must match the corresponding currency of the original payment. The authorised currency for PIX is `BRL`; the submitted currency may differ when FX was used.
Maximum refundable amount	The requested amount plus previous active or successful refunds must not exceed the amount of the original payment.
Multiple partial refunds	Not yet confirmed for PIX through Pagsmile. Do not rely on multiple partial refunds until this capability is enabled for your account and documented in the final integration guide.
Refund destination	Funds are returned to the original PIX payment source. Do not send `recipientPhone` or `recipientBankCode`; those fields are not part of the PIX refund flow.
Idempotency	Supply a unique `clientReferenceId` for every refund. Reusing the same value for the same settlement account results in HTTP `409 Conflict`, including when the previous refund ended unsuccessfully.

Top-Level Refund Request Parameters

Parameter	Type	Required	Description
`paymentId`	int64	`Required`	Identifier of the original captured PIX payment. Use the `payments[].id` returned by the Intent response.
`partial`	Boolean	`Optional`	Set to `true` for a partial refund. Set to `false` or omit for a full refund.
`paymentSubmittedAmount`	Object	`Conditional`	Partial refund amount in the original submitted currency. Its currency must match `submittedAmount.currency` of the original payment. Required when `partial = true` and this representation is selected. Do not send with `paymentAuthAmount`.
`paymentAuthAmount`	Object	`Conditional`	Partial refund amount in the authorised currency. For PIX, the currency must be `BRL`. Required when `partial = true` and this amount representation is selected. Do not send with `paymentSubmittedAmount`.
`reason`	String	`Optional`	Free-form refund reason used for informational and audit purposes.
`webhookUrl`	String	`Optional`	HTTPS URL to which refund status change webhooks will be sent. Supplying it is strongly recommended.
`clientReferenceId`	String	`Optional`	Merchant's unique refund reference and idempotency key. Maximum length: 2,048 characters. Supplying it is strongly recommended. It is returned as `clientReferenceTransactionId`.

paymentSubmittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Positive partial refund amount.
`currency`	String	`Required`	Refund currency in ISO 4217 alpha-3 format. It must match the submitted currency of the original payment.

paymentAuthAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Positive partial refund amount.
`currency`	String	`Required`	Refund currency in ISO 4217 alpha-3 format. For PIX, use `BRL`.

Refund Response: Example

{
  "id": "232510341198221312",
  "intentId": "232510340021612544",
  "paymentId": "232510340646563840",
  "refundSubmittedAmount": {
    "value": 5.00,
    "currency": "BRL"
  },
  "refundAuthAmount": {
    "value": 5.00,
    "currency": "BRL"
  },
  "refundExchangeRate": 1.00,
  "reason": "Partial return of the order",
  "status": "REFUND_REQUESTED",
  "createdAt": "2026-09-09T11:55:02Z",
  "updatedAt": "2026-09-09T11:55:02Z",
  "clientReferenceTransactionId": "refund-20260909-0002"
}

Refund Response Parameters

Parameter	Type	Required	Description
`id`	String	`Required`	Unique refund identifier. Use it with `GET /api/v1/refunds/{id}`.
`intentId`	String	`Required`	Identifier of the Intent containing the original PIX payment.
`paymentId`	String	`Required`	Identifier of the original PIX payment.
`refundSubmittedAmount`	Object	`Required`	Refund amount in the original submitted currency. It may differ from `BRL` when the original payment involved FX.
`refundAuthAmount`	Object	`Required`	Refund amount in the authorised currency. For PIX, the currency is `BRL`.
`refundExchangeRate`	Number	`Optional`	Exchange rate applied to the refund. For a BRL-to-BRL PIX payment, the value is normally `1.00`.
`reason`	String	`Optional`	Refund reason returned from the request.
`status`	String	`Required`	Current refund status. The creation response is normally non-final.
`createdAt`	DateTime	`Required`	Refund creation timestamp in ISO 8601 format.
`updatedAt`	DateTime	`Required`	Timestamp of the latest refund update in ISO 8601 format.
`clientReferenceTransactionId`	String	`Optional`	Merchant's refund reference returned when `clientReferenceId` was supplied.

Refund Statuses

Status	Final	Meaning
`ACCEPTED`	No	The refund request was accepted by the platform.
`REFUND_REQUESTED`	No	The refund was created and queued or submitted for processing.
`REFUNDED`	Yes	The refund completed successfully and the funds were returned to the original payment source.
`DECLINED`	Yes	The refund request was declined before successful completion.
`ERROR`	Yes	A technical or processing error prevented the refund from completing.

Webhooks

🔗
More about Payment and Refund Webhooks is available on the dedicated Webhook Overview page.

A payment webhook is sent when the PIX payment status changes. Fulfil the order only when the payment status is CAPTURED.
A refund webhook is sent when the refund reaches a webhook-triggering status. Treat the refund as successful only when the status is REFUNDED.
Webhooks may be delivered more than once. Process them idempotently using the platform transaction ID or your clientReferenceTransactionId.
If a webhook is delayed or missed, retrieve the current refund status with GET /api/v1/refunds/{id}.