Sign in

v1

latestOpenAPI 3.1.0MIT2026-07-2484155300.5 KB
Payment Request

Create PIX QR payment request

Creates the PIX QR payment request resource

post/payments/requests/pix-qr

Request body

pixQrCodestring required

Pix QR code

customerIdstring uuid

Customer identifier associated to the payment

isSandboxboolean

Indicates if this payment request should be created in sandbox mode. Default: false.

Example request

{
  "pixQrCode": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20",
  "callbackUrls": null,
  "customerId": "5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f",
  "isSandbox": false
}

Response

Create a PIX QR payment request.

idstring required

Primary identifier

amountnumber

Requested amount. For automatic pix it won't be returned

feesnumber

Fees charged for the payment request. This includes both Pluggy's fees and any customer-specific fees. Fees are calculated based on the payment method (PIX or Boleto) and the client's pricing configuration. For sandbox accounts, fees are set to 0.

descriptionstring

Payment description

status'CREATED' | 'IN_PROGRESS' | 'WAITING_PAYER_AUTHORIZATION' | 'AUTHORIZED' | 'SCHEDULED' | 'COMPLETED' | 'ERROR' | 'REFUND_IN_PROGRESS' | 'REFUNDED' | 'REFUND_ERROR' | 'EXPIRED' | 'CANCELED' required

Lifecycle of a payment request.

  • CREATED: the request was created and is waiting for a payment intent.
  • IN_PROGRESS: a payment intent is being processed by the institution.
  • WAITING_PAYER_AUTHORIZATION: the payer must authorize the payment at the institution.
  • AUTHORIZED: only for Automatic PIX. The recurring consent was authorized; individual payments will be executed under it.
  • SCHEDULED: the payment is scheduled for a future date.
  • COMPLETED: the payment was confirmed by the institution.
  • ERROR: the payment failed (see errorDetail).
  • REFUND_IN_PROGRESS: a refund was requested and is being processed.
  • REFUNDED: the refund was completed.
  • REFUND_ERROR: the refund failed.
  • EXPIRED: the request expired without being paid.
  • CANCELED: the request was canceled.
clientPaymentIdstring

Client payment identifier

createdAtstring date-time required

Date when the payment request was created

updatedAtstring date-time required

Date when the payment request was updated

paymentUrlstring required

URL to begin the payment intent creation flow for this payment request

pixQrCodestring

Pix QR code generated by the payment receiver

isSandboxboolean

Indicates if this payment request is in sandbox mode. Default: false.

Example response

{
  "id": "c2a6b7d9-3349-435d-8341-44021449ebbc",
  "amount": 150.5,
  "fees": 0.45,
  "description": "Order #4821",
  "status": "CREATED",
  "clientPaymentId": "order-4821",
  "createdAt": "2025-03-12T13:03:45.689Z",
  "updatedAt": "2025-03-12T13:03:45.689Z",
  "callbackUrls": {
    "success": "https://merchant.example.com/orders/4821/success",
    "error": "https://merchant.example.com/orders/4821/error"
  },
  "paymentUrl": "https://pay.pluggy.ai/c2a6b7d9-3349-435d-8341-44021449ebbc",
  "recipient": {
    "type": "BANK_ACCOUNT",
    "id": "5e9f8f8f-f8f8-4f8f-8f8f-8f8f8f8f8f8f",
    "name": "Conta empresa",
    "taxNumber": "12345678900",
    "isDefault": true,
    "paymentInstitution": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Banco J. Safra S.A.",
      "ispb": "03017677",
      "tradeName": "Banco Safra",
      "compe": "074",
      "createdAt": "2020-04-21T15:00:00.000Z",
      "updatedAt": "2020-04-21T15:00:00.000Z"
    },
    "account": {
      "branch": "0001",
      "number": "123456",
      "type": "CHECKING_ACCOUNT"
    },
    "pixKey": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "customer": null,
  "smartAccount": null,
  "pixQrCode": null,
  "boleto": null,
  "automaticPix": null,
  "schedule": null,
  "errorDetail": null,
  "isSandbox": false
}