Documentation

Create a PIX Transaction (Instant Payment Brazil)

Suggest Edits

This guide explains how to process payments via PIX using the PagSeguro Direct API.

PIX is Brazil’s instant payment system operated by the Central Bank of Brazil, allowing real-time fund transfers using QR codes or payment keys.
This integration enables merchants to generate dynamic PIX QR codes for instant customer payments, with real-time confirmation through asynchronous notifications.

Endpoint

POST /v3/transactions

Headers

  • Authorization: Bearer {access_token}
  • Content-Type: application/json

Step 1: Make a Request

{
  "integration": {
    "reference": "REF-BR-987654321",
    "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
    "language": "pt_BR"
  },
  "order": {
    "currency": "BRL",
    "items": [
      {
        "quantity": 1,
        "description": "Assinatura mensal",
        "unit_price": 59.90
      }
    ]
  },
  "charge": {
    "country": "BR",
    "method": "PIX"
  },
  "payer": {
    "email": "[email protected]",
    "ip": "189.204.23.121",
    "person": {
      "name": "João da Silva",
      "birth_date": "1985-03-10",
      "document": {
        "type": "CPF",
        "number": "12345678909"
      },
      "phone": {
        "country_code": "55",
        "number": "11987654321"
      }
    }
  }
}

Key Fields

FieldRequiredDescription
charge.methodyes"PIX" (instant payment)
charge.countryyes"BR" (Brazil)
order.currencyyes"BRL"
integration.referenceyesUnique merchant transaction reference.
integration.notification_urlyesWebhook URL for transaction status updates.
payer.person.document.typeyes"CPF" (Brazilian taxpayer ID)
payer.person.document.numberyesCustomer CPF number.
integration.languageyesDefines the language used in the integration and in transaction-related communications, such as messages, checkout screens, and notifications.
It must follow the ISO language code standard, for example: ptBR, en-US.
order.items.quantityyesQuantity of units of the item included in the order.
Only accepts positive integers greater than zero.
order.items.descriptionyesDescription of the item or service.
order.items.unit_priceyesUnit price of the item, expressed in the transaction currency and with up to two decimal places.
payer.emailyesPayer's email address.
payer.ipyesIP address of the device used by the payer at the time of the transaction.
payer.person.nameyesFull name of the payer, as it appears on the official document.
payer.person.phone.country_codeno--
payer.person.phone_numberno--

Step 2: Processing the API Response

On success (HTTP 200), you’ll receive:

{
  "code": "25a58ef1-3755-476b-b2f6-e445b170a849",
  "reference": "REF-BR-987654321",
  "status": "PENDING",
  "amount": 59.90,
  "currency": "BRL",
  "country": "BR",
  "created_at": "2025-05-05T21:00:00Z",
  "payment_instructions": {
    "interaction_type": [
      "CODE"
    ],
    "code": {
      "type": "QR_CODE",
      "value": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d3-a456-42665544000005204000053039865802BR5913MERCHANT_NAME6008BRASILIA61087040020062070503***6304A1B2",
      "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51AAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4xLjAsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+17YcXAAAMrklEQVR4nO3dX2jcZx3H8c/MZrZz...",
      "reference": "0136123e4567-e12b-12d3-a456-42665544"
    }
  }
}

Response Details

FieldDescription
codeTransaction ID generated by PagSeguro.
statusPENDING
amountTransaction amount in BRL.
currency"BRL" (Brazilian Real)
payment_instructions.code.type"QR_CODE"
payment_instructions.code.valueCopy-and-paste string for PIX payment.
payment_instructions.code.imageBase64 of the PIX payment QR Code image.
payment_instructions.code.referenceUnique PIX transaction reference.
expires_atExpiration time for the PIX QR code.

Payment Flow

  1. The merchant creates a PIX transaction using the /v3/transactions endpoint.
  2. PagSeguro returns the PIX QR code payload and reference data.
  3. The merchant displays the QR code to the customer.
  4. The customer scans it using their banking or wallet app to complete payment.
  5. The payment is processed instantly, and PagSeguro confirms via webhook.

Possible Status Values

Transaction Status Description

📘

Reason Codes

If the request fails, the API will return an HTTP status code other than 200. The response body will include an errors array with descriptive messages and corresponding error codes.

For the full list of possible error codes, see the Reason Codes reference.

Step 3: Handling Transaction Status

The status field in the response indicates the transaction state. You can monitor status updates using the notification_url or by querying the transaction status.

Updated about 9 hours ago