Menu da documentação

Referência

API v1

Gerada do código a cada versão: o que está aqui é o que a API faz. O mesmo conteúdo em OpenAPI 3.1 (JSON).

Autenticação

Base URL: https://api.sandbox.pagaki.com.br/v1. Peça um token em https://api.sandbox.pagaki.com.br/oauth/token com o client_id e o client_secret do painel (OAuth 2.0 client credentials) e mande-o em Authorization: Bearer. O token vale 1 h, e só os IPs da lista de permitidos passam. Passo a passo no início rápido.

Conferir credenciais

GET /v1/me

Responde com o tenant do token: confirma o client, o secret e o IP antes de integrar.

GET /v1/me

curl -s https://api.sandbox.pagaki.com.br/v1/me \
  -H "Authorization: Bearer $TOKEN"

$response = $http->request('GET', 'https://api.sandbox.pagaki.com.br/v1/me', [
    'headers' => ['Authorization' => "Bearer {$token}"],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/me', {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await response.json();

Respostas

HTTP	Corpo
`200`
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`429`	`rate_limited` Limite de requisições excedido

bill_payments.index

GET /v1/bill_payments

curl -s https://api.sandbox.pagaki.com.br/v1/bill_payments \
  -H "Authorization: Bearer $TOKEN"

$response = $http->request('GET', 'https://api.sandbox.pagaki.com.br/v1/bill_payments', [
    'headers' => ['Authorization' => "Bearer {$token}"],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/bill_payments', {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await response.json();

Parâmetros

limit integer · query opcional

status string · query opcional

payment_id string · query opcional

cursor string · query opcional

Respostas

HTTP	Corpo
`200`
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`422`	`validation_failed` Dados inválidos
`429`	`rate_limited` Limite de requisições excedido

bill_payments.show

GET /v1/bill_payments/{billPayment}

curl -s https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment} \
  -H "Authorization: Bearer $TOKEN"

$response = $http->request('GET', 'https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}', [
    'headers' => ['Authorization' => "Bearer {$token}"],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}', {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await response.json();

Parâmetros

billPayment string · caminho obrigatório

Respostas

HTTP	Corpo
`200`
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`404`	`not_found` Recurso não encontrado
`429`	`rate_limited` Limite de requisições excedido

bill_payments.retry

POST /v1/bill_payments/{billPayment}/retry

curl -s -X POST https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}/retry \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '[]'

$response = $http->request('POST', 'https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}/retry', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'json' => [
,
    ],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}/retry', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Idempotency-Key': idempotencyKey, 'Content-Type': 'application/json' },
  body: JSON.stringify([]),
});
const data = await response.json();

Parâmetros

billPayment string · caminho obrigatório

Idempotency-Key string · header obrigatório

Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.

Exemplo: 6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00

Corpo (JSON)

identification_field string | null opcional

amount integer | null opcional

due_date string (date) | null opcional

Respostas

HTTP	Corpo
`200`
`400`	`idempotency_key_required` Idempotency-Key obrigatória
`400`	`idempotency_key_invalid` Idempotency-Key inválida
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`404`	`not_found` Recurso não encontrado
`409`	`idempotency_key_in_progress` Requisição em andamento
`422`	`validation_failed` Dados inválidos
`422`	`idempotency_key_reused` Idempotency-Key já usada
`429`	`rate_limited` Limite de requisições excedido

bill_payments.cancel

POST /v1/bill_payments/{billPayment}/cancel

curl -s -X POST https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

$response = $http->request('POST', 'https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}/cancel', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/bill_payments/{billPayment}/cancel', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Idempotency-Key': idempotencyKey },
});
const data = await response.json();

Parâmetros

billPayment string · caminho obrigatório

Idempotency-Key string · header obrigatório

Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.

Exemplo: 6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00

Respostas

HTTP	Corpo
`200`
`400`	`idempotency_key_required` Idempotency-Key obrigatória
`400`	`idempotency_key_invalid` Idempotency-Key inválida
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`404`	`not_found` Recurso não encontrado
`409`	`idempotency_key_in_progress` Requisição em andamento
`422`	`idempotency_key_reused` Idempotency-Key já usada
`429`	`rate_limited` Limite de requisições excedido

Criar um pagamento PIX

POST /v1/payments

