API Documentation

Complete reference for the XRN Pay API

Overview

The XRN Pay API provides secure payment processing with built-in foreign exchange rate conversion. All API endpoints return JSON responses and use standard HTTP status codes.

Base URL

Authentication

API access requires JWT authentication. Sign up to receive your access token and start processing payments immediately.

Rate Limiting

Enterprise-grade rate limiting is implemented to ensure optimal performance and security for all users.

API Endpoints

GET /health

Check the health status of the API.

Response

{
  "status": "healthy",
  "message": "Welcome to XRN Pay"
}
                            

POST /v1/payments

Process a payment transaction with automatic FX conversion to USD.

Request Body

{
  "sender": "alice@example.com",
  "recipient": "bob@example.com",
  "amount": 100.50,
  "currency": "EUR"
}
                            

Request Parameters

Field	Type	Required	Description
`sender`	string	Yes	Valid email address of the sender
`recipient`	string	Yes	Valid email address of the recipient (must be different from sender)
`amount`	number	Yes	Payment amount (positive, max 2 decimal places)
`currency`	string	Yes	3-letter ISO currency code (e.g., USD, EUR, GBP)

Success Response (200)

{
  "success": true,
  "settlement_id": "123e4567-e89b-12d3-a456-426614174000",
  "fx_rate": 1.18,
  "settled_amount": 118.59
}
                            

Error Response (422)

{
  "error": "Validation failed",
  "message": [
    "Invalid sender email address",
    "Amount must be greater than 0"
  ]
}
                            

GET /v1/fx-rates/{source}/{target}

Get the current foreign exchange rate between two currencies.

Path Parameters

Parameter	Type	Description
`source`	string	Source currency code (e.g., EUR)
`target`	string	Target currency code (e.g., USD)

Success Response (200)

{
  "source": "EUR",
  "target": "USD",
  "rate": 1.18,
  "timestamp": "2024-01-01T00:00:00Z"
}
                            

HTTP Status Codes

Code	Description	Meaning
200	OK	Request successful
400	Bad Request	Invalid request format (e.g., malformed JSON)
404	Not Found	Endpoint does not exist
405	Method Not Allowed	HTTP method not supported for this endpoint
422	Unprocessable Entity	Request validation failed
500	Internal Server Error	Server encountered an error

Supported Currencies

The following currencies are supported for payment processing:

USD - US Dollar
EUR - Euro
GBP - British Pound
JPY - Japanese Yen
AUD - Australian Dollar

CAD - Canadian Dollar
CHF - Swiss Franc
CNY - Chinese Yuan
SEK - Swedish Krona
NZD - New Zealand Dollar

NOK - Norwegian Krone
COP - Colombian Peso
SGD - Singapore Dollar
HKD - Hong Kong Dollar
KRW - South Korean Won
INR - Indian Rupee

BRL - Brazilian Real
ZAR - South African Rand
MXN - Mexican Peso
TRY - Turkish Lira
PLN - Polish Zloty

Usage Examples

cURL Examples

Process a Payment

curl -X POST http://localhost:5000/v1/payments \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "alice@company.com",
    "recipient": "bob@vendor.com",
    "amount": 250.00,
    "currency": "EUR"
  }'
                        

Get FX Rate

curl -X GET http://localhost:5000/v1/fx-rates/EUR/USD

JavaScript Example

const paymentData = {
  sender: "alice@company.com",
  recipient: "bob@vendor.com",
  amount: 250.00,
  currency: "EUR"
};

fetch('/v1/payments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(paymentData)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
                        

Back to Home