Introdução

Bem-vindo à documentação da API Pública da SyncPay.

Através dela você integra o processamento de pagamentos da SyncPay diretamente ao
seu sistema: cobranças via PIX, cobranças via cartão de crédito, tokenização de
cartões, consulta de saldo e de transações, solicitação de reembolso, planos de
assinatura e recebimento de notificações por webhook.

Host de produção

Todas as requisições devem ser feitas para o host de produção abaixo:

https://api.syncpayments.com.br

Os endpoints da API pública ficam sob o prefixo /api/partner/v1. Ou seja, a URL
base completa das chamadas é:

https://api.syncpayments.com.br/api/partner/v1

Importante: a API é servida exclusivamente por HTTPS. Requisições em
HTTP não são atendidas. Sempre utilize o host acima — não existe outro domínio
oficial para a API pública.

Credenciais

Para consumir a API você precisa de um par de credenciais gerado no painel da
SyncPay:

Credencial	Descrição
`client_id`	Identificador público da sua aplicação.
`client_secret`	Segredo da aplicação. Nunca exponha em front-end ou repositório.

O client_secret é exibido apenas no momento da criação. Guarde-o em um cofre de
segredos ou em variável de ambiente do seu servidor.

Autenticação

A autenticação é feita em duas etapas:

Troque client_id + client_secret por um access token no endpoint
POST /api/partner/v1/auth-token.

Envie esse token no header Authorization de todas as demais chamadas.

1. Obtendo o access token

Resposta (200 OK):

{
  "access_token": "1|AbCdEf...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-01-01T12:00:00.000000Z"
}

Se as credenciais forem inválidas, a resposta é 401 Unauthorized:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

2. Usando o access token

O token tem validade de 3600 segundos (1 hora). Reaproveite o mesmo token
durante esse período e gere um novo somente quando ele expirar — não solicite um
token novo a cada requisição.

Headers obrigatórios

Header	Valor	Quando
`Authorization`	`Bearer <access_token>`	Em todos os endpoints, exceto `auth-token`.
`Content-Type`	`application/json`	Em requisições com corpo (POST/PUT/PATCH).
`Accept`	`application/json`	Recomendado em todas as requisições.

A API responde sempre em JSON, mesmo em caso de erro.

Primeira cobrança (PIX)

Exemplo mínimo de criação de uma cobrança PIX:

Resposta (200 OK):

{
  "message": "Cashin request successfully submitted",
  "pix_code": "00020126...",
  "identifier": "a1b2c3d4-e5f6-..."
}

O campo pix_code é o payload do PIX Copia e Cola — use-o para gerar o QR Code no
seu checkout. O identifier é o identificador da transação, usado para consulta
posterior e recebido também nos webhooks.

Consultando uma transação

Webhooks

A consulta por polling não é o caminho recomendado para acompanhar o status de uma
cobrança. Cadastre um webhook e receba as mudanças de status assim que
ocorrerem.

Você pode:

Cadastrar e gerenciar webhooks pelos endpoints /api/partner/v1/webhooks;

Ou informar uma webhook_url no corpo da própria cobrança, para notificar
apenas aquela transação.

Consulte a seção Webhooks desta documentação para o formato do payload, os
eventos disponíveis e a verificação de assinatura.

Valores e datas

Valores monetários são enviados e retornados em reais, com até duas casas
decimais (ex.: 49.90). O valor mínimo de uma cobrança é 1.00.

Datas e horários seguem o padrão ISO 8601 em UTC, com o sufixo Z
(ex.: 2026-01-01T12:00:00.000000Z). Converta para o fuso do usuário apenas na
camada de apresentação.

Limites de requisição (rate limit)

A API aplica limite de 500 requisições por minuto por conta autenticada. Ao
ultrapassar o limite, a resposta é 429 Too Many Requests.

Alguns endpoints sensíveis possuem limites próprios, mais restritos, indicados na
documentação de cada um.

Códigos de resposta

Código	Significado
`200`	Sucesso.
`201`	Recurso criado.
`401`	Não autenticado — token ausente, inválido ou expirado.
`403`	Sem permissão para o recurso.
`404`	Recurso não encontrado.
`422`	Dados inválidos ou conta ainda não habilitada para a operação.
`429`	Limite de requisições excedido.
`500`	Erro interno. Tente novamente e, se persistir, acione o suporte.

Erros de validação (422) seguem o formato padrão:

{
  "message": "The amount field is required.",
  "errors": {
    "amount": ["The amount field is required."]
  }
}

Requisitos da conta

Para transacionar pela API, a conta precisa estar aprovada e com o cadastro
completo. Contas pendentes recebem 422 com a indicação do que falta:

{
  "message": "Your account is not approved yet. Please wait for approval.",
  "action": "wait_for_approval"
}

Boas práticas

Guarde o client_secret no servidor. Nunca no navegador, no app ou no
repositório de código.

Reaproveite o access token durante sua validade de 1 hora.

Persista o identifier de cada transação do seu lado para conciliação.

Implemente retentativa com espera progressiva (backoff) para respostas 429 e
5xx.

Suporte

Dúvidas sobre a integração? Fale com o time da SyncPay pelos canais de suporte ou
com o seu gerente de contas.

Host de produção#

Credenciais#

Autenticação#

1. Obtendo o access token#

2. Usando o access token#

Headers obrigatórios#

Primeira cobrança (PIX)#

Consultando uma transação#

Webhooks#

Valores e datas#

Limites de requisição (rate limit)#

Códigos de resposta#

Requisitos da conta#

Boas práticas#

Suporte#