Localpayment para desenvolvedores

Construa em torno dos detalhes locais.

Encontre os guias da API, os requisitos de cada país, as ferramentas de teste e os exemplos de implementação por trás de cada fluxo de pagamento disponível.

Ir para a documentação Começar o guia rápido

REST + JSON
Webhooks assinados com HMAC
Stage (ambiente de testes)
Servidor MCP público

POST /api/payin/

curl -X POST https://api.stage.localpayment.com/api/payin/
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -d '{
    "externalId": "order-8f2k-1043",
    "paymentMethod": { "type": "BankTransfer", "code": "1314" },
    "country": "BRA", "currency": "BRL",
    "amount": 1250.00
  }'

O essencial para desenvolvedores

Documentação

Vá direto ao que você precisa

Atalhos para docs.localpayment.com: guias, referência da API e ferramentas.

Suas primeiras chamadas

Autentique, receba, confirme

Três passos cobrem o ciclo principal: obter um token, criar um pay-in e verificar o webhook assinado que o confirma. O mesmo modelo de requisição, status e webhooks se aplica a todos os países e meios de pagamento.

Os tokens expiram em 5 minutos: renove com POST /api/token/refresh/
Envie seu próprio externalId único em cada transação
O status final chega por webhook, assinado com HMAC-SHA256

Abrir a referência da API

# 1) Obtenha um token de acesso (Stage · válido por 5 minutos)
ACCESS_TOKEN=$(curl -s -X POST https://api.stage.localpayment.com/api/token/ \
  -H "Content-Type: application/json" \
  -d "{\"username\": \"$LP_API_USER\", \"password\": \"$LP_API_PASSWORD\"}" \
  | jq -r .access)

# 2) Crie um pay-in Pix (ilustrativo, valores fictícios)
curl -X POST https://api.stage.localpayment.com/api/payin/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": { "type": "BankTransfer", "code": "1314", "flow": "DIRECT" },
    "externalId": "7c1e2f7a-0000-4000-8000-000000000001",
    "country": "BRA",
    "currency": "USD",
    "amount": 100,
    "accountNumber": "<your-account-number>",
    "conceptCode": "0003",
    "merchant": { "type": "COMPANY", "name": "Nortia Commerce Ltda" },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "Maria",
      "lastname": "Silva",
      "document": { "type": "CPF", "id": "000.000.000-00" }
    }
  }'

Design da API

Previsível por design

Convenções que se mantêm iguais entre produtos e países, para que o seu código de integração também se mantenha.

REST e JSON
URLs orientadas a recursos, verbos e códigos HTTP padrão e corpos JSON. Os países usam códigos ISO-3, como BRA ou MEX.
Tokens Bearer de curta duração
POST /api/token/ retorna um token de acesso válido por 5 minutos e um de renovação válido por 24 horas, enviado como Authorization: Bearer.
Seu ID e o nosso
Cada transação leva o seu externalId, e nós retornamos o nosso internalId. Use qualquer um para consultar o status ou conciliar.
À prova de duplicidade
Reutilizar um externalId retorna 409 Conflict em vez de criar uma segunda transação, então você pode repetir com segurança uma requisição que expirou.
Códigos para decidir
Toda resposta traz um objeto status com code, description e detail, além de um array errors. As famílias de códigos dizem o que fazer.
Limites de requisições com backoff
Excesso de requisições retorna 429. Tente de novo com backoff exponencial e um padrão circuit breaker, assim como em respostas 5xx e no código 800.

Tratamento de erros

Famílias de códigos de status

Toda resposta inclui status.code. O primeiro dígito diz se você deve esperar, corrigir, tentar de novo ou reverter.

1xx
Significado
Pendente
Exemplos
100 INPROGRESS
O que fazer
Aguarde o webhook ou consulte o status
2xx
Significado
Sucesso
Exemplos
200 COMPLETED
O que fazer
Libere o pedido e atualize sua contabilidade
3xx
Significado
Validação
Exemplos
300 rejeitado (parâmetro inválido) · 301 não autorizado para o país
O que fazer
Corrija a requisição: não a reenvie sem alterações
7xx
Significado
Regras de negócio
Exemplos
701 conta inválida · 702 saldo insuficiente
O que fazer
Mostre uma mensagem clara ou alerte sua equipe de operações
8xx
Significado
Provedor ou sistema
Exemplos
800 erro com retentativa
O que fazer
Tente de novo com backoff exponencial
9xx
Significado
Reversões
Exemplos
902 reembolsado · 904 assinatura cancelada após tentativas falhas · 906 chargeback
O que fazer
Reverta a entrega e atualize sua contabilidade

Família	Significado	Exemplos	O que fazer
1xx	Pendente	100 INPROGRESS	Aguarde o webhook ou consulte o status
2xx	Sucesso	200 COMPLETED	Libere o pedido e atualize sua contabilidade
3xx	Validação	300 rejeitado (parâmetro inválido) · 301 não autorizado para o país	Corrija a requisição: não a reenvie sem alterações
7xx	Regras de negócio	701 conta inválida · 702 saldo insuficiente	Mostre uma mensagem clara ou alerte sua equipe de operações
8xx	Provedor ou sistema	800 erro com retentativa	Tente de novo com backoff exponencial
9xx	Reversões	902 reembolsado · 904 assinatura cancelada após tentativas falhas · 906 chargeback	Reverta a entrega e atualize sua contabilidade

