Documentação API
Referência completa das interfaces REST e SOAP do Paymart Suite. Integração servidor-a-servidor para pagamentos, contas, cartões, FX e conformidade — construída para instituições financeiras que necessitam de fiabilidade e velocidade.
Entre em produção em 3 passos
Da chave API ao primeiro pagamento em minutos. Sem onboarding complexo, sem frameworks específicos de fornecedor.
Obter Credenciais API
Registe-se no sandbox, receba o seu client_id e client_secret. O token OAuth 2.0 é emitido automaticamente.
Faça a Sua Primeira Chamada
Use o exemplo curl abaixo ou instale um SDK. Todos os endpoints seguem convenções RESTful com payloads JSON.
Passar para Produção
Após testes no sandbox, altere o URL base e use credenciais de produção. Zero alterações de código necessárias.
curl -X POST https://api.paymart.cv/v1/payments/sepa \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "debtor_iban": "CV640003000012345678901", "creditor_iban": "PT500027000012345678901", "amount": 1500.00, "currency": "EUR", "reference": "INV-2026-0042" }'
Integração RESTful para sistemas modernos
Baseado em JSON, versionado e totalmente documentado. Construído sobre a especificação OpenAPI 3.0 com documentação interactiva.
Autenticação
OAuth 2.0 Client Credentials
OAuth padrão de duas pernas para servidor-a-servidor. Troque client_id + client_secret por um token Bearer. O token expira em 3600s.
POST /oauth/token
grant_type=client_credentials
OpenID Connect
Para operações em contexto de utilizador. Fluxo de código de autorização com PKCE. Inclui id_token com claims do utilizador e acesso baseado em scopes.
GET /oauth/authorize
response_type=code
&code_challenge=...
Chave API (Sandbox)
Testes rápidos no ambiente sandbox. Passe o header X-API-Key. Não suportado em produção — use OAuth 2.0 em vez disso.
GET /v1/accounts
X-API-Key: sk_test_...
Endpoints Principais
| Método | Endpoint | Descrição |
|---|---|---|
| Contas & IBAN | ||
| GET | /v1/accounts | Listar todas as contas |
| POST | /v1/accounts | Criar uma nova conta |
| GET | /v1/accounts/{id} | Obter detalhes da conta |
| GET | /v1/accounts/{id}/balance | Obter saldo da conta |
| POST | /v1/iban/validate | Validar formato IBAN |
| Pagamentos | ||
| POST | /v1/payments/sepa | Iniciar transferência SEPA |
| POST | /v1/payments/swift | Iniciar pagamento SWIFT |
| GET | /v1/payments/{id} | Obter estado do pagamento |
| GET | /v1/payments | Listar pagamentos com filtros |
| POST | /v1/payments/{id}/cancel | Cancelar um pagamento pendente |
| Cartões | ||
| POST | /v1/cards/issue | Emitir um novo cartão |
| GET | /v1/cards/{id} | Obter detalhes do cartão |
| PUT | /v1/cards/{id}/status | Bloquear ou desbloquear cartão |
| GET | /v1/cards/{id}/transactions | Listar transacções do cartão |
| PATCH | /v1/cards/{id}/limits | Actualizar limites de gastos do cartão |
| Câmbio | ||
| GET | /v1/fx/rates | Obter taxas de câmbio actuais |
| POST | /v1/fx/quote | Solicitar cotação de câmbio |
| POST | /v1/fx/execute | Executar conversão cambial |
| Conformidade | ||
| POST | /v1/kyc/verify | Submeter verificação KYC |
| POST | /v1/aml/screen | Pedido de rastreio AML |
| GET | /v1/compliance/report | Gerar relatório de conformidade |
| GET | /v1/compliance/audit-trail | Obter registo de auditoria |
| Webhooks | ||
| POST | /v1/webhooks | Registar endpoint de webhook |
| GET | /v1/webhooks | Listar webhooks registados |
| DELETE | /v1/webhooks/{id} | Eliminar um webhook |
| POST | /v1/webhooks/{id}/test | Enviar evento de teste |
| GET | /v1/webhooks/{id}/logs | Listar registos de entrega de webhook |
| POST | /v1/webhooks/{id}/retry | Retentar entrega falhada |
Limites de Taxa
| Plano | Limite de Taxa | Burst |
|---|---|---|
| Sandbox | 100 req/min |
150 |
| SaaS Partilhado | 1,000 req/min |
1.500 |
| SaaS Dedicado | 5,000 req/min |
7.500 |
| Licença | Ilimitado* | N/A |
* Os limites de taxa do plano Licença dependem da capacidade da sua infraestrutura. Contacte o suporte para configurações personalizadas.
Códigos de Erro
| Código | Tipo | Descrição |
|---|---|---|
| 400 | Pedido Inválido | Corpo do pedido inválido, campos obrigatórios em falta, ou JSON malformado |
| 401 | Não Autorizado | Token de acesso inválido ou expirado |
| 403 | Proibido | Scope ou permissões insuficientes para esta operação |
| 404 | Não Encontrado | O recurso solicitado não existe |
| 422 | Entidade Improcessável | Validação falhou — veja o array errors na resposta |
| 429 | Demasiados Pedidos | Limite de taxa excedido. Tente novamente após o valor do header Retry-After |
| 500 | Erro Interno do Servidor | Erro inesperado do servidor. Contacte o suporte com o request_id |
| PS01 | Fundos Insuficientes | A conta do devedor não tem saldo suficiente |
| PS02 | Bloqueio de Conformidade | Transacção bloqueada por regras AML/KYC |
| PS03 | Referência Duplicada | Referência de pagamento já utilizada — use chave de idempotência |
| PS04 | Hora Limite | Pagamento submetido após hora limite SEPA/SWIFT, em fila para a próxima janela |
Interface SOAP para integração legada
Suporte completo SOAP/WSDL para instituições com middleware existente, ESB, ou sistemas de banca central que requerem comunicação baseada em XML.
Endpoints WSDL
Produção
https://api.paymart.cv/soap/v1?wsdl
Sandbox
https://sandbox-api.paymart.cv/soap/v1?wsdl
Operações Suportadas
| Operação | Descrição |
|---|---|
CreateAccount |
Abrir uma nova conta com geração de IBAN |
GetAccount |
Obter detalhes e saldo da conta |
InitiatePayment |
Submeter pagamento SEPA, SWIFT ou interno |
GetPaymentStatus |
Consultar o estado actual de um pagamento |
IssueCard |
Emitir cartão de débito ou pré-pago |
GetFxRate |
Obter taxa de câmbio em tempo real |
ExecuteFxConversion |
Realizar conversão de moeda |
VerifyKYC |
Submeter e verificar documentos KYC |
ScreenAML |
Executar rastreio AML sobre uma entidade |
Exemplo de Pedido XML
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pay="http://api.paymart.cv/soap/v1"> <soapenv:Header/> <soapenv:Body> <pay:InitiatePayment> <pay:debtorIban>CV640003000012345678901</pay:debtorIban> <pay:creditorIban>PT500027000012345678901</pay:creditorIban> <pay:amount>1500.00</pay:amount> <pay:currency>EUR</pay:currency> <pay:reference>INV-2026-0042</pay:reference> <pay:paymentType>SEPA</pay:paymentType> </pay:InitiatePayment> </soapenv:Body> </soapenv:Envelope>
SOAP vs REST — Quando Usar Cada Um
| Aspecto | REST | SOAP |
|---|---|---|
| Protocolo | HTTP/JSON | XML/SOAP Envelope |
| Ideal Para | Novas integrações, mobile, web apps | Banca central legada, middleware ESB |
| Performance | Leve, baixa latência | Payload mais pesado, overhead de WS-Security |
| Autenticação | Token Bearer OAuth 2.0 | WS-Security, certificados X.509 |
| Tratamento de Erros | Códigos de estado HTTP + corpo JSON | Elementos SOAP Fault |
| Contrato | OpenAPI 3.0 (Swagger) | WSDL (contrato legível por máquina) |
Bibliotecas oficiais de cliente
SDKs de integração para cinco linguagens principais. Modelos type-safe, retry automático e paginação integrada — para se concentrar na lógica de negócio.
Java
<dependency>
<groupId>cv.paymart</groupId>
<artifactId>paymart-sdk</artifactId>
<version>1.2.0</version>
</dependency>
Python
pip install paymart-sdk
Node.js
npm install @paymart/sdk
PHP
composer require
paymart/sdk-php
C#
dotnet add package
Paymart.Sdk
Tudo o que precisa para construir
Sandbox, monitorização de estado, changelog e acesso directo à nossa equipa de integração.
Sandbox
Sandbox gratuito com dados de teste, respostas simuladas e cobertura API completa. Sem cartão de crédito necessário.
Estado da API
Painel de uptime em tempo real com histórico de incidentes, métricas de latência e janelas de manutenção programada.
Changelog
Notas de versão com alterações breaking, novos endpoints e calendário de depreciação. Acompanhe via RSS.
Suporte
Engenheiros de integração dedicados, canal Slack e suporte de emergência 24/7 para problemas de produção.
API-First para a Era A2A
A mesma camada API que alimenta os seus módulos é a base para os pagamentos account-to-account, as finanças incorporadas e a automatização orientada por IA.
O Paymart Suite é API-first por design. Cada módulo - contas, pagamentos, cartões, FX, conformidade - expõe as mesmas interfaces REST e SOAP, pelo que não existe um caminho de integração separado para cada capacidade. Essa camada única é o que permite às instituições mover dinheiro account-to-account à medida que o mercado A2A cresce de cerca de 60 mil milhões para 186 mil milhões de transacções até 2029, sem refazer a integração à medida que os circuitos de cartões perdem quota.
Vemos aqui o maior erro de arquitectura nos sistemas financeiros mais antigos: cada capacidade traz consigo um contrato novo.
No Paymart, os mesmos endpoints que impulsionam as transferências SEPA e SWIFT estão prontos para o Open Banking. OAuth 2.0 e OpenID Connect estão incorporados, e a superfície API está estruturada para que fornecedores terceiros e agregadores de conta se possam ligar em condições standard. Como a camada é unificada, alimenta também as finanças incorporadas - os parceiros integram chamadas de pagamento, cartão e FX directamente nos seus próprios produtos - e dá aos agentes de IA um contrato limpo e versionado sobre o qual agir. Uma API, um contrato, em todos os canais. É simples: quando cada capacidade fala a mesma língua, o sistema cresce em semanas, não em trimestres.
Pronto para Construir?
Obtenha acesso API e comece a integrar o Paymart Suite na sua infraestrutura financeira. O sandbox é gratuito — credenciais de produção em 24 horas.