Back to Portal
Get Started
Payments API

Payments API Reference

Process payments, manage transactions, and handle virtual IBANs with enterprise-grade security. Support for cards, bank transfers, and instant payment confirmations.

Overview

The Payments API provides comprehensive payment processing capabilities including card payments, bank transfers, virtual IBAN generation, and real-time payment confirmations. All transactions are processed with bank-grade security and full compliance with financial regulations.

Multiple Methods

Cards, bank transfers, virtual IBANs, and digital wallets

PCI Compliant

Full PCI DSS compliance and end-to-end encryption

Real-time

Instant payment confirmations and status updates

POSTCreate Payment

Process a payment using cards, bank transfer, or virtual IBAN

Endpoint

POST /payments

Request Body (Card Payment)

{
  "amount": 1000.00,
  "currency": "USD",
  "payment_method": "card",
  "payer": {
    "user_id": "usr_1a2b3c4d5e6f",
    "email": "payer@example.com"
  },
  "recipient": {
    "user_id": "usr_7g8h9i0j1k2l", 
    "email": "recipient@example.com"
  },
  "card_details": {
    "card_number": "4242424242424242",
    "expiry_month": "12",
    "expiry_year": "2025", 
    "cvc": "123",
    "cardholder_name": "John Doe"
  },
  "description": "Payment for website development",
  "reference": "INV-2024-001",
  "metadata": {
    "order_id": "ord_abc123",
    "customer_id": "cust_xyz789"
  }
}

Request Body (Bank Transfer)

{
  "amount": 2500.00,
  "currency": "EUR",
  "payment_method": "bank_transfer",
  "payer": {
    "user_id": "usr_1a2b3c4d5e6f",
    "email": "payer@example.com"
  },
  "recipient": {
    "user_id": "usr_7g8h9i0j1k2l",
    "email": "recipient@example.com"
  },
  "bank_details": {
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "account_holder": "John Doe"
  },
  "description": "Contract milestone payment",
  "reference": "CONTRACT-001-M1"
}

Response (201 Created)

{
  "success": true,
  "data": {
    "payment_id": "pay_1a2b3c4d5e6f7g8h",
    "status": "processing",
    "amount": 1000.00,
    "currency": "USD",
    "payment_method": "card",
    "payer": {
      "user_id": "usr_1a2b3c4d5e6f",
      "email": "payer@example.com"
    },
    "recipient": {
      "user_id": "usr_7g8h9i0j1k2l",
      "email": "recipient@example.com"
    },
    "fees": {
      "platform_fee": 25.00,
      "processing_fee": 15.00,
      "total_fees": 40.00
    },
    "net_amount": 960.00,
    "expected_completion": "2024-01-15T10:35:00Z",
    "reference": "INV-2024-001",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_1a2b3c4d5e6f",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

GETGet Payment

Retrieve payment details and current status

Endpoint

GET /payments/{payment_id}

Response (200 OK)

{
  "success": true,
  "data": {
    "payment_id": "pay_1a2b3c4d5e6f7g8h",
    "status": "completed",
    "amount": 1000.00,
    "currency": "USD",
    "payment_method": "card",
    "payer": {
      "user_id": "usr_1a2b3c4d5e6f",
      "email": "payer@example.com",
      "name": "John Doe"
    },
    "recipient": {
      "user_id": "usr_7g8h9i0j1k2l",
      "email": "recipient@example.com",
      "name": "Jane Developer"
    },
    "transaction_details": {
      "transaction_id": "txn_9i8h7g6f5e4d",
      "confirmation_code": "CONF123456",
      "processor_reference": "proc_ref_789"
    },
    "fees": {
      "platform_fee": 25.00,
      "processing_fee": 15.00,
      "total_fees": 40.00
    },
    "net_amount": 960.00,
    "completed_at": "2024-01-15T10:32:15Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

POSTGenerate Virtual IBAN

Create a virtual IBAN for receiving payments

Endpoint

POST /payments/virtual-iban

Request Body

{
  "user_id": "usr_1a2b3c4d5e6f",
  "currency": "EUR",
  "purpose": "contract_payments",
  "reference": "CONTRACT-001",
  "auto_forward": true,
  "forward_to": {
    "iban": "DE89370400440532013000",
    "account_holder": "Main Business Account"
  },
  "metadata": {
    "contract_id": "ctr_1a2b3c4d5e6f",
    "client": "Acme Corp"
  }
}

Response (201 Created)

{
  "success": true,
  "data": {
    "virtual_iban_id": "viban_1a2b3c4d5e6f",
    "iban": "DE89370400440532013001",
    "bic": "WAFFYDEBXXX",
    "account_holder": "Waffy Virtual Account",
    "reference": "CONTRACT-001",
    "currency": "EUR",
    "status": "active",
    "balance": 0.00,
    "auto_forward": true,
    "forward_to": {
      "iban": "DE89370400440532013000",
      "account_holder": "Main Business Account"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-01-15T10:30:00Z"
  }
}

GETList Payments

Retrieve a list of payments with filtering options

Endpoint

GET /payments

Query Parameters

ParameterTypeDescription
statusstringFilter by status: pending, processing, completed, failed
user_idstringFilter by payer or recipient user ID
payment_methodstringFilter by payment method: card, bank_transfer, virtual_iban
date_fromstringFilter payments from date (ISO 8601 format)
date_tostringFilter payments up to date (ISO 8601 format)
limitintegerNumber of results to return (max 100, default 20)

Payment Statuses

Understanding the payment lifecycle

pending
Payment has been created but not yet processed
processing
Payment is being processed by the payment provider
completed
Payment has been successfully processed and funds transferred
failed
Payment failed due to insufficient funds, declined card, or other error

Supported Countries & Currencies

Card Payments

• Global coverage (190+ countries)
• Major card networks: Visa, Mastercard, Amex
• 50+ currencies supported
• 3D Secure authentication

Bank Transfers

• SEPA transfers (EU)
• UK Faster Payments
• US ACH transfers
• SWIFT international transfers

Common Errors

400 Bad Request - Card Declined

{
  "success": false,
  "error": {
    "code": "CARD_DECLINED",
    "message": "Your card was declined. Please check your card details or try a different card.",
    "details": {
      "decline_code": "insufficient_funds",
      "processor_message": "Not sufficient funds"
    }
  }
}

402 Payment Required - Insufficient Balance

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance in virtual IBAN account",
    "details": {
      "available_balance": 500.00,
      "required_amount": 1000.00,
      "currency": "EUR"
    }
  }
}

Payment Integration Guide

Learn how to integrate payments into your application

View Guide

Test Cards & Scenarios

Use test card numbers for development and testing

View Test Data