API de Link de Pagamento

Crie links de pagamento, consulte os dados de cada link e acompanhe as cobranças geradas por eles. O link pode ser compartilhado com o pagador, que conclui o pagamento no checkout da My Gateway.

Ambiente de produção#

Endpoints#

Autenticação#

Use o mesmo fluxo de autenticação das demais APIs. Envie Authorization e x-api-key em todas as chamadas de checkout, e Content-Type: application/json nas que têm corpo JSON.

Convenções#

Valores monetários#

• Na criação do link, os campos monetários são inteiros em centavos, sem separador decimal. Ex.: 15000 representa R$ 150,00.
• Nas respostas de consulta, os valores voltam em reais, como números decimais. Ex.: 150.0 representa R$ 150,00.
• Não envie valores monetários como texto ("15000") e não use vírgula decimal.

Datas#

• Na criação, envie validity em ISO 8601, de preferência em UTC, por exemplo 2027-04-03T23:59:59Z.
• A validade precisa estar no futuro.
• Nas consultas, as datas voltam no formato yyyy-MM-dd HH:mm:ss, sem offset explícito.

Identificadores#

O payment-link-id é o UUID retornado em data.id na criação do link. Exemplo: f4d8488c-aed0-4828-8b46-723ab7249f08.

Campos nulos#

Campos opcionais sem valor podem ser omitidos da resposta. Não dependa da presença de uma propriedade opcional com valor null.

Envelope de sucesso#

As respostas de sucesso trazem os dados em data. Na consulta de cobranças, data é uma lista.

{
  "data": {}
}

{
  "data": []
}

Fluxo recomendado#

1. 1

   Guarde as credenciais

   Armazene clientId, clientSecret e x-api-key em um cofre de segredos.

2. 2

   Autentique

   Gere o authData e solicite o token no endpoint de autenticação.

3. 3

   Crie o link

   Chame POST /payments/v1/checkout.

4. 4

   Guarde o ID e compartilhe o link

   Persista data.id como identificador do link e apresente ou compartilhe data.link com o pagador.

5. 5

   Consulte o link

   Use GET /payments/v1/checkout/{payment-link-id} quando precisar do estado do link.

6. 6

   Consulte as cobranças

   Use GET /payments/v1/checkout/charges/{payment-link-id}, com ?status=2 para ver só pagamentos confirmados. Uma lista vazia é um resultado válido.

7. 7

   Trate a autenticação

   Renove o token ao receber 401 Unauthorized e confira a x-api-key e as permissões ao receber 403 Forbidden.

Checklist antes de publicar#

1. Usar só as URLs públicas de produção, com o prefixo /payments.
2. Enviar Authorization e x-api-key em todas as chamadas de checkout.
3. Enviar JSON válido, sem comentários.
4. Enviar os valores de criação em centavos.
5. Enviar validity futura em ISO 8601.
6. Manter o mínimo e o máximo de parcelas entre 1 e 21.
7. Preencher main_title, title e description com textos diferentes entre si.
8. Enviar em accepted_payments_type só códigos válidos.
9. Se usar itens, garantir que a soma dos itens menos o desconto seja exatamente igual a value.
10. Persistir o payment-link-id retornado na criação.
11. Tratar campos opcionais ausentes nas respostas.
12. Não registrar credenciais, token ou x-api-key em logs.