Status HTTP em uso: 200, 201, 400, 401, 403, 404, 409, 429, 500, 502 e 503. As tabelas de códigos por tipo de transação estão na referência da documentação.

Jornada de integração

Da primeira chamada à produção

A maior parte do trabalho acontece no Stage. O acesso à produção vem após uma revisão de segurança e a verificação da sua empresa.

01
Receba credenciais do Stage
As credenciais do Stage são emitidas no início da parceria. Cadastre os IPs dos seus servidores no Business Portal.
Stage
02
Construa e teste
Integre pay-ins, payouts ou contas virtuais, processe webhooks e teste cenários de falha com dados de teste.
Stage
03
Revisão de segurança e KYB
Revisamos sua integração e concluímos a verificação da empresa (KYB) antes de emitir as credenciais de produção.
Compliance
04
Entre em produção e expanda
Troque para credenciais e IPs de produção. Países e métodos novos usam a mesma API.
Produção

Ferramentas de IA

Deixe seu assistente de IA ler a documentação

A documentação da Localpayment foi feita para funcionar com ferramentas de desenvolvimento assistido por IA, incluindo um servidor MCP, prompts prontos para usar e acesso estruturado pensado para sistemas de IA.

Servidor MCP em docs.localpayment.com/mcp, sem autenticação
Um índice llms.txt e uma versão em Markdown de cada página
Uma biblioteca de prompts e agentes de integração e QA para os frameworks de agentes mais usados
“Ask AI” integrado à documentação

Conheça as ferramentas de IA

{
  "mcpServers": {
    "localpayment-docs": {
      "url": "https://docs.localpayment.com/mcp"
    }
  }
}

Segurança

Seguro por padrão, desde a primeira requisição

Controles embutidos na API e no Business Portal, não adicionados depois.

Criptografia em trânsito e em repouso
TLS 1.2+ em trânsito e AES-256 em repouso, com rotação de chaves pelo AWS KMS.
Somente servidor a servidor
As chamadas trafegam por HTTPS a partir do seu backend. Nunca exponha credenciais ou tokens em um navegador ou app.
Lista de IPs permitidos
Somente os IPs de servidor cadastrados no Business Portal podem chamar a API, no Stage e na produção.
Webhooks assinados
Cada notificação traz uma assinatura HMAC-SHA256, para você rejeitar tudo o que não foi enviado por nós.
Payouts com dupla assinatura
Exija um segundo aprovador antes de um payout sair da sua conta, pela API ou no portal.
MFA e acesso por perfis
Os usuários do Business Portal entram com autenticação multifator e têm apenas as permissões que o perfil exige.

Perguntas frequentes de desenvolvedores

Existe um SDK?

Não há SDKs oficiais de servidor: a API é REST e JSON, então qualquer cliente HTTP funciona. Para formulários de cartão, o SDK JavaScript Smart Fields tokeniza os dados em campos hospedados e reduz seu escopo PCI.

Como obtenho credenciais do Stage?

As credenciais do Stage são emitidas no início da parceria. Conte sobre o seu projeto no formulário de contato e nossa equipe vai acompanhar você no credenciamento.

Quais URLs base devo usar?

Stage: https://api.stage.localpayment.com. Produção: https://api.v3.localpayment.com. Cada ambiente tem as próprias credenciais.

Quanto tempo leva uma integração?

As equipes costumam entrar em produção em semanas. Depois de integrado, novos mercados usam a mesma API.

Como funcionam retentativas e duplicidades?

Envie um externalId único por transação. Se você reenviar com o mesmo externalId, recebe 409 Conflict em vez de uma duplicidade. Tente de novo 429, 5xx e o código 800 com backoff exponencial.

Onde vejo a saúde do serviço?

Em status.localpayment.com, que cobre os serviços de pay-in, payout e autenticação, os trilhos locais e o histórico de incidentes. Se precisar de ajuda, escreva para support@localpayment.com: o suporte funciona 24/7.

Construa em torno dos detalhes locais.

O essencial para desenvolvedores

Guias

Referência da API

Ferramentas para desenvolvedores

Página de status

Vá direto ao que você precisa

Autenticação

Seu primeiro pagamento de teste

Pay-ins

Payouts

Contas virtuais

Webhooks

Status e códigos de erro

Coleção do Postman

Status do sistema

Autentique, receba, confirme

Previsível por design

REST e JSON

Tokens Bearer de curta duração

Seu ID e o nosso

À prova de duplicidade

Códigos para decidir

Limites de requisições com backoff

Famílias de códigos de status

Da primeira chamada à produção

Receba credenciais do Stage

Construa e teste

Revisão de segurança e KYB

Entre em produção e expanda

Deixe seu assistente de IA ler a documentação

Seguro por padrão, desde a primeira requisição

Criptografia em trânsito e em repouso

Somente servidor a servidor

Lista de IPs permitidos

Webhooks assinados

Payouts com dupla assinatura

MFA e acesso por perfis

Perguntas frequentes de desenvolvedores

Guias para desenvolvedores

Guia rápido

Ambiente Stage

Webhooks

Ferramentas de IA

Roadmap

Business Portal

Pronto para construir?