Skip to main content
POST
/
payments
/
pix
Criar pagamento PIX
curl --request POST \
  --url https://dev.plugtopay.com/api/v1/payments/pix \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --data '
{
  "merchant_order_id": "ORD-PIX-2026-999",
  "amount": 5000,
  "currency": "BRL",
  "customer": {
    "name": "Maria Santos",
    "email": "maria@example.com",
    "document": "98765432100"
  }
}
'
{
  "status": "pending",
  "transaction_id": "019ddb60-6f6e-72ee-99ff-a75b60ce6d87",
  "amount": 5000,
  "payment_method": "pix",
  "pix": {
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_url": "data:image/png;base64,...",
    "qr_copy_paste": "00020126580014br.gov.bcb.pix...",
    "expiration_at": "2026-04-30T02:23:45+00:00"
  },
  "webhooks": []
}

Authorizations

​
X-Client-ID
string
header
required

Identificador público do cliente (integração servidor-a-servidor). Usado em conjunto com X-API-Key.

​
X-API-Key
string
header
required

Chave secreta de API (integração servidor-a-servidor). Usada em conjunto com X-Client-ID.

Headers

​
Idempotency-Key
string

Chave única por intenção de pagamento (tipicamente o ID do pedido). Reenviar a mesma requisição com a mesma chave nunca resulta em cobrança duplicada. Escopada por empresa.

Example:

"ORD-2026-12345"

Body

application/json

Corpo da criação de pagamento PIX. O payment_method é injetado automaticamente pelo backend.

​
merchant_order_id
string
required

ID do pedido no seu sistema.

Example:

"ORD-PIX-2026-999"

​
amount
integer
required

Valor total, em centavos.

Example:

5000

​
currency
string
required

Código ISO 4217.

Example:

"BRL"

​
customer
object
required

Dados do cliente pagador.

Response

Cobrança PIX criada.

Resposta da criação de pagamento PIX.

​
status
enum<string>
required

Estado do pagamento na resposta HTTP. processing é transitório, retornado apenas no 202 enquanto a resolução assíncrona está em andamento.

Available options:
pending,
approved,
failed,
refunded,
processing
Example:

"approved"

​
transaction_id
string<uuid> | null
required
Example:

"019ddb60-6f6e-72ee-99ff-a75b60ce6d87"

​
amount
integer | null
required

Valor, em centavos.

Example:

5000

​
payment_method
enum<string>
required
Available options:
pix
Example:

"pix"

​
pix
object
required

Dados do QR PIX. Contém tudo que é necessário para renderizar o QR ao cliente.

​
webhooks
object[]
required