Testing Crypto Payments

Unlike fiat payments, crypto payment testing requires real test tokens sent to a test wallet address. IvoryPay provides test tokens you can request for free to use exclusively in the test environment.

This flow only works with test API keys (sk_test_...). Test tokens have no real monetary value and cannot be used on live networks.

---

Step 1 — Request Test Tokens

Visit the IvoryPay token faucet to request test tokens:

https://www.ivorypay.io/get-tokens

• Select the token and network you want to test with (e.g. USDT on BSC Testnet)

• Enter your test wallet address or email

• Tokens are sent to your account and available for testing immediately

---

Step 2 — Create a Crypto Payment Request

Use your test secret key to initiate a crypto collection transaction. The response will contain a wallet address and the exact crypto amount to send.

POST /v1/transactions
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 10,
  "email": "[e-mail]",
  "firstName": "John",
  "lastName": "Doe",
  "type": "CRYPTO",
  "baseFiat": "USD",
  "crypto": "USDT",
  "chain": "BSC_TESTNET",
  "reference": "b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e"
}

Response:

{
  "status": true,
  "message": "Transaction initiated successfully",
  "data": {
    "reference": "b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e",
    "status": "PENDING",
    "collectionDetails": {
      "address": "0xAbCdEf1234567890AbCdEf1234567890AbCdEf12",
      "network": "BSC_TESTNET",
      "token": "USDT",
      "amountInCrypto": "10.00",
      "expiresAt": "2024-01-01T12:10:00.000Z"
    }
  }
}

---

Step 3 — Send the Test Tokens

Send the exact crypto amount to the wallet address returned in collectionDetails.address.

Important:

• Send the exact amount shown — partial or excess amounts will not confirm

• Use the correct network — sending on the wrong network results in permanent loss of tokens

• Transactions must be sent before expiresAt — expired sessions return EXPIRED status

---

Step 4 — Verify the Transaction Status

Once the tokens are sent and the blockchain confirms the transaction, the status will move from PENDING → PROCESSING → SUCCESS.

GET /v1/business/transactions/b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e/verify
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "status": true,
  "message": "Transaction details retrieved successfully",
  "data": {
    "reference": "b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e",
    "status": "SUCCESS",
    "amount": 10,
    "currency": "USDT",
    "network": "BSC_TESTNET"
  }
}

Poll this endpoint every few seconds until the status is SUCCESS or FAILED.

---

Supported Test Networks

Network	Chain Value	Supported Tokens
BNB Smart Chain Testnet	BSC_TESTNET	USDT, USDC
Polygon Mumbai	POLYGON_TESTNET	USDT, USDC

To get available networks and tokens for your test account:

GET /v1/crypto-transfer/supported-network-tokens
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

---

Transaction Status Values

Status	Meaning
PENDING	Awaiting crypto transfer from the customer
PROCESSING	Transfer detected on-chain, awaiting confirmations
SUCCESS	Confirmed — payment complete
EXPIRED	Session expired before payment was received
FAILED	Transfer failed or could not be confirmed

---

Refreshing an Expired Session

If a session expires before the customer pays, you can refresh it to get a new wallet address and expiry window:

GET /v1/business/transactions/refresh/b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e?fiatCurrency=USD
Authorization: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

---

Code Samples

Node.js

const axios = require('axios');

const API_KEY = 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxx';
const BASE_URL = 'https://api.ivorypay.io/api';
const reference = 'b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e';
const headers = { Authorization: API_KEY };

async function createCryptoPayment() {
  const { data } = await axios.post(
    `${BASE_URL}/v1/transactions`,
    {
      amount: 10,
      email: '[e-mail]',
      firstName: 'John',
      lastName: 'Doe',
      type: 'CRYPTO',
      baseFiat: 'USD',
      crypto: 'USDT',
      chain: 'BSC_TESTNET',
      reference,
    },
    { headers },
  );

  const { address, amountInCrypto, network } = data.data.collectionDetails;
  console.log(`Send ${amountInCrypto} USDT to ${address} on ${network}`);
  return data.data;
}

