PaystationdocsPaystation
  1. Início
  2. API
  3. Kit de testes

Kit de testes

Coleção do Postman da API /v1, gerada do OpenAPI, com os ambientes de homologação e produção, e o roteiro para testar uma integração.

A coleção tem uma requisição para cada rota da API /v1, gerada da mesma especificação que a referência. Ela acompanha a API: a cada publicação deste site, a coleção é gerada de novo.

Coleção · Ambiente de homologação · Ambiente de produção

Começar ​

  1. No Postman, importe a coleção e os dois ambientes (Import, arraste os três arquivos).
  2. Escolha o ambiente Paystation homologação.
  3. Preencha secret_key com a sua chave sk_test_… e offer_id com o id de uma oferta publicada do seu cliente. Preencha só o local value: ele fica no seu computador. O shared value é sincronizado com a nuvem do Postman e com quem mais usa o seu workspace.
  4. Rode me → Describe the key used on the request para conferir a chave.
VariávelO que é
base_urlO endereço da API do ambiente.
secret_key, publishable_keyAs chaves do seu cliente. A coleção usa a secreta em toda rota que a aceita, que hoje são todas.
offer_idA oferta usada nas cotações e nas cobranças.
charge_id, subscription_idPreenchidos sozinhos por uma cobrança criada, para as consultas, o estorno e o cancelamento.
destination_idPreenchido sozinho por um destino de webhook cadastrado.
webhook_urlA URL do seu webhook, para cadastrar um destino. Vazia, o cadastro é recusado. Use um endereço seu e privado, nunca um serviço público de captura de requisições: o destino passa a receber os avisos de todos os compradores do cliente, com os dados deles.
turnstile_tokenO token do desafio, quando o Turnstile está ligado no seu cliente (veja abaixo).
idempotency_keyVazio: cada envio da cobrança é uma tentativa nova. Preenchido: todos os envios usam essa chave.
last_attempt_keyA chave do último envio da cobrança, guardada antes de ele sair. Um novo envio a substitui: a de envios anteriores fica só no Console do Postman.
allow_writesVeja Escritas fora da homologação.

Roteiro em homologação ​

  1. Cotação: offers → Quote an offer: payment methods, instalments and totals mostra os métodos e os totais da oferta.
  2. Cobrança Pix: charges → Create a charge já vem com um corpo de Pix. A resposta 201 traz status: "pending" e o QR em payment.qr_code; o charge_id fica guardado.
  3. Mesma tentativa de novo: copie last_attempt_key para idempotency_key e envie de novo. A resposta é a mesma cobrança, com o cabeçalho Idempotent-Replayed: true. É o que fazer quando um envio fica sem resposta: repetir a mesma chave, nunca enviar de novo com uma chave nova, e só nos primeiros 10 minutos depois do primeiro envio. Depois disso, procure a cobrança pela listagem (passo 4) antes de qualquer coisa.
  4. Consulta e busca: charges → Retrieve a charge responde o estado atual. Em charges → List your charges, newest first, ligue o filtro metadata[attempt_id], que usa last_attempt_key: a listagem acha a cobrança pela chave da tentativa, como na reconciliação.
  5. Fim: esvazie idempotency_key, ou toda cobrança seguinte repete essa tentativa.

Respostas que você pode ver ao repetir uma chave:

  • 409 idempotency_key_in_use, enquanto o primeiro envio ainda está rodando (até uns 2 minutos);
  • o estado atual da cobrança, sem Idempotent-Replayed, quando o primeiro envio terminou sem resposta guardada;
  • 409 idempotency_key_unresolved, quando nem isso existe: pode ter cobrado; procure pela listagem, como no passo 4;
  • 409 idempotency_key_reuse, se algo além do cartão mudou no corpo, como o comprador: volte o corpo ao do primeiro envio;
  • 409 idempotency_key_expired, mais de 24 horas depois.

Os avisos de checkout dessa cobrança vão para o destino de checkout que o time configurou para o seu cliente.

Cartão não entra no Postman: o token do cartão só sai do navegador, pelo SDK. Para testar cartão, use o checkout de referência ou a sua própria página com a chave pk_test_….

Com o Turnstile ligado no seu cliente, toda cobrança pede o cabeçalho cf-turnstile-token, e o Postman não resolve o desafio. Resolva o desafio na sua página de homologação, copie o token (por exemplo, do challenge.getToken() no console do navegador) para turnstile_token e envie a cobrança em até uns 5 minutos: com turnstile_token preenchido, a coleção liga o cabeçalho sozinha. Cada token serve a poucas cobranças; resolva outro quando a resposta for 403 turnstile_*.

Escritas fora da homologação ​

Em produção, cada envio é real: uma cobrança cobra o comprador e avisa o seu webhook de produção, um estorno devolve dinheiro, um cancelamento encerra uma assinatura e um destino de webhook removido deixa de receber avisos. Por isso a coleção só envia uma escrita (tudo que não é GET, menos a busca de pagamento reutilizável) quando a requisição vai para a homologação e com uma chave _test_. Qualquer outra combinação é bloqueada antes de sair, com um aviso no Console, inclusive num ambiente que você copiou e trocou o endereço ou a chave.

Para enviar uma escrita em produção, mude allow_writes para true, envie uma requisição e volte para false. Nunca rode a coleção inteira (Run) com allow_writes ligado.

  • Use o ambiente de produção para consultas: o estado de uma cobrança, a listagem, uma assinatura.
  • Troque o comprador do corpo da cobrança pelo seu antes de cobrar em produção: o exemplo usa um CPF de teste, e uma cobrança paga com ele emite nota fiscal nesse CPF.
  • Cada envio da cobrança é uma tentativa nova. Um segundo envio depois de um tempo esgotado cobra de novo: para repetir, copie last_attempt_key para idempotency_key, nos primeiros 10 minutos; depois, procure a cobrança pela listagem.
  • A listagem e a consulta com a chave secreta respondem os dados completos do comprador, que ficam no histórico do Postman.
  • Nunca grave a chave sk_live_… no shared value nem exporte o ambiente com ela.

Os arquivos do kit são gerados quando o site é publicado. Numa cópia local do site sem a especificação da API, os links acima não existem.