{"openapi":"3.1.2","info":{"title":"Pagaki API","version":"1","description":"API pública do Pagaki: cobranças PIX roteadas entre gateways, com fallback. Valores em centavos, datas em ISO 8601, IDs com prefixo e erros no formato RFC 9457."},"servers":[{"url":"https://api.sandbox.pagaki.com.br/v1","description":"Sandbox"}],"security":[{"oauth2":[]}],"paths":{"/me":{"get":{"operationId":"me","description":"Responde com o tenant do token: confirma o client, o secret e o IP antes de integrar.","summary":"Conferir credenciais","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"}},"required":["id","name","plan"]}},"required":["tenant"]}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/bill_payments":{"get":{"operationId":"bill_payments.index","tags":["BillPayment"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"payment_id","in":"query","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"__PHP_Incomplete_Class_Name":"stdClass"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"422":{"description":"`validation_failed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/validation_failed","title":"Dados inválidos","status":422,"code":"validation_failed","detail":"Um ou mais campos são inválidos.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/bill_payments/{billPayment}":{"get":{"operationId":"bill_payments.show","tags":["BillPayment"],"parameters":[{"name":"billPayment","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"__PHP_Incomplete_Class_Name":"stdClass"}}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"404":{"description":"`not_found`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"type":"https://sandbox.pagaki.com.br/errors/not_found","title":"Recurso não encontrado","status":404,"code":"not_found","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/bill_payments/{billPayment}/retry":{"post":{"operationId":"bill_payments.retry","tags":["BillPayment"],"parameters":[{"name":"billPayment","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.","schema":{"type":"string","description":"Até 255 caracteres; um UUID por operação."},"example":"6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryBillPaymentRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"__PHP_Incomplete_Class_Name":"stdClass"}}}}},"400":{"description":"`idempotency_key_required`, `idempotency_key_invalid`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_required":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_required","title":"Idempotency-Key obrigatória","status":400,"code":"idempotency_key_required","detail":"Envie o header Idempotency-Key em toda criação.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_invalid":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_invalid","title":"Idempotency-Key inválida","status":400,"code":"idempotency_key_invalid","detail":"A chave pode ter no máximo 255 caracteres.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"404":{"description":"`not_found`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"type":"https://sandbox.pagaki.com.br/errors/not_found","title":"Recurso não encontrado","status":404,"code":"not_found","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"409":{"description":"`idempotency_key_in_progress`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_in_progress":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_in_progress","title":"Requisição em andamento","status":409,"code":"idempotency_key_in_progress","detail":"Já existe uma requisição com esta chave sendo processada.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"422":{"description":"`validation_failed`, `idempotency_key_reused`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/validation_failed","title":"Dados inválidos","status":422,"code":"validation_failed","detail":"Um ou mais campos são inválidos.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_reused":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_reused","title":"Idempotency-Key já usada","status":422,"code":"idempotency_key_reused","detail":"Esta chave já foi usada com outra requisição.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/bill_payments/{billPayment}/cancel":{"post":{"operationId":"bill_payments.cancel","tags":["BillPayment"],"parameters":[{"name":"billPayment","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.","schema":{"type":"string","description":"Até 255 caracteres; um UUID por operação."},"example":"6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"__PHP_Incomplete_Class_Name":"stdClass"}}}}},"400":{"description":"`idempotency_key_required`, `idempotency_key_invalid`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_required":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_required","title":"Idempotency-Key obrigatória","status":400,"code":"idempotency_key_required","detail":"Envie o header Idempotency-Key em toda criação.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_invalid":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_invalid","title":"Idempotency-Key inválida","status":400,"code":"idempotency_key_invalid","detail":"A chave pode ter no máximo 255 caracteres.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"404":{"description":"`not_found`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"type":"https://sandbox.pagaki.com.br/errors/not_found","title":"Recurso não encontrado","status":404,"code":"not_found","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"409":{"description":"`idempotency_key_in_progress`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_in_progress":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_in_progress","title":"Requisição em andamento","status":409,"code":"idempotency_key_in_progress","detail":"Já existe uma requisição com esta chave sendo processada.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"422":{"description":"`idempotency_key_reused`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_reused":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_reused","title":"Idempotency-Key já usada","status":422,"code":"idempotency_key_reused","detail":"Esta chave já foi usada com outra requisição.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/payments":{"post":{"operationId":"payments.store","description":"O roteamento escolhe o gateway pelas regras do tenant e tenta o próximo se um falhar. `201` com o QR Code\npronto; `202` com `status: processing` quando o gateway demora (o resultado chega pelo webhook).","summary":"Criar um pagamento PIX","tags":["Payment"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.","schema":{"type":"string","description":"Até 255 caracteres; um UUID por operação."},"example":"6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}}},"responses":{"201":{"description":"Cobrança criada no gateway, com o QR Code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResource"}}}},"202":{"description":"O gateway demorou: `status: processing`; o resultado chega pelo webhook.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResource"}}}},"400":{"description":"`idempotency_key_required`, `idempotency_key_invalid`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_required":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_required","title":"Idempotency-Key obrigatória","status":400,"code":"idempotency_key_required","detail":"Envie o header Idempotency-Key em toda criação.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_invalid":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_invalid","title":"Idempotency-Key inválida","status":400,"code":"idempotency_key_invalid","detail":"A chave pode ter no máximo 255 caracteres.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"409":{"description":"`idempotency_key_in_progress`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_in_progress":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_in_progress","title":"Requisição em andamento","status":409,"code":"idempotency_key_in_progress","detail":"Já existe uma requisição com esta chave sendo processada.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"422":{"description":"`no_gateway_available`, `gateway_invalid_data`, `validation_failed`, `idempotency_key_reused`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"no_gateway_available":{"value":{"type":"https://sandbox.pagaki.com.br/errors/no_gateway_available","title":"Nenhum gateway disponível","status":422,"code":"no_gateway_available","detail":"Nenhuma instalação ativa atende este pagamento (método, expiração ou gateway forçado).","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"gateway_invalid_data":{"value":{"type":"https://sandbox.pagaki.com.br/errors/gateway_invalid_data","title":"Dados recusados pelo gateway","status":422,"code":"gateway_invalid_data","detail":"A mensagem do gateway, como o conector a montou (ex.: `Asaas recusou a requisição (HTTP 400): …`)","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"validation_failed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/validation_failed","title":"Dados inválidos","status":422,"code":"validation_failed","detail":"Um ou mais campos são inválidos.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_reused":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_reused","title":"Idempotency-Key já usada","status":422,"code":"idempotency_key_reused","detail":"Esta chave já foi usada com outra requisição.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"502":{"description":"`gateway_rejected`, `gateway_failure`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"gateway_rejected":{"value":{"type":"https://sandbox.pagaki.com.br/errors/gateway_rejected","title":"Recusado pelo gateway","status":502,"code":"gateway_rejected","detail":"A mensagem do gateway, como o conector a montou (ex.: `Asaas recusou a requisição (HTTP 400): …`)","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"gateway_failure":{"value":{"type":"https://sandbox.pagaki.com.br/errors/gateway_failure","title":"Nenhum gateway concluiu a cobrança","status":502,"code":"gateway_failure","detail":"Na criação, a mensagem do último gateway ou \"Nenhum gateway disponível conseguiu criar a cobrança.\"; no cancelamento, \"O gateway não confirmou o cancelamento. Tente de novo.\"","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}},"get":{"operationId":"payments.index","description":"Do mais novo para o mais antigo, paginado por cursor: repita a chamada com `cursor=next_cursor` até ele vir `null`.","summary":"Listar pagamentos","tags":["Payment"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"method","in":"query","schema":{"type":"string"}},{"name":"external_id","in":"query","schema":{"type":"string"}},{"name":"created_from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentResource"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"]}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"422":{"description":"`validation_failed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/validation_failed","title":"Dados inválidos","status":422,"code":"validation_failed","detail":"Um ou mais campos são inválidos.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/payments/quote":{"post":{"operationId":"payments.quote","description":"Mesmo corpo do `POST /v1/payments`, sem criar nada: diz por qual gateway sairia e quanto cobrar, para mostrar o\nvalor ao pagador antes. Para garantir o mesmo valor na criação, envie o `gateway` devolvido aqui.","summary":"Cotar um pagamento","tags":["Payment"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.","schema":{"type":"string","description":"Até 255 caracteres; um UUID por operação."},"example":"6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"payment_quote"},"amount":{"type":"integer"},"currency":{"type":"string","const":"BRL"},"gateway":{"type":"object","properties":{"installation_id":{"type":"string"},"provider":{"type":"string"}},"required":["installation_id","provider"]},"amount_breakdown":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string"},"amount":{"type":"integer"},"label":{"type":"string"}},"required":["type","amount","label"]}}},"required":["object","amount","currency","gateway","amount_breakdown"]}}}},"400":{"description":"`idempotency_key_required`, `idempotency_key_invalid`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_required":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_required","title":"Idempotency-Key obrigatória","status":400,"code":"idempotency_key_required","detail":"Envie o header Idempotency-Key em toda criação.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_invalid":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_invalid","title":"Idempotency-Key inválida","status":400,"code":"idempotency_key_invalid","detail":"A chave pode ter no máximo 255 caracteres.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"409":{"description":"`idempotency_key_in_progress`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_in_progress":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_in_progress","title":"Requisição em andamento","status":409,"code":"idempotency_key_in_progress","detail":"Já existe uma requisição com esta chave sendo processada.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"422":{"description":"`no_gateway_available`, `validation_failed`, `idempotency_key_reused`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"no_gateway_available":{"value":{"type":"https://sandbox.pagaki.com.br/errors/no_gateway_available","title":"Nenhum gateway disponível","status":422,"code":"no_gateway_available","detail":"Nenhuma instalação ativa atende este pagamento (método, expiração ou gateway forçado).","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"validation_failed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/validation_failed","title":"Dados inválidos","status":422,"code":"validation_failed","detail":"Um ou mais campos são inválidos.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_reused":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_reused","title":"Idempotency-Key já usada","status":422,"code":"idempotency_key_reused","detail":"Esta chave já foi usada com outra requisição.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/payments/{payment}":{"get":{"operationId":"payments.show","summary":"Consultar um pagamento","tags":["Payment"],"parameters":[{"name":"payment","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`PaymentResource`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResource"}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"404":{"description":"`not_found`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"type":"https://sandbox.pagaki.com.br/errors/not_found","title":"Recurso não encontrado","status":404,"code":"not_found","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}},"/payments/{payment}/cancel":{"post":{"operationId":"payments.cancel","summary":"Cancelar um pagamento pendente","tags":["Payment"],"parameters":[{"name":"payment","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Uma chave por operação, guardada antes de enviar. Repetir com a mesma chave devolve a primeira resposta, sem criar outro pagamento.","schema":{"type":"string","description":"Até 255 caracteres; um UUID por operação."},"example":"6f1c2a0e-8b7d-4e3f-9a21-5c4b3d2e1f00"}],"responses":{"200":{"description":"`PaymentResource`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResource"}}}},"400":{"description":"`idempotency_key_required`, `idempotency_key_invalid`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_key_required":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_required","title":"Idempotency-Key obrigatória","status":400,"code":"idempotency_key_required","detail":"Envie o header Idempotency-Key em toda criação.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_invalid":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_invalid","title":"Idempotency-Key inválida","status":400,"code":"idempotency_key_invalid","detail":"A chave pode ter no máximo 255 caracteres.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"401":{"description":"`unauthenticated`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"value":{"type":"https://sandbox.pagaki.com.br/errors/unauthenticated","title":"Não autenticado","status":401,"code":"unauthenticated","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"403":{"description":"`ip_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"ip_not_allowed":{"value":{"type":"https://sandbox.pagaki.com.br/errors/ip_not_allowed","title":"IP não autorizado","status":403,"code":"ip_not_allowed","detail":"O IP `{ip}` não está na allowlist do tenant.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"404":{"description":"`not_found`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"type":"https://sandbox.pagaki.com.br/errors/not_found","title":"Recurso não encontrado","status":404,"code":"not_found","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"409":{"description":"`invalid_state`, `idempotency_key_in_progress`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_state":{"value":{"type":"https://sandbox.pagaki.com.br/errors/invalid_state","title":"Estado não permite cancelar","status":409,"code":"invalid_state","detail":"Só cobranças pendentes podem ser canceladas.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_in_progress":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_in_progress","title":"Requisição em andamento","status":409,"code":"idempotency_key_in_progress","detail":"Já existe uma requisição com esta chave sendo processada.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"422":{"description":"`cancel_not_supported`, `idempotency_key_reused`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"cancel_not_supported":{"value":{"type":"https://sandbox.pagaki.com.br/errors/cancel_not_supported","title":"Gateway não cancela","status":422,"code":"cancel_not_supported","detail":"O gateway desta cobrança não permite cancelamento.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}},"idempotency_key_reused":{"value":{"type":"https://sandbox.pagaki.com.br/errors/idempotency_key_reused","title":"Idempotency-Key já usada","status":422,"code":"idempotency_key_reused","detail":"Esta chave já foi usada com outra requisição.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"429":{"description":"`rate_limited`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"type":"https://sandbox.pagaki.com.br/errors/rate_limited","title":"Limite de requisições excedido","status":429,"code":"rate_limited","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}},"502":{"description":"`gateway_failure`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"gateway_failure":{"value":{"type":"https://sandbox.pagaki.com.br/errors/gateway_failure","title":"Falha no gateway","status":502,"code":"gateway_failure","detail":"O gateway não confirmou o cancelamento. Tente de novo.","request_id":"01JBZ3Q2W5E8R1T4Y7K0M3N6P9"}}}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Client credentials do painel (Acesso à API). O token vale 1 h; só IPs da lista de permitidos.","flows":{"clientCredentials":{"tokenUrl":"https://api.sandbox.pagaki.com.br/oauth/token","scopes":{"__PHP_Incomplete_Class_Name":"stdClass"}}}}},"schemas":{"CreatePaymentRequest":{"type":"object","description":"POST /v1/payments (API.md §5.1). Por enquanto só method=pix (boleto na F3, cartão na F4).","properties":{"method":{"type":"string","description":"Meio de pagamento. Por enquanto só `pix`.","enum":["pix"]},"amount":{"type":["integer","null"],"description":"Valor em centavos, inteiro: `12550` é R$ 125,50. Com `pay_bill` é opcional: o Pagaki calcula.","examples":[12550],"minimum":1},"currency":{"type":"string","description":"Só `BRL`.","enum":["BRL"]},"description":{"type":["string","null"],"description":"Aparece para o pagador quando o gateway mostra.","examples":["IPTU 2026, parcela 1"],"maxLength":255},"external_id":{"type":["string","null"],"description":"Seu identificador. Filtrável na listagem, mas não único: para não duplicar, use a `Idempotency-Key`.","examples":["guia-778899"],"maxLength":255},"expires_at":{"type":["string","null"],"format":"date-time","description":"Vencimento do PIX, ISO 8601 no futuro. Sem ele, 30 minutos."},"payer":{"type":"object","description":"Quem paga. Guardado criptografado e devolvido mascarado.","properties":{"name":{"type":"string","description":"Nome completo.","examples":["Fulano de Tal"],"maxLength":255},"document":{"type":"string","description":"CPF ou CNPJ, só números.","examples":["12345678909"]},"email":{"type":["string","null"],"format":"email","description":"E-mail do pagador.","maxLength":255},"phone":{"type":["string","null"],"description":"Telefone do pagador.","maxLength":30}},"required":["name","document"]},"metadata":{"type":"array","description":"Até 20 chaves (até 40 caracteres) com valores de texto (até 500). Volta nas respostas e nos webhooks.","items":{"type":"string","maxLength":500},"maxItems":20},"service_fee":{"type":["integer","null"],"description":"Taxa do integrador, em centavos. Só com `pay_bill`. O que `amount` trouxer a mais entra aqui.","minimum":0},"pay_bill":{"type":"object","description":"Conta a pagar quando este pagamento for confirmado.","properties":{"identification_field":{"type":"string","description":"Linha digitável do boleto (47 dígitos) ou da guia de arrecadação (48).","maxLength":60},"amount":{"type":["integer","null"],"description":"Valor da conta em centavos, só para conferência: o valor vem da simulação no gateway.","minimum":1},"due_date":{"type":["string","null"],"format":"date","description":"Vencimento, `AAAA-MM-DD`, para conferência."},"description":{"type":["string","null"],"description":"Até 140 caracteres. Fica só no Pagaki.","maxLength":140}}},"gateway":{"type":["string","null"],"description":"Força uma instalação (`inst_…`) e ignora as regras de roteamento."}},"required":["method","payer"],"title":"CreatePaymentRequest"},"PaymentResource":{"type":"object","properties":{"id":{"type":"string","description":"`pay_…`"},"object":{"type":"string","const":"payment"},"method":{"type":"string","const":"pix"},"status":{"type":"string","description":"Situação: só `paid` (e os estornos) quer dizer dinheiro recebido.","enum":["processing","pending","paid","expired","canceled","failed","partially_refunded","refunded"]},"amount":{"type":"integer","description":"Valor em centavos."},"amount_breakdown":{"type":["array","null"],"description":"Composição do valor; `null` sem pagamento de conta.","items":{"type":"object","properties":{"type":{"type":"string"},"amount":{"type":"integer"},"label":{"type":"string"}},"required":["type","amount","label"]}},"amount_paid":{"type":["integer","null"],"description":"Quanto foi pago, em centavos; `null` até pagar."},"amount_refunded":{"type":"integer","description":"Quanto foi estornado, em centavos."},"currency":{"type":"string"},"description":{"type":["string","null"]},"external_id":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"payer":{"type":"object","description":"Dados do pagador, mascarados.","properties":{"name":{"type":"string"},"document":{"anyOf":[{"type":"string"},{"type":"string","enum":["***"]}]},"email":{"anyOf":[{"type":"null"},{"type":"string"},{"type":"string","enum":["***"]}]},"phone":{"anyOf":[{"type":"null"},{"type":"string"},{"type":"string","enum":["***"]}]}},"required":["name","document","email","phone"]},"expires_at":{"type":"string"},"paid_at":{"type":["string","null"]},"created_at":{"type":"string"},"pix":{"type":"object","description":"O QR Code \"copia e cola\" em `qr_code`; `qr_code_image_url` hoje é sempre `null`.","properties":{"qr_code":{"type":["string","null"]},"qr_code_image_url":{"type":["string","null"]}},"required":["qr_code","qr_code_image_url"]},"gateway":{"type":["object","null"],"description":"A instalação que criou a cobrança; `null` se nenhuma criou.","properties":{"installation_id":{"type":"string"},"provider":{"type":"string"},"provider_payment_id":{"type":["string","null"]}},"required":["installation_id","provider","provider_payment_id"]},"routing":{"type":"object","properties":{"rule_set_id":{"type":["string","null"]},"rule_id":{"type":["string","null"]},"forced":{"type":"boolean"}},"required":["rule_set_id","rule_id","forced"]},"attempts":{"type":"array","description":"Cada gateway tentado, na ordem, com o erro normalizado de quem falhou.","items":{"type":"object","properties":{"installation_id":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"error_code":{"type":["string","null"]},"latency_ms":{"type":["integer","null"]}},"required":["installation_id","provider","status","error_code","latency_ms"]}},"bill_payment":{"type":"string"}},"required":["id","object","method","status","amount","amount_breakdown","amount_paid","amount_refunded","currency","description","external_id","metadata","payer","expires_at","paid_at","created_at","pix","gateway","routing","attempts","bill_payment"],"title":"PaymentResource"},"Problem":{"type":"object","properties":{"type":{"type":"string","format":"uri","description":"Página do erro: {APP_URL}/errors/{code}."},"title":{"type":"string","description":"Título fixo por code, em português."},"status":{"type":"integer","description":"O mesmo status HTTP da resposta."},"code":{"type":"string","description":"Código estável, em inglês. Decida por ele."},"detail":{"type":"string","description":"Explicação para pessoas; o texto pode mudar."},"errors":{"type":"object","description":"Só em validation_failed: as mensagens de cada campo.","additionalProperties":{"type":"array","items":{"type":"string"}}},"payment":{"type":"object","description":"Só nos erros de gateway na criação: o objeto payment, em failed."},"request_id":{"type":"string","description":"Guarde para falar com o suporte."}},"required":["type","title","status","code","request_id"],"title":"Problem"},"RetryBillPaymentRequest":{"type":"object","description":"POST /v1/bill_payments/{id}/retry (API.md §5.6): corpo opcional para trocar o boleto.","properties":{"identification_field":{"type":["string","null"],"maxLength":60},"amount":{"type":["integer","null"],"minimum":1},"due_date":{"type":["string","null"],"format":"date"}},"title":"RetryBillPaymentRequest"}}}}