Skip to main content
This guide will walk you through creating your first payment order and integrating with the Paycrest API.

​
Prerequisites

Before you begin, make sure you have:
  • A Paycrest account with API access
  • KYC verification completed (required for all participants)
  • API credentials (API key and secret)
  • Basic knowledge of REST APIs
Follow these steps to obtain your API credentials:
  1. Register an account at app.paycrest.io
  2. Complete KYC verification (required for compliance)
  3. 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.
All participants must complete KYC verification before using the Paycrest protocol. This includes:
  • Identity verification (government-issued ID)
  • Address verification (utility bill or bank statement)
  • Business verification (for corporate accounts)
  • Compliance checks (sanctions screening)
The verification process typically takes 1-3 business days.

​
Create Your First Payment Order

Let’s create a simple payment order to send USDT to a Nigerian bank account.

​
Step 1: Get Exchange Rate

  • cURL
  • JavaScript
  • Python
  • Go
curl -X GET "https://api.paycrest.io/v1/rates/USDT/100/NGN" \
  -H "API-Key: YOUR_API_KEY"
Response: 
{
  "status": "success",
  "message": "Rate fetched successfully",
  "data": "1250.50"
}
Always fetch the latest rate before creating a payment order. Rates can change frequently, and using an outdated rate may cause your order to be refunded.
1

Get Exchange Rate

Fetch the current exchange rate for your token and currency pair.
2

Prepare Your Request

Set up your API key and prepare the payment order data with recipient details.
3

Send the Request

Make a POST request to the orders endpoint with your payment details.
4

Handle the Response

Process the response to get your order ID and payment instructions.
5

Monitor Status

Track your order status and handle webhooks for real-time updates.

​
Step 2: Create Payment Order

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

​
Response

{
  "status": "success",
  "message": "Payment order initiated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "100",
    "token": "USDT",
    "network": "base",
    "receiveAddress": "0x9876543210987654321098765432109876543210",
    "validUntil": "2024-01-15T10:30:00Z",
    "senderFee": "0.5",
    "transactionFee": "2.5",
    "reference": "payment-123"
  }
}

​
Check Order Status

  • cURL
  • JavaScript
  • Python
  • Go
curl -X GET "https://api.paycrest.io/v1/sender/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "API-Key: YOUR_API_KEY"

Order Statuses

  • pending: Order created, waiting for provider assignment
  • processing: Provider assigned, fulfillment in progress
  • fulfilled: Payment completed by provider
  • validated: Payment validated and confirmed
  • settled: Order fully completed on blockchain
  • cancelled: Order cancelled (with reason)
  • refunded: Funds refunded to sender

Response Time

  • Order Processing: < 30 seconds (creation → validation)
  • Settlement: +15 seconds (onchain settlement)
  • Total Time: ~1-2 minutes
  • Auto-Refund: If not completed within 5 minutes

​
Handle Webhooks (Optional)

