Referência da API

Criar transação

Cria uma nova transação de entrada. Para pagamentos PIX, retorna um BR Code copia-e-cola que seu cliente paga por qualquer app de banco. Para cartão de crédito, a transação é autorizada e capturada de forma síncrona.

POST/transactions/v2/purchase

Restrinja quem pode pagar

restrictPayerDocument Defina como true para travar a transação ao CPF/CNPJ informado em `cpf`. Se outra pessoa tentar pagar, o banco rejeita o PIX. Essa é a defesa mais forte contra fraude de roteamento de pagamento, onde um atacante paga por um terceiro e depois contesta a cobrança.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

namestringobrigatório

Nome completo do pagador (máximo 255 caracteres).

Exemplo: João Silva

emailstringobrigatório

E-mail válido do pagador. Usado para comprovantes e notificações ao cliente.

Exemplo: joaosilva@exemplo.com

cpfstringobrigatório

CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, apenas números. Sem máscara.

Exemplo: 12345678901

phonestringobrigatório

Telefone do pagador, 8 a 12 dígitos numéricos.

Exemplo: 9876543210

amountnumberobrigatório

Valor da transação em centavos. R$ 10,00 = 1000. R$ 0,01 = 1. Não há mínimo, mas valores muito baixos podem ser rejeitados pela instituição recebedora.

Exemplo: 1000

descriptionstringobrigatório

Descrição curta da transação que aparece no comprovante e no extrato bancário do pagador.

Exemplo: Assinatura Pro

responsibleDocumentstringobrigatório

CPF ou CNPJ da parte legal do seu negócio responsável por essa cobrança.

Exemplo: 12345678901

responsibleExternalIdstringobrigatório

ID interno do responsável no seu sistema (ex: ID do vendedor, ID da conta).

Exemplo: user-1234

paymentMethod'PIX' | 'CREDIT_CARD'obrigatório

Método de pagamento. PIX retorna uma string BR Code copia-e-cola; o cliente paga de forma assíncrona e nós enviamos um webhook na confirmação. CREDIT_CARD autoriza de forma síncrona.

Exemplo: PIX

currency'BRL' | 'MXN'opcional

Código da moeda. Padrão BRL.

Exemplo: BRL

externalIdstringopcional

Sua referência para essa transação. Retornada em `GET /transactions/:id?searchBy=externalId` e em todo webhook vinculado a essa transação. Use como sua chave de join.

Exemplo: pedido-5678

referrerUrlstringopcional

URL da página de origem dessa transação.

Exemplo: https://exemplo.com/checkout

checkoutUrlstringopcional

URL da sua página de checkout hospedada, se aplicável.

Exemplo: https://exemplo.com/pagar/pedido-5678

postbackUrlstringopcional

URL de webhook para eventos dessa transação. Se omitido, usa a URL de webhook global configurada no dashboard.

Exemplo: https://seu-dominio.com/webhook

fingerPrintstringopcional

Device fingerprint do seu SDK de antifraude. Opcional para PIX, fortemente recomendado para CREDIT_CARD.

Exemplo: 174859385

restrictPayerDocumentbooleanopcional

Quando true, apenas o titular do `cpf` informado pode pagar essa transação. Pagamentos de qualquer outro CPF/CNPJ são rejeitados pela instituição recebedora.

Exemplo: true

creditCardobjectopcional

Obrigatório quando paymentMethod é CREDIT_CARD. Campos do objeto: • number (string): PAN do cartão • holder (string): nome impresso no cartão • expMonth (string): MM • expYear (string): AAAA • cvv (string): código de segurança • installments (number): 1-12

Exemplo: { "number": "4111411141114111", "holder": "João Silva", "expMonth": "04", "expYear": "2027", "cvv": "324", "installments": 1 }

Body da requisição

Content-Type: application/json

JSON

// Exemplo PIX
{
  "name": "João Silva",
  "email": "joaosilva@exemplo.com",
  "cpf": "12345678901",
  "phone": "9876543210",
  "amount": 1000,
  "description": "Assinatura Pro",
  "responsibleDocument": "12345678901",
  "responsibleExternalId": "user-1234",
  "externalId": "pedido-5678",
  "postbackUrl": "https://seu-dominio.com/webhook",
  "paymentMethod": "PIX",
  "currency": "BRL"
}

