Quickstart

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

Get API Credentials

Follow these steps to obtain your API credentials:

Register an account 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.

KYC Requirements

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"

const axios = require('axios');

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

async function getExchangeRate() {
  const response = await axios.get(`${BASE_URL}/rates/USDT/100/NGN`, {
    headers: { 'API-Key': API_KEY }
  });
  console.log(response.data);
}
getExchangeRate();

import requests

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

response = requests.get(
    f'{BASE_URL}/rates/USDT/100/NGN',
    headers={'API-Key': API_KEY}
)
print(response.json())

package main

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

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.paycrest.io/v1/rates/USDT/100/NGN", nil)
    req.Header.Set("API-Key", "YOUR_API_KEY")
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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.

Get Exchange Rate

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

Prepare Your Request

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

Send the Request

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

Handle the Response

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

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

const axios = require('axios');

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

async function createOrder() {
  const response = await axios.post(
    `${BASE_URL}/sender/orders`,
    {
      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'
    },
    {
      headers: {
        'API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  console.log(response.data);
}
createOrder();

import requests

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

order_data = {
    "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 = 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() {
    order := map[string]interface{}{
        "amount": "100",
        "token": "USDT",
        "network": "base",
        "rate": "1250.50",
        "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(order)
    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

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

const axios = require('axios');

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

async function checkOrderStatus(orderId) {
  const response = await axios.get(
    `${BASE_URL}/sender/orders/${orderId}`,
    { headers: { 'API-Key': API_KEY } }
  );
  console.log(response.data);
}
checkOrderStatus('550e8400-e29b-41d4-a716-446655440000');

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.paycrest.io/v1'
ORDER_ID = '550e8400-e29b-41d4-a716-446655440000'

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

package main

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

func main() {
    orderId := "550e8400-e29b-41d4-a716-446655440000"
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.paycrest.io/v1/sender/orders/"+orderId, nil)
    req.Header.Set("API-Key", "YOUR_API_KEY")
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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:

Log into your Sender dashboard at app.paycrest.io
Navigate to Settings → Webhooks
Enter your webhook URL (e.g., https://your-domain.com/webhooks/paycrest)
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

JavaScript/Node.js

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);
  }
}

Python

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.

Getting Started

Core Concepts

Implementation Guides

Resources

Prerequisites

Create Your First Payment Order

Step 1: Get Exchange Rate

Step 2: Create Payment Order

Response

Check Order Status

Order Statuses

Response Time

Handle Webhooks (Optional)

Webhook Payload Example

Get Supported Currencies

Code Examples

Next Steps

Explore the API

Learn About Architecture

Check Supported Assets

Get Support

Getting Started

Core Concepts

Implementation Guides

Resources

​Prerequisites

​Create Your First Payment Order

​Step 1: Get Exchange Rate

​Step 2: Create Payment Order

​Response

​Check Order Status

Order Statuses

Response Time

​Handle Webhooks (Optional)

​Webhook Payload Example

​Get Supported Currencies

​Code Examples

​Next Steps

Explore the API

Learn About Architecture

Check Supported Assets

Get Support

Prerequisites

Create Your First Payment Order

Step 1: Get Exchange Rate

Step 2: Create Payment Order

Response

Check Order Status

Handle Webhooks (Optional)

Webhook Payload Example

Get Supported Currencies

Code Examples

Next Steps