Troubleshooting

Invalid API Key

If you’re getting 401 Unauthorized errors:

• Verify your API key is correct and not expired
• Ensure you’re using the correct header: API-Key (not X-API-Key)
• Check that your account has been KYC verified
• Confirm your API key has the necessary permissions

Example Request

curl -X GET "https://api.paycrest.io/v2/sender/orders" \
  -H "API-Key: YOUR_API_KEY"

400 Bad Request

Common causes and solutions:

• Invalid amount: Amount must be a positive number
• Unsupported token: Check supported tokens in the resources section
• Invalid network: Ensure the network supports your chosen token
• Invalid Starknet address: For network: "starknet", use felt hex (0x + 63–64 hex digits), not an EVM checksum address
• Invalid Tron address: For network: "tron", use a Base58 address starting with T, not an EVM 0x address
• Invalid Solana address: For network: "solana", refundAddress (off-ramp) and destination.recipient.address (on-ramp) must be Solana Base58 public keys, not EVM 0x addresses
• ”This network is available only via POST /v2/sender/orders”: v1 endpoints do not accept Tron or Solana. Create Tron and Solana orders with POST /v2/sender/orders
• ”recipient … token account does not exist …” (on-ramp to Solana): the recipient wallet has no token account for the stablecoin’s mint. Have the user create it, then retry
• ”Amount is below the minimum of 1 for this network”: the amount must be at least 1 unit of the stablecoin
• Invalid senderFeeAddress on a Solana order: for Solana orders, senderFeeAddress must be a Solana Base58 public key, like the order’s other addresses
• Missing recipient details: All recipient fields are required
• Invalid institution: Check supported institutions for the currency
• Provider routing rejected: providerIds and providerId are mutually exclusive; off-ramp queues cap at 3 entries and on-ramp at 1; entries must name providers you can route to. See Pin a provider queue

503 “Network temporarily unavailable”

The message is one of:

• “This network is temporarily unavailable; retry shortly or use another network"
• "A quote for this amount is not available right now; retry shortly”

Nothing was created. Retry shortly, or create the order on another network.

The user’s wallet will not send the deposit (“insufficient funds for gas”)

Not a Paycrest error — the wallet is refusing before broadcast. providerAccount.amountToTransfer is the token amount to send; the network fee for the user’s own transfer is paid separately in the network’s native token.

• No native balance in the sending account: holding the token is not enough. Wallets show a combined balance across accounts, so the native token often sits in a different account than the one sending
• Solana — the receive address’s token account: a transfer to a new receive address also creates its token account, currently about 0.0015 SOL on top of the network fee, and not refunded

Deposit sent without the memo

When providerAccount.memo is present, the deposit must include it; without it the deposit cannot be credited. Contact support with the order ID and transaction hash.

”Recipient data too large for encryption”

The recipient object is capped at 500 bytes of JSON before encryption. The size check reserves room for a full 3-provider routing queue on every order — including orders that send no providerIds — because the aggregator may resolve one onto the order and it rides in the message hash at gateway submit.

• That reservation costs about 49 bytes (~41 when you pin a providerId), leaving roughly 450 bytes for accountIdentifier + accountName + memo + metadata combined
• Trim memo first, then metadata — keep only apiKey and corridor-required keys like channel
• accountName from verify-account is often longer than what you supplied; count the resolved value

Example Error Response

{
  "status": "error",
  "message": "Invalid recipient details",
  "errors": {
    "recipient.accountIdentifier": "Account number is required",
    "recipient.institution": "Institution not supported for NGN"
  }
}

Order Stuck in Pending

If your order has been in pending status for more than 10 minutes:

• Check if there are any network issues or maintenance
• Verify the recipient details are correct
• Contact support with your order ID

Order Refunded

Common reasons for a refund:

• Insufficient provider liquidity
• Recipient account issues
• Compliance or regulatory restrictions
• Network congestion or technical issues

Webhooks Not Receiving

Troubleshooting steps:

• Verify your webhook URL is publicly accessible
• Check that your server returns 200 OK responses
• Ensure your webhook endpoint can handle POST requests
• Verify webhook signature for security

Inspect and replay deliveries

You don’t need to re-trigger the order flow to recover a missed event. Every send is logged as a delivery you can audit and replay:

• List failed deliveries: GET /v2/sender/webhooks?status=failed
• Read the captured response body and error: GET /v2/sender/webhooks/:id
• Replay the original payload: POST /v2/sender/webhooks/:id/retry (?sync=true returns the HTTP result inline; otherwise it’s queued)

Failed deliveries (transport errors and non-2xx responses) are also retried automatically with exponential backoff for 24 hours before being marked expired. See the webhook delivery logs & retry guide.

Webhook Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  const sig = (signature && String(signature).trim().toLowerCase()) || '';
  const key = String(secret || '').trim();
  if (!sig || !key) return false;

  const bodyBuf = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8');
  const expected = crypto.createHmac('sha256', key).update(bodyBuf).digest('hex').toLowerCase();
  if (expected.length !== sig.length) return false;
  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, 'utf8'),
      Buffer.from(sig, 'utf8')
    );
  } catch {
    return false;
  }
}

import hmac
import hashlib

def verify_webhook_signature(raw_body, signature, secret):
    # raw_body is the raw request body bytes
    sig = (signature or "").strip().lower()
    body = raw_body if isinstance(raw_body, bytes) else raw_body.encode("utf-8")
    expected = hmac.new(
        secret.strip().encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest().lower()
    return hmac.compare_digest(expected, sig)

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strings"
)

func verifyWebhookSignature(rawBody []byte, signature, secret string) bool {
    // rawBody is the raw request body bytes
    h := hmac.New(sha256.New, []byte(strings.TrimSpace(secret)))
    h.Write(rawBody)
    expected := hex.EncodeToString(h.Sum(nil))
    sig := strings.ToLower(strings.TrimSpace(signature))
    return hmac.Equal([]byte(expected), []byte(sig))
}

Blockchain Network Problems

If you’re experiencing issues with specific networks:

• High gas fees: Consider using L2 networks like Base, Arbitrum, Polygon, Celo, or Lisk
• Slow confirmations: Some networks may have congestion
• Network maintenance: Check our Telegram community for updates

Supported Networks