Guia de Início Rápido

Bem-vindo à documentação da API da PinguPag. Siga estes passos para começar a integrar nossa API de pagamentos PIX em sua aplicação.

1. Crie sua Conta de Loja: Entre em contato com o administrador da plataforma para criar sua conta. Você receberá um e-mail e uma senha para acessar o seu portal de cliente.
2. Obtenha sua Chave Secreta: Faça login no seu portal, vá para a aba "Configurações e API" e copie sua Chave Secreta (Secret Key).
3. Autentique suas Requisições: Para toda chamada à API, inclua sua Chave Secreta no cabeçalho HTTP X-API-Key.
4. Crie sua Primeira Transação: Use o endpoint POST /gateway/v1/transaction para gerar sua primeira cobrança PIX.
5. Receba Notificações: Configure uma URL de Webhook no seu portal para ser notificado em tempo real sobre as mudanças de status.

Autenticação

A autenticação é feita via API Key. Envie sua Chave Secreta no cabeçalho X-API-Key em todas as requisições. Requisições sem uma chave válida retornarão um erro 401 Unauthorized.

Exemplo de Requisição Autenticada (cURL)

curl --location 'https://pagamento-processador.org.ua/gateway/v1/transaction' \
--header 'X-API-Key: pingupag_' \
--header 'Content-Type: application/json' \
--data-raw '{ ... }'

Recurso: Transações

O recurso de transações é o principal da API, permitindo a criação e consulta de pagamentos.

Criar Transação

POST

Este endpoint cria uma nova transação. Atualmente, apenas o método de pagamento pix é suportado.

Atributos do Objeto transaction (Envio)

Atributos do Objeto tracking (Opcional)

Envie este objeto para rastrear a origem de suas vendas.

Atributos do Objeto splits (Opcional)

Envie este campo para dividir o valor da venda entre múltiplos recebedores (coprodutores, parceiros, etc.). A taxa da plataforma será descontada integralmente da conta principal que está realizando a transação.

Cada objeto dentro do array splits deve conter:

Atributos do Objeto customer (Envio)

Atributos do Objeto address (Envio de Endereço)

Envie este objeto para especificar o endereço de cobrança ou entrega do cliente. Aceito na raiz do JSON como address ou dentro de customer.address. Ideal para e-commerces, produtos físicos e enriquecimento antifraude.

Exemplo de Requisição Completa para Gerar PIX (cURL)

curl --location 'https://pagamento-processador.org.ua/gateway/v1/transaction' \
--header 'X-API-Key: pingupag_' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 1000,
    "description": "Produto Exemplo Premium",
    "reference": "PEDIDO-2026-99881",
    "postback_url": "https://meusite.com.br/webhooks/gateway",
    "source": "api_externa",
    "customer": {
        "name": "João da Silva",
        "email": "joao.silva@exemplo.com",
        "phone": "11999998888",
        "document": "01234567890"
    },
    "address": {
        "street": "Avenida Paulista",
        "number": "1000",
        "complement": "Apto 101, Bloco B",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "zipcode": "01310-100"
    },
    "orderbump": [
        "ob_hash_da_oferta_1"
    ],
    "tracking": {
        "utm_source": "meta",
        "utm_campaign": "campanha_vendas_2026",
        "utm_medium": "cpc",
        "utm_content": "anuncio_video_01",
        "utm_term": "feed_instagram",
        "src": "src_rastreamento",
        "sck": "sck_rastreamento"
    },
    "splits": [
        {
            "recipientId": "store_abcdef123456",
            "amount": 200
        }
    ]
}'

Exemplo de Resposta (Sucesso)

{
    "status": "success",
    "transaction_id": 238,
    "id": "PED123-CLIENTE456",
    "qr_code": "00020126...6304ABCD",
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgo...",
    "amount": 1000,
    "acquirer": "Adquirente",
    "attempts": 1,
    "expires_at": "2025-08-22 21:30:00"
}

Consultar Transação por ID

GET

Busca os detalhes completos de uma única transação usando o ID interno da plataforma.

Atributos do Objeto de Resposta

Exemplo de Resposta (Sucesso)

{
    "id": "iupJA3D4U82",
    "external_id": "LOJA-TESTE-1755739430",
    "status": "pending",
    "amount": 200,
    "created_at": "2025-08-21 22:23:53",
    "updated_at": "2025-08-21 22:23:53",
    "customer_data": { ... },
    "attempts_data": [ ... ],
    "amount_in_reais": "2,00"
}

Recurso: Pix Recorrente (Assinaturas)

A API de Pix Recorrente permite criar assinaturas e cobranças automáticas híbridas via Pix (Jornada 2 e Jornada 3).

Criar Assinatura

POST

Este endpoint cria uma nova assinatura Pix. É gerada uma cobrança imediata da primeira parcela e configurada a recorrência automaticamente.

Parâmetros de Envio

Exemplo de Requisição (POST)

curl --location 'https://pagamento-processador.org.ua/gateway/v1/pix_recurring.php' \
--header 'X-API-Key: pingupag_' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 9990,
    "periodicity": "MENSAL",
    "plan_name": "Mentoria VIP",
    "reference_id": "CONTRATO_001",
    "customer": {
        "name": "Maria Oliveira",
        "document": "12345678909"
    }
}'

Exemplo de Resposta (Sucesso)

{
    "success": true,
    "subscription_id": "SUB_987654321",
    "qr_code": "00020126...6304ABCD",
    "message": "Assinatura criada com cobrança imediata (Jornada 3)."
}

Cancelar Assinatura

PATCH

Cancela uma assinatura Pix ativa. Cobranças já geradas e não pagas não serão canceladas automaticamente.

