Skip to main content

​
Base URL

All API requests — both test and live — use a single base URL: 
https://api.orafi.app
Your API key determines whether you’re operating on testnet or mainnet. There are no separate environment URLs to manage.

​
Test vs live mode

Test modeLive mode
BlockchainTestnetMainnet
Real fundsNoYes
API key prefixora_test_ora_live_
Onboarding requiredNoYes
WebhooksDelivered normallyDelivered normally
Always use test mode during development. Switch to live mode only after your integration is fully tested and your onboarding is complete.

​
Switching modes

You can switch between test and live mode in two ways:
  1. Dashboard — Toggle the mode switch in your Orafi Dashboard.
  2. API — Call the Mode endpoint programmatically.
Switching to live mode requires completed onboarding and business verification.

​
Local webhook testing

Webhooks are delivered to publicly accessible HTTPS URLs. For local development, use a tunneling tool to expose your local server:
1

Start a tunnel

Use a tool like ngrok or localtunnel to create a public URL that forwards to your local server.
ngrok http 3000
2

Register the webhook URL

Use the tunnel URL as your webhook endpoint.
curl -X POST https://api.orafi.app/v1/webhook/register \
  -H "Content-Type: application/json" \
  -H "x-api-key: ora_test_your_api_key" \
  -d '{ "url": "https://abc123.ngrok.io/webhooks/orafi" }'
3

Trigger a test payment

Create a payment with your test API key. Once confirmed, the webhook will be delivered to your local server via the tunnel.

​
Testing best practices

Always generate a unique txRef for each payment. If you retry with the same txRef, Orafi returns the original payment instead of creating a duplicate.
Create payments, trigger refunds, and initiate payouts in test mode to cover your integration’s happy and error paths.
Every webhook payload is signed with your webhook secret. Always verify the signature before processing events — even in test mode.
If your endpoint returns a non-2xx status, Orafi retries delivery automatically. Make sure your handler is idempotent so duplicate deliveries don’t cause issues.