O roteamento escolhe o gateway pelas regras do tenant e tenta o próximo se um falhar. 201 com o QR Code pronto; 202 com status: processing quando o gateway demora (o resultado chega pelo webhook).

POST /v1/payments

curl -s -X POST https://api.sandbox.pagaki.com.br/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "payer": {
        "name": "Fulano de Tal",
        "document": "12345678909"
    }
}'

$response = $http->request('POST', 'https://api.sandbox.pagaki.com.br/v1/payments', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'json' => [
        'method' => 'pix',
        'payer' => [
            'name' => 'Fulano de Tal',
            'document' => '12345678909',
        ],
    ],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/payments', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Idempotency-Key': idempotencyKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({
      "method": "pix",
      "payer": {
          "name": "Fulano de Tal",
          "document": "12345678909"
      }
  }),
});
const data = await response.json();

Parâmetros

Idempotency-Key string · header obrigatório

Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.

Exemplo: 6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00

Corpo (JSON)

method "pix" obrigatório

Meio de pagamento. Por enquanto só pix.

amount integer | null opcional

Valor em centavos, inteiro: 12550 é R$ 125,50. Com pay_bill é opcional: o Pagaki calcula.

Exemplo: 12550

currency "BRL" opcional

Só BRL.

description string | null opcional

Aparece para o pagador quando o gateway mostra.

Exemplo: "IPTU 2026, parcela 1"

external_id string | null opcional

Seu identificador. Filtrável na listagem, mas não único: para não duplicar, use a Idempotency-Key.

Exemplo: "guia-778899"

expires_at string (date-time) | null opcional

Vencimento do PIX, ISO 8601 no futuro. Sem ele, 30 minutos.

payer object obrigatório

Quem paga. Guardado criptografado e devolvido mascarado.

payer.name string obrigatório

Nome completo.

Exemplo: "Fulano de Tal"

payer.document string obrigatório

CPF ou CNPJ, só números.

Exemplo: "12345678909"

payer.email string (email) | null opcional

E-mail do pagador.

payer.phone string | null opcional

Telefone do pagador.

metadata array opcional

Até 20 chaves (até 40 caracteres) com valores de texto (até 500). Volta nas respostas e nos webhooks.

service_fee integer | null opcional

Taxa do integrador, em centavos. Só com pay_bill. O que amount trouxer a mais entra aqui.

pay_bill object opcional

Conta a pagar quando este pagamento for confirmado.

pay_bill.identification_field string opcional

Linha digitável do boleto (47 dígitos) ou da guia de arrecadação (48).

pay_bill.amount integer | null opcional

Valor da conta em centavos, só para conferência: o valor vem da simulação no gateway.

pay_bill.due_date string (date) | null opcional

Vencimento, AAAA-MM-DD, para conferência.

pay_bill.description string | null opcional

Até 140 caracteres. Fica só no Pagaki.

gateway string | null opcional

Força uma instalação (inst_…) e ignora as regras de roteamento.

Respostas

HTTP	Corpo
`201`	Objeto payment. Cobrança criada no gateway, com o QR Code.
`202`	Objeto payment. O gateway demorou: `status: processing`; o resultado chega pelo webhook.
`400`	`idempotency_key_required` Idempotency-Key obrigatória
`400`	`idempotency_key_invalid` Idempotency-Key inválida
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`409`	`idempotency_key_in_progress` Requisição em andamento
`422`	`no_gateway_available` Nenhum gateway disponível
`422`	`gateway_invalid_data` Dados recusados pelo gateway
`422`	`validation_failed` Dados inválidos
`422`	`idempotency_key_reused` Idempotency-Key já usada
`429`	`rate_limited` Limite de requisições excedido
`502`	`gateway_rejected` Recusado pelo gateway
`502`	`gateway_failure` Nenhum gateway concluiu a cobrança

Listar pagamentos

GET /v1/payments

Do mais novo para o mais antigo, paginado por cursor: repita a chamada com cursor=next_cursor até ele vir null.

GET /v1/payments

curl -s https://api.sandbox.pagaki.com.br/v1/payments \
  -H "Authorization: Bearer $TOKEN"