Set up webhooks to receive real-time updates through your Sender dashboard:
  1. Log into your Sender dashboard at app.paycrest.io
  2. Navigate to Settings → Webhooks
  3. Enter your webhook URL (e.g., https://your-domain.com/webhooks/paycrest)
  4. Save the configuration
Your webhook endpoint will receive notifications for all order status changes automatically.

​
Webhook Payload Example

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

​
Get Supported Currencies

Check available currencies and institutions: 
# Get supported currencies
curl -X GET "https://api.paycrest.io/v1/currencies"

# Get institutions for a currency
curl -X GET "https://api.paycrest.io/v1/institutions/NGN"

​
Code Examples

const axios = require('axios');

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

// Get exchange rate
async function getExchangeRate(token, amount, currency) {
  try {
    const response = await axios.get(`${BASE_URL}/rates/${token}/${amount}/${currency}`, {
      headers: {
        'API-Key': API_KEY
      }
    });
    
    console.log('Rate retrieved:', response.data);
    return response.data.data;
  } catch (error) {
    console.error('Error getting rate:', error.response?.data || error.message);
  }
}

// Create payment order
async function createPaymentOrder() {
  try {
    // First, get the current rate
    const rate = await getExchangeRate('USDT', '100', 'NGN');
    
    const response = await axios.post(`${BASE_URL}/sender/orders`, {
      amount: '100',
      token: 'USDT',
      network: 'base',
      rate: rate,
      recipient: {
        institution: 'GTB',
        accountIdentifier: '1234567890',
        accountName: 'John Doe',
        currency: 'NGN',
        memo: 'Salary payment for January 2024'
      },
      reference: 'payment-123',
      returnAddress: '0x1234567890123456789012345678901234567890'
    }, {
      headers: {
        'API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Order created:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error creating order:', error.response?.data || error.message);
  }
}

// Get order status
async function getOrderStatus(orderId) {
  try {
    const response = await axios.get(`${BASE_URL}/sender/orders/${orderId}`, {
      headers: {
        'API-Key': API_KEY
      }
    });
    
    console.log('Order status:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error getting order status:', error.response?.data || error.message);
  }
}

import requests

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

# Get exchange rate
def get_exchange_rate(token, amount, currency):
    try:
        response = requests.get(
            f'{BASE_URL}/rates/{token}/{amount}/{currency}',
            headers={'API-Key': API_KEY}
        )
        
        print('Rate retrieved:', response.json())
        return response.json()['data']['data']
    except Exception as e:
        print('Error getting rate:', str(e))

# Create payment order
def create_payment_order():
    try:
        # First, get the current rate
        rate = get_exchange_rate('USDT', '100', 'NGN')
        
        response = requests.post(
            f'{BASE_URL}/sender/orders',
            json={
                'amount': '100',
                'token': 'USDT',
                'network': 'base',
                'rate': rate,
                'recipient': {
                    'institution': 'GTB',
                    'accountIdentifier': '1234567890',
                    'accountName': 'John Doe',
                    'currency': 'NGN',
                    'memo': 'Salary payment for January 2024'
                },
                'reference': 'payment-123',
                'returnAddress': '0x1234567890123456789012345678901234567890'
            },
            headers={
                'API-Key': API_KEY,
                'Content-Type': 'application/json'
            }
        )
        
        print('Order created:', response.json())
        return response.json()
    except Exception as e:
        print('Error creating order:', str(e))

# Get order status
def get_order_status(order_id):
    try:
        response = requests.get(
            f'{BASE_URL}/sender/orders/{order_id}',
            headers={'API-Key': API_KEY}
        )
        
        print('Order status:', response.json())
        return response.json()
    except Exception as e:
        print('Error getting order status:', str(e))

package main

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

const (
    API_KEY  = "YOUR_API_KEY"
    BASE_URL = "https://api.paycrest.io/v1"
)

// Get exchange rate
func getExchangeRate(token, amount, currency string) (string, error) {
    req, _ := http.NewRequest("GET", fmt.Sprintf("%s/rates/%s/%s/%s", BASE_URL, token, amount, currency), nil)
    req.Header.Set("API-Key", API_KEY)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println("Rate retrieved:", string(body))
    
    // Parse response to get rate (simplified)
    var result map[string]interface{}
    json.Unmarshal(body, &result)
    return result["data"].(string), nil
}

// Create payment order
func createPaymentOrder() error {
    // First, get the current rate
    rate, err := getExchangeRate("USDT", "100", "NGN")
    if err != nil {
        return err
    }
    
    payload := map[string]interface{}{
        "amount": "100",
        "token":  "USDT",
        "network": "base",
        "rate":   rate,
        "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(payload)
    req, _ := http.NewRequest("POST", BASE_URL+"/sender/orders", bytes.NewBuffer(jsonData))
    req.Header.Set("API-Key", API_KEY)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println("Order created:", string(body))
    return nil
}

// Get order status
func getOrderStatus(orderID string) error {
    req, _ := http.NewRequest("GET", BASE_URL+"/sender/orders/"+orderID, nil)
    req.Header.Set("API-Key", API_KEY)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println("Order status:", string(body))
    return nil
}

​
Next Steps

Explore the API

Dive deeper into the Paycrest API with interactive examples and detailed documentation

Learn About Architecture

Understand how the Paycrest protocol works under the hood

Check Supported Assets

See all supported stablecoins, networks, and fiat currencies

Get Support

Need help? Contact our support team for assistance
This quickstart guide covers the basics. For production integration, make sure to implement proper error handling, webhook verification, and security best practices.
⌘I