Paylor API

Authentication

Every call carries Authorization: Bearer pk_live_… or pk_test_…. The test key only sees the test world. Idempotency-Key is required in practice on everything that creates: repeating returns the same response; a different body with the same key is 409.

Authorization: Bearer pk_test_…
Idempotency-Key: <id do seu lado>
Accept-Language: pt-BR | en | es
Content-Type: application/json

Sellers

• POST /v1/vendedores
• GET /v1/vendedores
• GET /v1/vendedores/{id}
• POST /v1/vendedores/{id}/pausar
• POST /v1/vendedores/{id}/retomar
• POST /v1/vendedores/{id}/debitos

POST https://paylor.io/v1/vendedores
{ "nome": "Mira Studio", "nome_na_fatura": "Mira Studio", "email_do_dono": "ana@mirastudio.com",
  "moeda": "USD", "taxa": { "percentual_bps": 400, "fixo_centavos": 35 }, "plano": "Crescimento",
  "id_no_cliente": "loja_mira", "idioma": "pt-BR", "pais": "US", "volta_para": "https://…/acesso?pedido={id}" }

201 { "id": "vend_test_…", "estado": "cadastro_pendente", "podeCobrar": false, "podeReceber": false, "urlDoConnect": "https://paylor.io/connect/t_…" }

Orders

• POST /v1/pedidos
• GET /v1/pedidos?vendedor=&estado=&comprador=
• GET /v1/pedidos/{id}
• POST /v1/pedidos/{id}/reembolsos
• GET /v1/pedidos/{id}/reembolsos

POST https://paylor.io/v1/pedidos
{ "vendedor": "vend_test_…", "valor": 4900, "descricao": "Pack de presets Lightroom",
  "comprador": { "email": "miguel@exemplo.com", "idioma": "pt-BR" }, "reembolso_ate_dias": 7,
  "tipo": "unico" | "assinatura", "intervalo": "mes" | "ano", "id_no_cliente": "ped_7f31", "metadados": { } }

201 { "id": "PL-TEST-00012", "estado": "criado", "taxa": 231, "repasse": 4669, "checkoutUrl": "https://paylor.io/c/t_…" }

POST /v1/pedidos/PL-TEST-00012/reembolsos  { "valor": 2450, "motivo": "…" }   (sem valor = total)

Subscriptions

• GET /v1/assinaturas/{id}
• POST /v1/assinaturas/{id}/cancelar { quando: agora | fim_do_periodo }
• POST /v1/assinaturas/{id}/pausar
• POST /v1/assinaturas/{id}/retomar

Disputes

• POST /v1/disputas/{id}/provas { provas: { entrega: '…', download: '…', termos: '…' } }

Webhooks back to you

Paylor POSTs to the client's URL with the paylor-assinatura header (t=unix,v1=hmac-sha256 of 't.body'). Reply 200. Five attempts: 1 min, 5 min, 30 min, 2 h, 6 h. After that the event waits in the admin and you can fetch it with GET /v1/eventos.

GET /v1/eventos?depois=evt_…&tipo=pedido.pago
GET /v1/eventos/{id}

{ "id": "evt_test_…", "tipo": "pedido.pago", "ambiente": "test", "criadoEm": "…", "objeto": { "tipo": "pedido", "id": "PL-TEST-00012" }, "dados": { … } }

Errors

Every error has a fixed code and a status. The code is never translated; the message is for the log.