$response = $http->request('GET', 'https://api.sandbox.pagaki.com.br/v1/payments', [
    'headers' => ['Authorization' => "Bearer {$token}"],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/payments', {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await response.json();

Parâmetros

limit integer · query opcional

status string · query opcional

method string · query opcional

external_id string · query opcional

created_from string (date-time) · query opcional

created_to string (date-time) · query opcional

cursor string · query opcional

Respostas

HTTP	Corpo
`200`
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`422`	`validation_failed` Dados inválidos
`429`	`rate_limited` Limite de requisições excedido

Cotar um pagamento

POST /v1/payments/quote

Mesmo corpo do POST /v1/payments, sem criar nada: diz por qual gateway sairia e quanto cobrar, para mostrar o valor ao pagador antes. Para garantir o mesmo valor na criação, envie o gateway devolvido aqui.

POST /v1/payments/quote

curl -s -X POST https://api.sandbox.pagaki.com.br/v1/payments/quote \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "payer": {
        "name": "Fulano de Tal",
        "document": "12345678909"
    }
}'

$response = $http->request('POST', 'https://api.sandbox.pagaki.com.br/v1/payments/quote', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'json' => [
        'method' => 'pix',
        'payer' => [
            'name' => 'Fulano de Tal',
            'document' => '12345678909',
        ],
    ],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/payments/quote', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Idempotency-Key': idempotencyKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({
      "method": "pix",
      "payer": {
          "name": "Fulano de Tal",
          "document": "12345678909"
      }
  }),
});
const data = await response.json();

Parâmetros

Idempotency-Key string · header obrigatório

Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.

Exemplo: 6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00

Corpo (JSON)

method "pix" obrigatório

Meio de pagamento. Por enquanto só pix.

amount integer | null opcional

Valor em centavos, inteiro: 12550 é R$ 125,50. Com pay_bill é opcional: o Pagaki calcula.

Exemplo: 12550

currency "BRL" opcional

Só BRL.

description string | null opcional

Aparece para o pagador quando o gateway mostra.

Exemplo: "IPTU 2026, parcela 1"

external_id string | null opcional

Seu identificador. Filtrável na listagem, mas não único: para não duplicar, use a Idempotency-Key.

Exemplo: "guia-778899"

expires_at string (date-time) | null opcional

Vencimento do PIX, ISO 8601 no futuro. Sem ele, 30 minutos.

payer object obrigatório

Quem paga. Guardado criptografado e devolvido mascarado.

payer.name string obrigatório

Nome completo.

Exemplo: "Fulano de Tal"

payer.document string obrigatório

CPF ou CNPJ, só números.

Exemplo: "12345678909"

payer.email string (email) | null opcional

E-mail do pagador.

payer.phone string | null opcional

Telefone do pagador.

metadata array opcional

Até 20 chaves (até 40 caracteres) com valores de texto (até 500). Volta nas respostas e nos webhooks.

service_fee integer | null opcional

Taxa do integrador, em centavos. Só com pay_bill. O que amount trouxer a mais entra aqui.

pay_bill object opcional

Conta a pagar quando este pagamento for confirmado.

pay_bill.identification_field string opcional

Linha digitável do boleto (47 dígitos) ou da guia de arrecadação (48).

pay_bill.amount integer | null opcional

Valor da conta em centavos, só para conferência: o valor vem da simulação no gateway.

pay_bill.due_date string (date) | null opcional

Vencimento, AAAA-MM-DD, para conferência.

pay_bill.description string | null opcional

Até 140 caracteres. Fica só no Pagaki.

gateway string | null opcional

Força uma instalação (inst_…) e ignora as regras de roteamento.

Respostas

HTTP	Corpo
`200`
`400`	`idempotency_key_required` Idempotency-Key obrigatória
`400`	`idempotency_key_invalid` Idempotency-Key inválida
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`409`	`idempotency_key_in_progress` Requisição em andamento
`422`	`no_gateway_available` Nenhum gateway disponível
`422`	`validation_failed` Dados inválidos
`422`	`idempotency_key_reused` Idempotency-Key já usada
`429`	`rate_limited` Limite de requisições excedido

Consultar um pagamento

GET /v1/payments/{payment}

curl -s https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st \
  -H "Authorization: Bearer $TOKEN"

