​

API Reference

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

1. Register at app.paycrest.io
2. Complete KYC verification (required for compliance)
3. Generate API credentials in your dashboard
4. Save your API key securely

​

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
• POST /provider/orders/{id}/accept - Accept an order for fulfillment
• POST /provider/orders/{id}/decline - Decline an order
• POST /provider/orders/{id}/fulfill - Fulfill an order with payment details
• POST /provider/orders/{id}/cancel - Cancel an order with reason
• 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 -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"
  }'

​

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

GET /sender/orders?page=2&pageSize=10

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"
  }
}

​

Error Codes

​

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.

​

Support

Need help with the API?

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

​

Fee Model

All sender fees are paid by providers. Senders experience zero or minimal fees, maximizing their payout.