Troubleshooting

Use this page to identify the next safe action. Never retry a money-moving request with a new reference when the previous outcome is unknown.

Authentication fails (401 or 403)

Check that:

• the endpoint and key belong to the same environment: ps_pk_test_... with sandbox, ps_pk_live_... with production;
• the Authorization header is sent from your server as Bearer $PAYSCRIBE_API_KEY;
• the key is active and has the required dashboard permissions; and
• production requests originate from an allowed server IP.

See Authentication before generating or rotating a key.

A request timed out or returned 5xx

Treat the result as unknown. Keep the original ref, look up the transaction or operation status, and process any corresponding verified webhook. Do not create a new reference until reconciliation proves the first request did not complete.

See Idempotency and Funds flow.

Transfer keeps failing

Check that:

• the bank code came from the current bank list and the account number has been validated;
• your wallet has sufficient available balance; and
• you have recorded and reconciled the original ref before attempting another payout.

Use Transfers & Payouts and Common errors for the exact recovery path.

Webhook is not received or fails verification

• confirm the endpoint is public HTTPS and accepts POST;
• verify the raw request body before any JSON parsing or transformation;
• check the signature, timestamp, and X-Payscribe-Event-Id handling;
• return 200 OK only after the delivery has been durably queued or stored; and
• inspect the dashboard webhook logs and reconcile the related transaction.

Use Webhooks for setup and Webhooks & Events for the complete payload and retry reference.

Validation errors (400 or 422)

Show the returned validation message to the developer or customer, correct the request, then submit again. Do not retry unchanged input. For field-specific cases, see Common errors.