$response = $http->request('GET', 'https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st', [
    'headers' => ['Authorization' => "Bearer {$token}"],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st', {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await response.json();

Parâmetros

payment string · caminho obrigatório

Respostas

HTTP	Corpo
`200`	Objeto payment.
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`404`	`not_found` Recurso não encontrado
`429`	`rate_limited` Limite de requisições excedido

Cancelar um pagamento pendente

POST /v1/payments/{payment}/cancel

curl -s -X POST https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

$response = $http->request('POST', 'https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st/cancel', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'http_errors' => false,
]);

const response = await fetch('https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st/cancel', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Idempotency-Key': idempotencyKey },
});
const data = await response.json();

Parâmetros

payment string · caminho obrigatório

Idempotency-Key string · header obrigatório

Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.

Exemplo: 6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00

Respostas

HTTP	Corpo
`200`	Objeto payment.
`400`	`idempotency_key_required` Idempotency-Key obrigatória
`400`	`idempotency_key_invalid` Idempotency-Key inválida
`401`	`unauthenticated` Não autenticado
`403`	`ip_not_allowed` IP não autorizado
`404`	`not_found` Recurso não encontrado
`409`	`invalid_state` Estado não permite cancelar
`409`	`idempotency_key_in_progress` Requisição em andamento
`422`	`cancel_not_supported` Gateway não cancela
`422`	`idempotency_key_reused` Idempotency-Key já usada
`429`	`rate_limited` Limite de requisições excedido
`502`	`gateway_failure` Falha no gateway

Objeto payment

Devolvido na criação, na consulta, na listagem e no cancelamento, e em data.object dos webhooks. Dados do pagador sempre mascarados.

id string obrigatório

pay_…

object "payment" obrigatório

method "pix" obrigatório

Situação: só paid (e os estornos) quer dizer dinheiro recebido.

amount integer obrigatório

Valor em centavos.

amount_breakdown array | null obrigatório

Composição do valor; null sem pagamento de conta.

amount_breakdown[].type string obrigatório

amount_breakdown[].amount integer obrigatório

amount_breakdown[].label string obrigatório

amount_paid integer | null obrigatório

Quanto foi pago, em centavos; null até pagar.

amount_refunded integer obrigatório

Quanto foi estornado, em centavos.

currency string obrigatório

description string | null obrigatório

external_id string | null obrigatório

metadata object obrigatório

payer object obrigatório

Dados do pagador, mascarados.

payer.name string obrigatório

payer.document string | string obrigatório

payer.email string | string | null obrigatório

payer.phone string | string | null obrigatório

expires_at string obrigatório

paid_at string | null obrigatório

created_at string obrigatório

pix object obrigatório

O QR Code "copia e cola" em qr_code; qr_code_image_url hoje é sempre null.

pix.qr_code string | null obrigatório

pix.qr_code_image_url string | null obrigatório

gateway object | null obrigatório

A instalação que criou a cobrança; null se nenhuma criou.

gateway.installation_id string obrigatório

gateway.provider string obrigatório

gateway.provider_payment_id string | null obrigatório

routing object obrigatório

routing.rule_set_id string | null obrigatório

routing.rule_id string | null obrigatório

routing.forced boolean obrigatório

attempts array obrigatório

Cada gateway tentado, na ordem, com o erro normalizado de quem falhou.

attempts[].installation_id string obrigatório

attempts[].provider string obrigatório

attempts[].status string obrigatório

attempts[].error_code string | null obrigatório

attempts[].latency_ms integer | null obrigatório

bill_payment string obrigatório

Situações (`status`)

processing, pending, paid, expired, canceled, failed, partially_refunded, refunded

API v1

Autenticação

Conferir credenciais

Respostas

bill_payments.index

Parâmetros

Respostas

bill_payments.show

Parâmetros

Respostas

bill_payments.retry

Parâmetros

Corpo (JSON)

Respostas

bill_payments.cancel

Parâmetros

Respostas

Criar um pagamento PIX

Parâmetros

Corpo (JSON)

Respostas

Listar pagamentos

Parâmetros

Respostas

Cotar um pagamento

Parâmetros

Corpo (JSON)

Respostas

Consultar um pagamento

Parâmetros

Respostas

Cancelar um pagamento pendente

Parâmetros

Respostas

Objeto payment

Situações (status)

Situações (`status`)