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

”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