// Exemplo cartão de crédito
{
  "name": "João Silva",
  "email": "joaosilva@exemplo.com",
  "cpf": "12345678901",
  "phone": "9876543210",
  "amount": 1000,
  "description": "Assinatura Pro",
  "responsibleDocument": "12345678901",
  "responsibleExternalId": "user-1234",
  "externalId": "pedido-5678",
  "postbackUrl": "https://seu-dominio.com/webhook",
  "paymentMethod": "CREDIT_CARD",
  "currency": "BRL",
  "fingerPrint": "174859385",
  "creditCard": {
    "number": "4111411141114111",
    "holder": "João Silva",
    "expMonth": "04",
    "expYear": "2027",
    "cvv": "324",
    "installments": 1
  }
}

Respostas

201

Transação criada. Para PIX, pixCode é o BR Code para exibir ao seu cliente. Para CREDIT_CARD, a transação já está em APPROVED ou REJECTED.

JSON

{
  "id": 1234567,
  "method": "PIX",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 1000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "pixCode": "00020126580014br.gov.bcb.pix...6304B0D2",
  "createdAt": "2026-04-08T14:32:01.923Z",
  "expiresAt": "2026-04-08T15:32:01.923Z",
  "fingerPrint": null,
  "description": "Assinatura Pro"
}

400

Erro de validação. O campo message descreve qual(is) campo(s) falharam.

JSON

{
  "statusCode": 400,
  "message": "The 'email' field must be a valid email address.",
  "error": "Bad Request"
}

401

API key inválida ou ausente.

JSON

{ "statusCode": 401, "message": "Unauthorized" }

403

API key sem a permissão createTransaction.

JSON

{
  "statusCode": 403,
  "message": "You do not have permission to access this resource"
}

Exemplos

cURL

curl -X POST "https://api.pagnovo.com/transactions/v2/purchase" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joaosilva@exemplo.com",
    "cpf": "12345678901",
    "phone": "9876543210",
    "amount": 1000,
    "description": "Assinatura Pro",
    "responsibleDocument": "12345678901",
    "responsibleExternalId": "user-1234",
    "externalId": "pedido-5678",
    "postbackUrl": "https://seu-dominio.com/webhook",
    "paymentMethod": "PIX",
    "currency": "BRL"
  }'

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");

const res = await fetch("https://api.pagnovo.com/transactions/v2/purchase", {
  method: "POST",
  headers: {
    Authorization: `Basic ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "João Silva",
    email: "joaosilva@exemplo.com",
    cpf: "12345678901",
    phone: "9876543210",
    amount: 1000,
    description: "Assinatura Pro",
    responsibleDocument: "12345678901",
    responsibleExternalId: "user-1234",
    externalId: "pedido-5678",
    postbackUrl: "https://seu-dominio.com/webhook",
    paymentMethod: "PIX",
    currency: "BRL",
  }),
});

const traceId = res.headers.get("x-trace-id");
console.log("trace:", traceId);

if (!res.ok) {
  const err = await res.json();
  throw new Error(`${err.message} (trace: ${traceId})`);
}

const tx = await res.json();
console.log("Código PIX:", tx.pixCode);

Python

import base64, json, os, requests

token = base64.b64encode(
    f"secret:{os.environ['PAGNOVO_SECRET_KEY']}".encode()
).decode()

res = requests.post(
    "https://api.pagnovo.com/transactions/v2/purchase",
    headers={
        "Authorization": f"Basic {token}",
        "Content-Type": "application/json",
    },
    json={
        "name": "João Silva",
        "email": "joaosilva@exemplo.com",
        "cpf": "12345678901",
        "phone": "9876543210",
        "amount": 1000,
        "description": "Assinatura Pro",
        "responsibleDocument": "12345678901",
        "responsibleExternalId": "user-1234",
        "externalId": "pedido-5678",
        "postbackUrl": "https://seu-dominio.com/webhook",
        "paymentMethod": "PIX",
        "currency": "BRL",
    },
)

print("trace:", res.headers.get("x-trace-id"))
res.raise_for_status()
tx = res.json()
print("Código PIX:", tx["pixCode"])