# Pix
source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/a2a/pix/index.md

Pix is Brazil's national instant payment system, created and operated by the Central Bank of Brazil - Banco Central do Brasil (BCB). Pix enables fast, secure, real time account to account (A2A) transfers in Brazilian Real (BRL). Payments are processed within seconds and are available 24×7×365.

Pix does not require traditional bank account identifiers, such as International Bank Account Number (IBANs). Instead, customers initiate payments using Pix keys (aliases) or QR codes, delivering a simple and frictionless payment experience.

Pix is widely used by merchants across Brazil to accept payments through static or dynamic QR codes. Customers complete transactions by scanning the QR codes using their banking applications, enabling fast and seamless payments.

Through integration between the Mastercard Gateway platform and Pix, merchants can accept digital payments efficiently using Pix QR codes.

For more information, refer to [Pix](https://www.bcb.gov.br/en/financialstability/pix_en).

## Prerequisites {#prerequisites}

To offer the Pix payment method through the Mastercard Gateway, merchant must:

* Register with a supported payment method service provider to offer Pix payments.
* Register an online merchant for Pix payments through through the payment service provider.
* Configure your merchant profile in Mastercard Gateway Merchant Manager (MM) to enable Pix as an accepted payment method.

## Pix QR payer journey flow {#pix-qr-payer-journey-flow}

The following stages describe the Pix QR payer journey:

1. The payer selects goods or services on the merchant's app or website and proceeds to checkout.
2. On the checkout page, the payer reviews the order details, provides personal information if required, and selects Pix QR as the payment method.
3. The system redirects the payer to a payment page that displays a dedicated QR code.
4. The payer scans the QR code or pastes the Pix code into a supported banking app and authorizes the payment.
5. The payer returns to the merchant site. The merchant confirms the transaction status by using Retrieve Transaction or webhooks.

Figure: Pix QR payment transaction flow

This diagram illustrates the transaction flow for a Pix QR payment.
![Pix QR payment transaction flow](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/pix.png)

Figure: Pix QR Code

This diagram illustrates the QR code used in an Pix payment.
![Pix QR Code](https://static.developer.mastercard.com/content/mastercard-gateway/uploads/pix_qr_code.png)

## Pix QR Payments integration {#pix-qr-payments-integration}

### Pix QR Payments through Direct Payment {#pix-qr-payments-through-direct-payment}

This section provides an overview of how to support Pix QR Code payments using Direct Payment integration.

* Direct Payment integration enables you to offer Pix QR payment on your checkout page.
* Pix QR payments are supported from WS API version 100 and later.
* Submit an Initiate Browser Payment request where **sourceOfFunds.browserPayment.type = PIX_QR** and **browserPayment.operation = PAY.**

### Pix QR payments transactions {#pix-qr-payments-transactions}

This table shows the Pix QR transaction characteristics.

|     Transaction details     |                          Value                           |
|-----------------------------|----------------------------------------------------------|
| Payment type                | QR Code                                                  |
| Supported countries         | Brazil (BRA)                                             |
| Supported currencies        | BRL                                                      |
| Supported operations        | Purchase (PAY), Partial Refund, Refund                   |
| Minimum transaction amount  | Depends on merchant configuration                        |
| Maximum transaction amount  | Depends on merchant configuration                        |
| Refund validity             | Pix QR refunds are initiated according to acquirer rules |
| Chargeback                  | Not applicable                                           |
| Transaction validity period | 120 seconds                                              |

### Payment options inquiry (POI) {#payment-options-inquiry-poi}

```bash
curl --request POST \
  --url {{remotehost}}/rest/version/llaatteesstt/merchant/{{merchant_name}}/paymentOptionsInquiry \
  --header 'Content-Type: application/json'
```

```json
{
  "merchant": "PAYAIR_MER_3",
  "paymentTypes": {
    "browserPayment": [
      {
        "currencies": [
          {
            "currency": "BRL"
          }
        ],
        "description": "Pix is Brazil's instant payment system, governed by the Central Bank, enabling 24/7 free transfers.",
        "displayName": "Pix",
        "logoUrl": "{{remotehost}}/bpui/bp/logo/117c6b66-f63e-43fb-8d78-26951bb9e03d_PIX_QR.svg",
        "maxAmount": 10000,
        "minAmount": 1,
        "supportedCountries": [
          {
            "country": "BRA"
          }
        ],
        "type": "PIX_QR"
      }
    ]
  },
  "result": "SUCCESS",
  "supportedPaymentOperations": [
    {
      "supportedPaymentOperation": "PURCHASE"
    }
  ]
}
```

### Initiate browser payment {#initiate-browser-payment}

```bash
curl --request PUT \
  --url "{{remotehost}}/rest/version/latest/merchant/{{merchant_name}}/order/{{order_id}}/transaction/{{transaction_id}}" \
  --header "Authorization: Basic bWVyY2hhbnQuUEFZQUlSX01FUl8zOjI3YTQ5ZTkwMTJkOWEwYTdhNmUzYzcyYmI2NWMyMzhm" \
  --header "Content-Type: application/json" \
  --data '{
    "apiOperation": "INITIATE_BROWSER_PAYMENT",
    "billing": {
      "address": {
        "city": "Brisbane",
        "company": "Payment Gateway",
        "country": "BRA",
        "stateProvince": "Queensland",
        "postcodeZip": "ERT",
        "street": "OceanPoint",
        "street2": "OceanDrive"
      }
    },
    "shipping": {
      "address": {
        "city": "Brisbane",
        "company": "Payment Gateway",
        "country": "BRA",
        "stateProvince": "Queensland",
        "postcodeZip": "ERT",
        "street": "OceanPoint",
        "street2": "OceanDrive"
      }
    },
    "browserPayment": {
      "operation": "PAY",
      "returnUrl": "{{remotehost}}/documentation/integrationGuidelines/index.html"
    },
    "customer": {
      "account": {
        "id": "customerAccount"
      },
      "dateOfBirth": "1999-12-31",
      "email": "<Email ID>",
      "firstName": "Akash",
      "lastName": "Mali",
      "mobilePhone": "0779xxxx555",
      "nationalId": "nationalId1",
      "phone": "98XXXXX898"
    },
    "order": {
      "reference": "TEST-SUCCEED",
      "amount": "100.00",
      "currency": "BRL",
      "description": "apmspi test order"
    },
    "sourceOfFunds": {
      "type": "BROWSER_PAYMENT",
      "browserPayment": {
        "type": "PIX_QR",
        "additionalPayerData": {}
      }
    }
  }'
```

```json
{
  "billing": {
    "address": {
      "city": "Brisbane",
      "company": "Payment Gateway",
      "country": "BRA",
      "postcodeZip": "ERT",
      "stateProvince": "Queensland",
      "street": "OceanPoint",
      "street2": "OceanDrive"
    }
  },
  "browserPayment": {
    "interaction": {
      "status": "INITIATED",
      "timeInitiated": "2026-02-26T13:24:37.064Z"
    },
    "operation": "PAY",
    "redirectHtml": "<div id=\"initiateRedirect\" xmlns=\"http://www.w3.org/1999/html\"><iframe srcdoc=\"<script type='application/javascript'>(function(){window.top.location.href='https://au-poc-tf-qa-nonmtls.aws-payair.com/apm-rede/pix/bfb96f81b65babd2c5f72f3b2d6490f1?lang=en-US';})();</script>\" id=\"redirectFrame\" name=\"redirectFrame\" height=\"100%\" width=\"100%\"></iframe&gt;</div>",
    "returnUrl": "{{remotehost}}/documentation/integrationGuidelines/index.html"
  },
  "customer": {
    "account": {
      "id": "customerAccount"
    },
    "email": "<Email ID>",
    "firstName": "Akash",
    "lastName": "Mali",
    "mobilePhone": "0779xxxx555",
    "nationalId": "nationalId1",
    "phone": "98XXXXX898"
  },
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "merchant": "PAYAIR_MER_3",
  "order": {
    "amount": 100,
    "chargeback": {
      "amount": 0,
      "currency": "BRL"
    },
    "creationTime": "2026-02-26T13:24:37.009Z",
    "currency": "BRL",
    "description": "apmspi test order",
    "id": "3323034941",
    "lastUpdatedTime": "2026-02-26T13:24:38.150Z",
    "merchantAmount": 100,
    "merchantCurrency": "BRL",
    "reference": "TEST-SUCCEED",
    "status": "INITIATED",
    "totalAuthorizedAmount": 0,
    "totalCapturedAmount": 0,
    "totalDisbursedAmount": 0,
    "totalRefundedAmount": 0
  },
  "response": {
    "acquirerCode": "ACCEPTED",
    "gatewayCode": "SUBMITTED",
    "gatewayRecommendation": "NO_ACTION"
  },
  "result": "SUCCESS",
  "shipping": {
    "address": {
      "city": "Brisbane",
      "company": "Payment Gateway",
      "country": "BRA",
      "postcodeZip": "ERT",
      "stateProvince": "Queensland",
      "street": "OceanPoint",
      "street2": "OceanDrive"
    }
  },
  "sourceOfFunds": {
    "browserPayment": {
      "type": "PIX_QR"
    },
    "type": "BROWSER_PAYMENT"
  },
  "timeOfLastUpdate": "2026-02-26T13:24:38.150Z",
  "timeOfRecord": "2026-02-26T13:24:37.061Z",
  "transaction": {
    "acquirer": {
      "id": "ACQ1_PIX",
      "merchantId": "98860936"
    },
    "amount": 100,
    "currency": "BRL",
    "id": "6083075583",
    "source": "INTERNET",
    "stan": "0",
    "type": "PAYMENT"
  },
  "version": "100"
}
```

### Refund {#refund}

```bash
curl --request PUT \
  --url "{{remotehost}}/api/rest/version/latest/merchant/{{merchant_id}}/order/{{order_id}}/transaction/{{transaction_id}}" \
  --header "Accept-Language: en-US" \
  --header "Content-Type: application/json" \
  --data '{
    "apiOperation": "REFUND",
    "transaction": {
      "amount": "10.00",
      "currency": "BRL"
    }
  }'
```

```json
{
  "browserPayment": {
    "interaction": {
      "status": "COMPLETED",
      "timeCompleted": "2026-06-10T13:03:50.409Z",
      "timeInitiated": "2026-06-10T13:02:44.853Z"
    },
    "operation": "PAY",
    "redirectHtml": "<div id=\"initiateRedirect\" xmlns=\"http://www.w3.org/1999/html\"><iframe srcdoc=\"<script type='application/javascript'>(function(){window.top.location.href='https://au-poc-tf-qa-nonmtls.aws-payair.com/apm-pix/pix/98df33443659b9df9fe14a1f2af47b26?lang=en-US';})();</script>\" id=\"redirectFrame\" name=\"redirectFrame\" height=\"100%\" width=\"100%\"></iframe></div>",
    "returnUrl": "{{remotehost}}/api/documentation/integrationGuidelines/index.html"
  },
  "customer": {
    "account": {
      "id": "customerAccount"
    },
    "email": "<Email ID>",
    "mobilePhone": "07792555555"
  },
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "merchant": "PAYAIR_MER_2",
  "order": {
    "amount": 10,
    "chargeback": {
      "amount": 0,
      "currency": "BRL"
    },
    "creationTime": "2026-06-10T13:02:44.777Z",
    "currency": "BRL",
    "id": "6991584061",
    "lastUpdatedTime": "2026-06-10T13:06:08.652Z",
    "merchantAmount": 10,
    "merchantCurrency": "BRL",
    "reference": "TEST-SUCCEED",
    "status": "REFUNDED",
    "totalAuthorizedAmount": 10,
    "totalCapturedAmount": 10,
    "totalDisbursedAmount": 0,
    "totalRefundedAmount": 10
  },
  "response": {
    "acquirerCode": "APPROVED",
    "gatewayCode": "APPROVED"
  },
  "result": "SUCCESS",
  "sourceOfFunds": {
    "browserPayment": {
      "type": "PIX_QR"
    },
    "type": "BROWSER_PAYMENT"
  },
  "timeOfLastUpdate": "2026-06-10T13:06:08.652Z",
  "timeOfRecord": "2026-06-10T13:06:05.452Z",
  "transaction": {
    "acquirer": {
      "id": "REDE_PIX_ACQ",
      "merchantId": "98860936"
    },
    "amount": 10,
    "currency": "BRL",
    "id": "6787603543",
    "source": "INTERNET",
    "stan": "0",
    "type": "REFUND"
  },
  "version": "100"
}
```

### Retrieve order {#retrieve-order}

```bash
curl --request GET \ 
   --url {{remotehost}}/api/rest/version/llaatteesstt/merchant/{{merchant_id}}/order/{{order_id}} \
```

```json
{
  "amount": 10,
  "billing": {
    "address": {
      "city": "Edinburgh",
      "company": "Payment Gateway",
      "country": "BRA",
      "postcodeZip": "2000",
      "stateProvince": "Scotland",
      "street": "OceanPoint",
      "street2": "OceanDrive"
    }
  },
  "chargeback": {
    "amount": 0,
    "currency": "BRL"
  },
  "creationTime": "2026-06-10T13:02:44.777Z",
  "currency": "BRL",
  "customer": {
    "account": {
      "id": "customerAccount"
    },
    "email": "<Email ID>",
    "firstName": "Akash",
    "lastName": "Mali",
    "mobilePhone": "07792555555",
    "nationalId": "nationalId1",
    "phone": "9898989898"
  },
  "description": "apmspi test order",
  "id": "6991584061",
  "lastUpdatedTime": "2026-06-10T13:03:50.427Z",
  "merchant": "PAYAIR_MER_2",
  "merchantAmount": 10,
  "merchantCurrency": "BRL",
  "reference": "TEST-SUCCEED",
  "result": "SUCCESS",
  "shipping": {
    "address": {
      "city": "Edinburgh",
      "company": "Payment Gateway",
      "country": "ZAF",
      "postcodeZip": "2000",
      "stateProvince": "Scotland",
      "street": "OceanPoint",
      "street2": "OceanDrive"
    }
  },
  "sourceOfFunds": {
    "browserPayment": {
      "type": "PIX_QR"
    },
    "type": "BROWSER_PAYMENT"
  },
  "status": "CAPTURED",
  "totalAuthorizedAmount": 10,
  "totalCapturedAmount": 10,
  "totalDisbursedAmount": 0,
  "totalRefundedAmount": 0,
  "transaction": [
    {
      "billing": {
        "address": {
          "city": "Edinburgh",
          "company": "Payment Gateway",
          "country": "BRA",
          "postcodeZip": "2000",
          "stateProvince": "Scotland",
          "street": "OceanPoint",
          "street2": "OceanDrive"
        }
      },
      "browserPayment": {
        "interaction": {
          "status": "COMPLETED",
          "timeCompleted": "2026-06-10T13:03:50.409Z",
          "timeInitiated": "2026-06-10T13:02:44.853Z"
        },
        "operation": "PAY",
        "redirectHtml": "<div id=\"initiateRedirect\" xmlns=\"http://www.w3.org/1999/html\"><iframe srcdoc=\"<script type='application/javascript'>(function(){window.top.location.href='https://au-poc-tf-qa-nonmtls.aws-payair.com/apm-pix/pix/98df33443659b9df9fe14a1f2af47b26?lang=en-US';})();</script>\" id=\"redirectFrame\" name=\"redirectFrame\" height=\"100%\" width=\"100%\"></iframe></div>",
        "returnUrl": "{{remotehost}}/api/documentation/integrationGuidelines/index.html"
      },
      "customer": {
        "account": {
          "id": "customerAccount"
        },
        "email": "<Email ID>",
        "firstName": "Akash",
        "lastName": "Mali",
        "mobilePhone": "07792555555",
        "nationalId": "nationalId1",
        "phone": "9898989898"
      },
      "gatewayEntryPoint": "WEB_SERVICES_API",
      "merchant": "PAYAIR_MER_2",
      "order": {
        "amount": 10,
        "chargeback": {
          "amount": 0,
          "currency": "BRL"
        },
        "creationTime": "2026-06-10T13:02:44.777Z",
        "currency": "BRL",
        "description": "apmspi test order",
        "id": "6991584061",
        "lastUpdatedTime": "2026-06-10T13:03:50.427Z",
        "merchantAmount": 10,
        "merchantCurrency": "BRL",
        "reference": "TEST-SUCCEED",
        "status": "CAPTURED",
        "totalAuthorizedAmount": 10,
        "totalCapturedAmount": 10,
        "totalDisbursedAmount": 0,
        "totalRefundedAmount": 0
      },
      "response": {
        "gatewayCode": "APPROVED",
        "gatewayRecommendation": "NO_ACTION"
      },
      "result": "SUCCESS",
      "shipping": {
        "address": {
          "city": "Edinburgh",
          "company": "Payment Gateway",
          "country": "ZAF",
          "postcodeZip": "2000",
          "stateProvince": "Scotland",
          "street": "OceanPoint",
          "street2": "OceanDrive"
        }
      },
      "sourceOfFunds": {
        "browserPayment": {
          "type": "PIX_QR"
        },
        "type": "BROWSER_PAYMENT"
      },
      "timeOfLastUpdate": "2026-06-10T13:03:50.427Z",
      "timeOfRecord": "2026-06-10T13:02:44.841Z",
      "transaction": {
        "acquirer": {
          "id": "REDE_PIX_ACQ",
          "merchantId": "98860936"
        },
        "amount": 10,
        "currency": "BRL",
        "id": "5828038423",
        "source": "INTERNET",
        "stan": "0",
        "type": "PAYMENT"
      },
      "version": "100"
    }
  ]
}
```

## Interpretation of the Transaction result {#interpretation-of-the-transaction-result}

This table shows the transaction response codes for the possible scenarios that you may encounter after initiating the Pix QR payments.

|           Initiate browser payment response           |                                      What this means                                      |
|-------------------------------------------------------|-------------------------------------------------------------------------------------------|
| `response.gatewayCode = SUBMITTED` `result = SUCCESS` | Redirect the payer using the returnUrl provided in the Initiate Browser Payment response. |

|                Retrieve transaction or retrieve order response                |                                                                                                          What this means                                                                                                          |
|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `response.gatewayCode = APPROVED` `result = SUCCESS`                          | The payment is successful.                                                                                                                                                                                                        |
| `response.gatewayCode = PENDING` `result = PENDING`                           | The Mastercard Gateway is waiting for a confirmation from the acquirer. Retry RETRIEVE_TRANSACTION or use webhooks.                                                                                                               |
| `response.gatewayCode = CANCELLED` `result = FAILURE`                         | The payer cancelled the payment. Offer an alternative payment method.                                                                                                                                                             |
| `response.gatewayCode = DECLINED or ACQUIRER_SYSTEM_ERROR` `result = FAILURE` | The payment was declined. Offer the payer the option to try another payment method. In the case of an ACQUIRER_SYSTEM_ERROR, you may inquire with the acquirer for the reason for payment failure, or retry RETRIEVE_TRANSACTION. |
| `response.gatewayCode = TIMED_OUT` `result = FAILURE`                         | Treat as declined. The Mastercard Gateway will attempt to ensure the transaction is not successful or will revert the transaction.                                                                                                |

## Pix QR payment through Hosted Checkout {#pix-qr-payment-through-hosted-checkout}

Hosted Checkout integration allows you to collect payment details from your payer through an interaction that the gateway hosts and displays.

From the API version 100 and later, Pix QR payment is automatically available as a payment method once your payment service provider enables and configures you for this payment method.
For more information, see [Browser Payments through Hosted Checkout integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/imp-brow-pay-int/index.md#browser-payments-through-hosted-checkout-integration).

## Webhook notifications {#webhook-notifications}

If you subscribed to Mastercard Gateway [Webhook notification](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/webhook-noti/index.md) , you receive additional notifications on the paymentStatus.