Skip to content

quickstart.mdx

Latest commit

 

History

History
729 lines (614 loc) · 18.8 KB

quickstart.mdx

File metadata and controls

729 lines (614 loc) · 18.8 KB
title Quickstart
description Get started with Paycrest in minutes - Learn how to create payment orders and integrate with the API

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](https://app.paycrest.io)
2. **Complete KYC verification** (required for compliance)
3. **Access your API key** in your dashboard

<Note>
  Your API key should be kept secure and never shared publicly. It's used to authenticate all API requests.
</Note>
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 -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. Fetch the current exchange rate for your token and currency pair. Set up your API key and prepare the payment order data with recipient details. Make a POST request to the orders endpoint with your payment details. Process the response to get your order ID and payment instructions. Track your order status and handle webhooks for real-time updates.

Step 2: Create Payment Order

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

```javascript 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))
```
```go 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

Dive deeper into the Paycrest API with interactive examples and detailed documentation Understand how the Paycrest protocol works under the hood See all supported stablecoins, networks, and fiat currencies 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.