async function pollStatus(intervalMs = 5000, maxAttempts = 24) {
  for (let i = 0; i < maxAttempts; i++) {
    const { data } = await axios.get(
      `${BASE_URL}/v1/business/transactions/${reference}/verify`,
      { headers },
    );

    const { status } = data.data;
    console.log(`Status: ${status}`);

    if (status === 'SUCCESS' || status === 'FAILED' || status === 'EXPIRED') {
      return status;
    }

    await new Promise((r) => setTimeout(r, intervalMs));
  }

  throw new Error('Max polling attempts reached');
}

createCryptoPayment().then(() => pollStatus());

Python

import requests
import time

API_KEY = "sk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://api.ivorypay.io/api"
REFERENCE = "b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e"
HEADERS = {"Authorization": API_KEY, "Content-Type": "application/json"}

# Step 1: Create payment request
response = requests.post(f"{BASE_URL}/v1/transactions", json={
    "amount": 10,
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "type": "CRYPTO",
    "baseFiat": "USD",
    "crypto": "USDT",
    "chain": "BSC_TESTNET",
    "reference": REFERENCE,
}, headers=HEADERS)

details = response.json()["data"]["collectionDetails"]
print(f"Send {details['amountInCrypto']} USDT to {details['address']} on {details['network']}")

# Step 2: Poll for status
for _ in range(24):
    verify = requests.get(
        f"{BASE_URL}/v1/business/transactions/{REFERENCE}/verify",
        headers=HEADERS,
    ).json()

    status = verify["data"]["status"]
    print(f"Status: {status}")

    if status in ("SUCCESS", "FAILED", "EXPIRED"):
        break

    time.sleep(5)

PHP

<?php

$apiKey    = 'sk_test_xxxxxxxxxxxxxxxxxxxxxxxx';
$baseUrl   = 'https://api.ivorypay.io/api';
$reference = 'b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e';
$headers   = ['Authorization: ' . $apiKey, 'Content-Type: application/json'];

// Step 1: Create payment request
$ch = curl_init("$baseUrl/v1/transactions");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'amount'    => 10,
        'email'     => '[e-mail]',
        'firstName' => 'John',
        'lastName'  => 'Doe',
        'type'      => 'CRYPTO',
        'baseFiat'  => 'USD',
        'crypto'    => 'USDT',
        'chain'     => 'BSC_TESTNET',
        'reference' => $reference,
    ]),
    CURLOPT_HTTPHEADER     => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);
$txn     = json_decode(curl_exec($ch), true);
curl_close($ch);

$details = $txn['data']['collectionDetails'];
echo "Send {$details['amountInCrypto']} USDT to {$details['address']} on {$details['network']}" . PHP_EOL;

// Step 2: Poll for status
for ($i = 0; $i < 24; $i++) {
    $ch = curl_init("$baseUrl/v1/business/transactions/$reference/verify");
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $verify = json_decode(curl_exec($ch), true);
    curl_close($ch);

    $status = $verify['data']['status'];
    echo "Status: $status" . PHP_EOL;

    if (in_array($status, ['SUCCESS', 'FAILED', 'EXPIRED'])) break;

    sleep(5);
}

---

Webhook Testing

Once the test transaction reaches SUCCESS, IvoryPay fires a cryptoCollection.success event to your configured webhook URL.

Example webhook payload:

{
  "event": "cryptoCollection.success",
  "data": {
    "reference": "b7e2d1f3-49a8-4c20-8e5b-2f3a4b5c6d7e",
    "status": "SUCCESS",
    "amount": 10,
    "currency": "USDT",
    "network": "BSC_TESTNET",
    "customer": {
      "email": "[e-mail]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

See Webhooks for how to verify the signature and handle events.

---

Important Notes

Rule	Detail
Test tokens only	Only use tokens received from ivorypay.io/get-tokens — do not send real funds
Exact amount	Send the exact amountInCrypto shown — mismatches will not confirm
Correct network	Always match the network in the response — wrong network means unrecoverable tokens
Session expiry	Sessions expire after 10 minutes — use the refresh endpoint if needed
Test keys only	sk_test_... keys only — test tokens sent to live addresses are unrecoverable