Criar cobrança PIX 🇧🇷

POST /v1/payments — valores em centavos. idempotencyKey evita cobrança duplicada (reenviar a mesma chave retorna a cobrança original).

curl -X POST 'https://v2.pagnow.com/v1/payments' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{
    "amount": 1990,
    "currency": "BRL",
    "paymentMethods": ["PIX"],
    "idempotencyKey": "pedido-123",
    "customerId": "cus_abc123",
    "customerName": "João Silva",
    "customerDocument": "52998224725",
    "customerEmail": "joao@exemplo.com",
    "metadata": { "orderId": "ORD-456", "plan": "pro" },
    "items": [
      { "name": "Plano Pro", "quantity": 1, "unitPrice": 1990, "totalPrice": 1990 }
    ],
    "webhookUrl": "https://sua-loja.com/webhooks/pagnow"
  }'

import requests

resp = requests.post(
    "https://v2.pagnow.com/v1/payments",
    headers={"apikey": "pnk_sua_chave_aqui"},
    json={
        "amount": 1990,
        "currency": "BRL",
        "paymentMethods": ["PIX"],
        "idempotencyKey": "pedido-123",
        "customerId": "cus_abc123",
        "customerName": "João Silva",
        "customerDocument": "52998224725",
        "customerEmail": "joao@exemplo.com",
        "metadata": {"orderId": "ORD-456"},
        "webhookUrl": "https://sua-loja.com/webhooks/pagnow",
    },
    timeout=30,
)
resp.raise_for_status()
charge = resp.json()
print(charge["pixCopyPaste"])

<?php
$ch = curl_init("https://v2.pagnow.com/v1/payments");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["apikey: pnk_sua_chave_aqui", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 1990,
    "currency" => "BRL",
    "paymentMethods" => ["PIX"],
    "idempotencyKey" => "pedido-123",
    "customerId" => "cus_abc123",
    "customerName" => "João Silva",
    "customerDocument" => "52998224725",
    "customerEmail" => "joao@exemplo.com",
    "metadata" => ["orderId" => "ORD-456"],
    "webhookUrl" => "https://sua-loja.com/webhooks/pagnow",
  ]),
]);
$charge = json_decode(curl_exec($ch), true);
echo $charge["pixCopyPaste"];

Resposta (201)

{
  "id": "a99e3d82-352b-49b2-b10e-4551ca69446e",
  "status": "WAITING_PAYMENT",
  "amount": 1990,
  "currency": "BRL",
  "pixCopyPaste": "00020101021226...br.gov.bcb.pix...",
  "pixQrCode": "data:image/png;base64,iVBOR...",
  "pixExpiresAt": "2026-05-27T13:00:00.000Z"
}

O cliente paga com o pixQrCode (imagem) ou o pixCopyPaste. Você também pode enviá-lo para a página de checkout hospedada: https://checkout.v2.pagnow.com/{id}.

Campos principais

Campo	Tipo	Obrigatório	Notas
`amount`	int	sim	Centavos (> 0).
`currency`	string	não	Padrão `BRL`. Aceita fiat (BRL/EUR/USD) e cripto (USDT/USDC etc.). Os valores aceitos dependem da configuração do provedor na sua conta.
`paymentMethods`	string[]	sim	`PIX`, `CREDIT_CARD`, `BOLETO`, `MBWAY`, `MULTIBANCO`, `CRYPTO`, `SWAP_NOW`.
`idempotencyKey`	string	sim	Reenvio retorna a cobrança original.
`customerId`	string	não	ID do cliente no seu sistema.
`customerName`, `customerDocument`, `customerEmail`	string	recomendado	Dados do pagador. Podem ser obrigatórios dependendo do método de pagamento — recomendamos sempre enviar.
`customerPhone`	string	não	Telefone do pagador.
`metadata`	object	não	Campos livres (chave/valor) associados à cobrança.
`items`	array	não	`{ name, quantity, unitPrice, totalPrice }`.
`webhookUrl`	string	não	Recebe o `POST` de mudança de status.

Campos avançados (resolução de provedor)

Os campos abaixo são opcionais e influenciam qual conta de provedor o gateway seleciona para processar a cobrança. Na maioria dos casos não são necessários.

Campo	Tipo	Valores	Notas
`country`	string	ISO 3166-1 (2-3 letras)	País do pagador para roteamento.
`riskTier`	string	`LOW`, `MEDIUM`, `HIGH`	Nível de risco da transação.
`environment`	string	`SANDBOX`, `STAGING`, `PRODUCTION`	Força uma conta de provedor de ambiente específico. Se omitido, derivado do `NODE_ENV`.

Criar cobrança PIX 🇧🇷

Resposta (201)

Campos principais

Campos avançados (resolução de provedor)

Nesta página