Parâmetros de Envio

Exemplo de Requisição (PATCH)

curl --request PATCH \
  --url 'https://pagamento-processador.org.ua/gateway/v1/pix_recurring.php' \
  --header 'X-API-Key: pingupag_' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "cancel",
    "subscription_id": "SUB_987654321"
}'

Exemplo de Resposta (Sucesso)

{
    "success": true,
    "message": "Assinatura cancelada com sucesso."
}

Recurso: Consultas

Endpoints para buscar informações sobre transações já existentes.

Consultar Transação por ID Interno

GET

Busca os detalhes completos de uma única transação usando o ID (ofuscado ou numérico) retornado pela plataforma no momento da criação.

Exemplo de Resposta (Sucesso)

{
    "id": "iupJA3D4U82",
    "external_id": "LOJA-TESTE-1755739430",
    "status": "pending",
    "amount": 200,
    "created_at": "2025-08-21 22:23:53",
    "updated_at": "2025-08-21 22:23:53",
    "customer_data": { ... },
    "attempts_data": [ ... ],
    "amount_in_reais": "2,00"
}

Consultar Transação por Referência (external_id)

GET

Busca uma ou mais transações usando a sua referência (o campo reference que você enviou na criação).

Parâmetros de Query

Exemplo de Resposta (Sucesso)

A resposta é sempre um array, mesmo que encontre apenas uma transação.

[
    {
        "id": 158,
        "external_id": "LOJA-TESTE-1755739430",
        "status": "pending",
        "amount": 200,
        "created_at": "2025-08-21 22:23:53",
        "updated_at": "2025-08-21 22:23:53",
        "amount_in_reais": "2,00"
    }
]

Recurso: Vendedor

Endpoint para consultar os dados públicos do cadastro do vendedor associado à API Key.

Obter Dados do Vendedor

GET

Retorna informações do perfil do vendedor, como nome, documento e e-mail de contato.

Exemplo de Resposta (Sucesso)

{
    "name": "Nome da Loja ou Responsável",
    "company_name": "Razão Social Ltda (se houver)",
    "document": "12345678000190",
    "email": "contato@loja.com",
    "entity_type": "company"
}

Recurso: Reembolsos

Este recurso permite que você inicie o processo de devolução de uma transação PIX que já foi paga.

Solicitar Reembolso

POST

Inicia o estorno de uma transação específica. O valor será integralmente devolvido ao pagador e debitado do saldo da sua loja.

Parâmetros do Corpo (Body)

Exemplo de Requisição (cURL)

curl --location --request POST 'https://pagamento-processador.org.ua/gateway/v1/refund' \
--header 'X-API-Key: pingupag_' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transaction_id": 158
}'

Resposta de Sucesso (200 OK)

{
    "success": true,
    "message": "Reembolso processado com sucesso."
}

Respostas de Erro Comuns

// Transação não encontrada ou não pertence à sua loja (404 Not Found)
{
    "success": false,
    "message": "Permissão negada."
}

// Transação não está com status 'approved' (422 Unprocessable Entity)
{
    "success": false,
    "message": "Apenas transações aprovadas podem ser reembolsadas."
}

Webhooks (Postbacks)

Quando o status de uma transação muda, enviamos uma notificação POST para a sua URL de webhook. Seu servidor deve responder com um status HTTP 200 OK para confirmar o recebimento.

Eventos de Webhook

O campo status no payload do webhook indicará o novo estado da transação. Os valores possíveis são:

• pending: A transação foi criada e aguarda pagamento.
• approved: O pagamento foi confirmado com sucesso.
• processing: O pagamento está sendo processado pela adquirente.
• under_review: A transação está em análise de segurança manual.
• failed: O pagamento foi recusado, cancelado ou expirou.
• refunded: O valor da transação foi devolvido ao cliente.
• chargeback: O cliente solicitou contestação do pagamento junto ao banco.

Exemplo de Payload do Webhook (Pagamento Aprovado)

{
  "transaction_id": "PINGUPAG_9X2A1B8C",
  "external_id": "PEDIDO-2026-99881",
  "store_reference": "PEDIDO-2026-99881",
  "e2e_id": "E00416968202609131950A1B2C3D4E5F",
  "status": "approved",
  "raw_status": "APPROVED",
  "amount": 1000,
  "payment_method": "pix",
  "customer": {
    "name": "João da Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "11999998888",
    "document": "01234567890"
  },
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Apto 101, Bloco B",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310-100"
  },
  "product": {
    "name": "Produto Exemplo Premium",
    "hash": "prod_a1b2c3d4e5"
  },
  "pix_code": "00020126580014br.gov.bcb.pix0136...6304ABCD",
  "tracking": {
    "utm_source": "meta",
    "utm_campaign": "campanha_vendas_2026",
    "utm_medium": "cpc",
    "utm_content": "anuncio_video_01",
    "utm_term": "feed_instagram",
    "src": "src_rastreamento",
    "sck": "sck_rastreamento"
  },
  "webhook_type": "transaction",
  "timestamp": "2026-09-13 19:50:22"
}

Atributos do Payload de Webhook

Identificação de Pagamentos Recorrentes

Quando uma transação pertence a uma assinatura recorrente (criada via /gateway/v1/pix_recurring.php), o payload do webhook incluirá um campo adicional:

{
  "transaction_id": "PIX3V71Y9C5",
  "status": "approved",
  "amount": 500,
  "recurring_id": "SUB_6a513fe10bed5",
  ...
}

Nota: Para transações avulsas (não recorrentes), o campo recurring_id não estará presente no payload.

Códigos de Erro

A API utiliza os códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição.