Introduction - Paycrest

Welcome to the Paycrest API Reference. Here you’ll find detailed documentation for all available endpoints, including request/response formats, authentication, and integration tips.

For a quick start, see the Quickstart guide.
For OpenAPI playground, see the interactive API explorer below (if available).

The Paycrest Aggregator API provides a comprehensive interface for interacting with the Paycrest protocol. This API enables senders to create payment orders, providers to fulfill orders, and general access to protocol information.

Base URL

# Production
https://api.paycrest.io/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

API-Key: YOUR_API_KEY

Getting Your API Key

Register at app.paycrest.io
Complete KYC verification (required for compliance)
Access your API key in your dashboard

Your API key should be kept secure and never shared publicly. It’s used to authenticate all API requests and identify your account.

API Endpoints

The Paycrest API is organized into three main categories:

Sender Endpoints

For entities that create payment orders:

POST /sender/orders - Create a new payment order
GET /sender/orders - List payment orders with filtering
GET /sender/orders/{id} - Get specific payment order details
GET /sender/stats - Get sender statistics

Provider Endpoints

For liquidity providers that fulfill orders:

GET /provider/orders - List available orders for fulfillment
GET /provider/rates/{token}/{fiat} - Get market rates
GET /provider/stats - Get provider statistics
GET /provider/node-info - Get node information

General Endpoints

For protocol information and utilities:

GET /currencies - List supported fiat currencies
GET /institutions/{currency_code} - List supported institutions
GET /tokens - List supported tokens
GET /rates/{token}/{amount}/{fiat} - Get token rates
GET /pubkey - Get aggregator public key
POST /verify-account - Verify bank account details
GET /orders/{chain_id}/{id} - Get lock payment order status
GET /reindex/{network}/{tx_hash} - Reindex transactions

Request Format

All requests should include the following headers:

Content-Type: application/json
API-Key: YOUR_API_KEY

Example Request

cURL
JavaScript
Python
Go

curl -X POST "https://api.paycrest.io/v1/sender/orders" \
  -H "Content-Type: application/json" \
  -H "API-Key: YOUR_API_KEY" \
  -d '{
    "amount": 100,
    "token": "USDT",
    "network": "base",
    "rate": 1.0,
    "recipient": {
      "institution": "GTB",
      "accountIdentifier": "1234567890",
      "accountName": "John Doe",
      "currency": "NGN",
      "memo": "Salary payment for January 2024"
    },
    "reference": "payment-123",
    "returnAddress": "0x1234567890123456789012345678901234567890"
  }'

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.paycrest.io/v1';

const orderData = {
  amount: 100,
  token: 'USDT',
  network: 'base',
  rate: 1.0,
  recipient: {
    institution: 'GTB',
    accountIdentifier: '1234567890',
    accountName: 'John Doe',
    currency: 'NGN',
    memo: 'Salary payment for January 2024'
  },
  reference: 'payment-123',
  returnAddress: '0x1234567890123456789012345678901234567890'
};

const response = await axios.post(`${BASE_URL}/sender/orders`, orderData, {
  headers: {
    'API-Key': API_KEY,
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.paycrest.io/v1'

order_data = {
    "amount": 100,
    "token": "USDT",
    "network": "base",
    "rate": 1.0,
    "recipient": {
        "institution": "GTB",
        "accountIdentifier": "1234567890",
        "accountName": "John Doe",
        "currency": "NGN",
        "memo": "Salary payment for January 2024"
    },
    "reference": "payment-123",
    "returnAddress": "0x1234567890123456789012345678901234567890"
}

response = requests.post(
    f'{BASE_URL}/sender/orders',
    headers={
        'API-Key': API_KEY,
        'Content-Type': 'application/json'
    },
    json=order_data
)

print(response.json())

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    orderData := map[string]interface{}{
        "amount": 100,
        "token":  "USDT",
        "network": "base",
        "rate":   1.0,
        "recipient": map[string]interface{}{
            "institution":       "GTB",
            "accountIdentifier": "1234567890",
            "accountName":       "John Doe",
            "currency":          "NGN",
            "memo":             "Salary payment for January 2024",
        },
        "reference":     "payment-123",
        "returnAddress": "0x1234567890123456789012345678901234567890",
    }

    jsonData, _ := json.Marshal(orderData)
    req, _ := http.NewRequest("POST", "https://api.paycrest.io/v1/sender/orders", bytes.NewBuffer(jsonData))
    req.Header.Set("API-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Response Format

All API responses follow a consistent format:

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

Error Responses

Error responses include detailed information:

{
  "status": "error",
  "message": "Validation failed",
  "data": [
    {
      "field": "amount",
      "message": "Amount must be greater than 0"
    }
  ]
}

Rate Limiting

API requests are rate-limited to ensure fair usage:

Unauthenticated requests: 20 requests per second
Authenticated requests: 500 requests per second

Pagination

List endpoints support pagination with the following parameters:

page - Page number (default: 1)
pageSize - Items per page (default: 20, max: 100)

Example

cURL
JavaScript
Python
Go

curl -X GET "https://api.paycrest.io/v1/sender/orders?page=2&pageSize=10" \
  -H "API-Key: YOUR_API_KEY"

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.paycrest.io/v1';

async function getOrders(page = 2, pageSize = 10) {
  const response = await axios.get(`${BASE_URL}/sender/orders`, {
    headers: { 'API-Key': API_KEY },
    params: { page, pageSize }
  });
  console.log(response.data);
}
getOrders();

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.paycrest.io/v1'

response = requests.get(
    f'{BASE_URL}/sender/orders',
    headers={'API-Key': API_KEY},
    params={'page': 2, 'pageSize': 10}
)
print(response.json())

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

func main() {
    baseURL := "https://api.paycrest.io/v1/sender/orders"
    params := url.Values{}
    params.Add("page", "2")
    params.Add("pageSize", "10")
    
    req, _ := http.NewRequest("GET", baseURL+"?"+params.Encode(), nil)
    req.Header.Set("API-Key", "YOUR_API_KEY")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Response includes pagination metadata:

{
  "status": "success",
  "message": "Orders retrieved successfully",
  "data": {
    "total": 150,
    "page": 2,
    "pageSize": 10,
    "orders": [...]
  }
}

Webhooks

Set up webhooks to receive real-time updates:

Webhook Events

order.initiated - Order initiated via API (before Gateway creation)
order.pending - Order awaiting provider assignment
order.validated - Order validated and ready for settlement
order.settled - Order settled on blockchain
order.refunded - Order refunded to sender
order.expired - Order expired because no transfer was made to the receive address within the time limit

Webhook Payload

{
  "event": "order.settled",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "settled",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "txHash": "0x1234567890abcdef...",
    "providerId": "provider-123",
    "settlementAmount": "50000"
  }
}

For detailed webhook implementation guide including signature verification, retry logic, and best practices, see the Sender API Integration Guide.

Testing

Paycrest supports very low minimum orders (as little as $0.50) and uses cost-effective EVM L2s, making it perfect for testing with real transactions. Start small and scale up as you gain confidence.

There is no sandbox environment at the moment. All testing should be done on production using small amounts.

Support

Need help with the API?

Documentation: Browse our comprehensive guides
Telegram: Join our developer community at t.me/+Stx-wLOdj49iNDM0
GitHub: Report issues at github.com/paycrest
Email: Contact support at [email protected]

Fee Model

Protocol fees are paid by providers. Senders experience zero fees, maximizing their payout.

Overview

Sender

Provider

General

​Base URL

​Authentication

​Getting Your API Key

​API Endpoints

​Sender Endpoints

​Provider Endpoints

​General Endpoints

​Request Format

​Example Request

​Response Format

​Error Responses

​Rate Limiting

​Pagination

​Example

​Webhooks

​Webhook Events

​Webhook Payload

​Testing

​Support

​Fee Model

Base URL

Authentication

Getting Your API Key

API Endpoints

Sender Endpoints

Provider Endpoints

General Endpoints

Request Format

Example Request

Response Format

Error Responses

Rate Limiting

Pagination

Example

Webhooks

Webhook Events

Webhook Payload

Testing

Support

Fee Model