API Documentation
Complete reference for Paymart Suite's REST and SOAP interfaces. Server-to-server integration for payments, accounts, cards, FX, and compliance — built for financial institutions that need reliability and speed.
Go live in 3 steps
From API key to first payment in minutes. No complex onboarding, no vendor-specific frameworks.
Get API Credentials
Register in the sandbox, receive your client_id and client_secret. OAuth 2.0 token is issued automatically.
Make Your First Call
Use the curl example below or install an SDK. All endpoints follow RESTful conventions with JSON payloads.
Move to Production
After sandbox testing, switch the base URL and use production credentials. Zero code changes required.
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" }'
RESTful integration for modern systems
JSON-based, versioned, and fully documented. Built on OpenAPI 3.0 specification with interactive documentation.
Authentication
OAuth 2.0 Client Credentials
Standard two-legged OAuth for server-to-server. Exchange client_id + client_secret for a Bearer token. Token expires in 3600s.
POST /oauth/token
grant_type=client_credentials
OpenID Connect
For user-context operations. Authorization code flow with PKCE. Includes id_token with user claims and scope-based access.
GET /oauth/authorize
response_type=code
&code_challenge=...
API Key (Sandbox)
Quick testing in sandbox environment. Pass X-API-Key header. Not supported in production — use OAuth 2.0 instead.
GET /v1/accounts
X-API-Key: sk_test_...
Core Endpoints
| Method | Endpoint | Description |
|---|---|---|
| Accounts & IBAN | ||
| GET | /v1/accounts | List all accounts |
| POST | /v1/accounts | Create a new account |
| GET | /v1/accounts/{id} | Get account details |
| GET | /v1/accounts/{id}/balance | Get account balance |
| POST | /v1/iban/validate | Validate IBAN format |
| Payments | ||
| POST | /v1/payments/sepa | Initiate SEPA credit transfer |
| POST | /v1/payments/swift | Initiate SWIFT payment |
| GET | /v1/payments/{id} | Get payment status |
| GET | /v1/payments | List payments with filters |
| POST | /v1/payments/{id}/cancel | Cancel a pending payment |
| Cards | ||
| POST | /v1/cards/issue | Issue a new card |
| GET | /v1/cards/{id} | Get card details |
| PUT | /v1/cards/{id}/status | Block or unblock card |
| GET | /v1/cards/{id}/transactions | List card transactions |
| PATCH | /v1/cards/{id}/limits | Update card spending limits |
| Foreign Exchange | ||
| GET | /v1/fx/rates | Get current exchange rates |
| POST | /v1/fx/quote | Request FX quote |
| POST | /v1/fx/execute | Execute FX conversion |
| Compliance | ||
| POST | /v1/kyc/verify | Submit KYC verification |
| POST | /v1/aml/screen | AML screening request |
| GET | /v1/compliance/report | Generate compliance report |
| GET | /v1/compliance/audit-trail | Retrieve audit trail |
| Webhooks | ||
| POST | /v1/webhooks | Register webhook endpoint |
| GET | /v1/webhooks | List registered webhooks |
| DELETE | /v1/webhooks/{id} | Delete a webhook |
| POST | /v1/webhooks/{id}/test | Send test event |
| GET | /v1/webhooks/{id}/logs | List webhook delivery logs |
| POST | /v1/webhooks/{id}/retry | Retry failed delivery |
Rate Limits
| Plan | Rate Limit | Burst |
|---|---|---|
| Sandbox | 100 req/min |
150 |
| SaaS Monthly | 1,000 req/min |
1,500 |
| SaaS Dedicated | 5,000 req/min |
7,500 |
| License | Unlimited* | N/A |
* License plan rate limits depend on your infrastructure capacity. Contact support for custom configurations.
Error Codes
| Code | Type | Description |
|---|---|---|
| 400 | Bad Request | Invalid request body, missing required fields, or malformed JSON |
| 401 | Unauthorized | Invalid or expired access token |
| 403 | Forbidden | Insufficient scope or permissions for this operation |
| 404 | Not Found | Requested resource does not exist |
| 422 | Unprocessable Entity | Validation failed — see errors array in response |
| 429 | Too Many Requests | Rate limit exceeded. Retry after Retry-After header value |
| 500 | Internal Server Error | Unexpected server error. Contact support with request_id |
| PS01 | Insufficient Funds | Debtor account does not have sufficient balance |
| PS02 | Compliance Hold | Transaction blocked by AML/KYC rules |
| PS03 | Duplicate Reference | Payment reference already used — use idempotency key |
| PS04 | Cut-off Time | Payment submitted after SEPA/SWIFT cut-off, queued for next window |
SOAP interface for legacy integration
Full SOAP/WSDL support for institutions with existing middleware, ESB, or core banking systems that require XML-based communication.
WSDL Endpoints
Production
https://api.paymart.cv/soap/v1?wsdl
Sandbox
https://sandbox-api.paymart.cv/soap/v1?wsdl
Supported Operations
| Operation | Description |
|---|---|
CreateAccount |
Open a new account with IBAN generation |
GetAccount |
Retrieve account details and balance |
InitiatePayment |
Submit SEPA, SWIFT, or internal payment |
GetPaymentStatus |
Query current status of a payment |
IssueCard |
Issue debit or prepaid card |
GetFxRate |
Retrieve real-time foreign exchange rate |
ExecuteFxConversion |
Perform currency conversion |
VerifyKYC |
Submit and verify KYC documents |
ScreenAML |
Run AML screening on a party |
XML Request Example
<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 — When to Use Each
| Aspect | REST | SOAP |
|---|---|---|
| Protocol | HTTP/JSON | XML/SOAP Envelope |
| Best For | New integrations, mobile, web apps | Legacy core banking, ESB middleware |
| Performance | Lightweight, low latency | Heavier payload, WS-Security overhead |
| Authentication | OAuth 2.0 Bearer token | WS-Security, X.509 certificates |
| Error Handling | HTTP status codes + JSON body | SOAP Fault elements |
| Contract | OpenAPI 3.0 (Swagger) | WSDL (machine-readable contract) |
Official client libraries
Drop-in SDKs for five major languages. Type-safe models, automatic retry, and built-in pagination — so you focus on business logic.
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
Everything you need to build
Sandbox, status monitoring, changelog, and direct access to our integration team.
Sandbox
Free sandbox with test data, mock responses, and full API coverage. No credit card required.
API Status
Real-time uptime dashboard with incident history, latency metrics, and scheduled maintenance windows.
Changelog
Versioned release notes with breaking changes, new endpoints, and deprecation schedules. Follow via RSS.
Support
Dedicated integration engineers, Slack channel, and 24/7 emergency support for production issues.
Ready to Build?
Get API access and start integrating Paymart Suite into your financial infrastructure. Sandbox is free — production credentials in 24 hours.