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.

Quick Start

Go live in 3 steps

From API key to first payment in minutes. No complex onboarding, no vendor-specific frameworks.

1

Get API Credentials

Register in the sandbox, receive your client_id and client_secret. OAuth 2.0 token is issued automatically.

2

Make Your First Call

Use the curl example below or install an SDK. All endpoints follow RESTful conventions with JSON payloads.

3

Move to Production

After sandbox testing, switch the base URL and use production credentials. Zero code changes required.

curl 
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"
  }'
REST API

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 Shared 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 API

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

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 — 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)
SDKs

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

Maven
<dependency> <groupId>cv.paymart</groupId> <artifactId>paymart-sdk</artifactId> <version>1.2.0</version> </dependency>

Python

pip
pip install paymart-sdk

Node.js

npm
npm install @paymart/sdk

PHP

Composer
composer require paymart/sdk-php

C#

NuGet
dotnet add package Paymart.Sdk
Developer Resources

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.

Request API Access Contact Sales