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
```bash theme={null}
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
- Missing recipient details: All recipient fields are required
- Invalid institution: Check supported institutions for the currency
Example Error Response
```json theme={null}
{
"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
```javascript theme={null}
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;
}
}
```
```python theme={null}
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)
```
```go theme={null}
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
- Base
- Arbitrum One
- Polygon
- Celo
- Lisk
- Ethereum
- BNB Smart Chain
- Scroll
## Error Codes Reference