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.
Da chave API ao primeiro pagamento em minutos. Sem onboarding complexo, sem frameworks específicos de fornecedor.
Registe-se no sandbox, receba o seu client_id e client_secret. O token OAuth 2.0 é emitido automaticamente.
Use o exemplo curl abaixo ou instale um SDK. Todos os endpoints seguem convenções RESTful com payloads JSON.
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" }'
Baseado em JSON, versionado e totalmente documentado. Construído sobre a especificação OpenAPI 3.0 com documentação interactiva.
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
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=...
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_...
| 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 |
| 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ó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 |
Suporte completo SOAP/WSDL para instituições com middleware existente, ESB, ou sistemas de banca central que requerem comunicação baseada em XML.
https://api.paymart.cv/soap/v1?wsdl
https://sandbox-api.paymart.cv/soap/v1?wsdl
| 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 |
<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>
| 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) |
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.
<dependency>
<groupId>cv.paymart</groupId>
<artifactId>paymart-sdk</artifactId>
<version>1.2.0</version>
</dependency>
pip install paymart-sdk
npm install @paymart/sdk
composer require
paymart/sdk-php
dotnet add package
Paymart.Sdk
Sandbox, monitorização de estado, changelog e acesso directo à nossa equipa de integração.
Sandbox gratuito com dados de teste, respostas simuladas e cobertura API completa. Sem cartão de crédito necessário.
Painel de uptime em tempo real com histórico de incidentes, métricas de latência e janelas de manutenção programada.
Notas de versão com alterações breaking, novos endpoints e calendário de depreciação. Acompanhe via RSS.
Engenheiros de integração dedicados, canal Slack e suporte de emergência 24/7 para problemas de produção.
Obtenha acesso API e comece a integrar o Paymart Suite na sua infraestrutura financeira. O sandbox é gratuito — credenciais de produção em 24 horas.