Testing

Any registered account can generate TEST keys — no KYB required. Keys are managed from the dashboard, not through the API:

1. Log in to your Tulu Switch dashboard.
2. Navigate to Account > Developers in the sidebar.
3. Select the TEST environment and generate a new key pair.
4. Copy both keys immediately — the secret key is shown only once.

In TEST mode, the platform uses the sandbox / test credentials of each provider. This means checkout links and deposit flows go through the provider's own sandbox — you can use provider test cards and test bank accounts to simulate payments.

Use the test card numbers and test bank accounts from each provider's own documentation to trigger successful and failed payment scenarios.

• Outbound bank transfers (payouts) are hard-blocked — any attempt returns 400 Bad Request. This prevents accidental real-money disbursements from a test integration.
• Stablecoin operations use testnet chains, not mainnets.

A complete integration test covers these steps:

1. Generate a TEST key pair from the dashboard
2. Configure a webhook URL for the TEST environment
3. Authenticate via POST /v2/auth/authenticate to get an access token
4. Create a customer via POST /v2/customers
5. Initiate a deposit via POST /v2/purse/deposit and open the checkout URL
6. Complete the payment using provider test credentials
7. Receive and verify the customer.deposit.success webhook
8. Query the customer wallet balance to confirm the credit

Authentication (Customer API)

POST /v2/auth/authenticate
Content-Type: application/json

{
  "publicKey": "pk_test_Abc123...",
  "secretKey": "sk_test_Xyz789..."
}

Initiate a deposit

POST /v2/purse/deposit
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "customerId": "cus_xxx",
  "channel": "WALLET",
  "currency": "NGN",
  "amount": 5000,
  "email": "test@example.com",
  "callbackUrl": "https://your-app.com/callback"
}

Webhook testing happens through a real deposit flow — there is no separate test-event endpoint. When a deposit or payment is completed in TEST mode, the platform delivers a real signed webhook event to your configured URL.

1. Configure a TEST webhook URL in Account > Webhooks on the dashboard.
2. Use a tunnel tool (e.g. ngrok) to expose your local server if you are developing locally.
3. Initiate a deposit via POST /v2/purse/deposit and complete it using provider test credentials.
4. Your handler will receive a signed customer.deposit.success (or .failed) event.
5. Verify the X-Tulu-Switch-Signature header against the raw body using your webhook secret.

• Authentication — key-pair auth for builder routes; JWT token flow for Customer API
• Customer creation — create, update, and retrieve customers
• Deposits — WALLET channel checkout, ACCOUNT channel virtual NUBAN
• Webhooks — successful delivery, signature verification, idempotency
• Wallet balance — verify credits after customer.deposit.success
• Error paths — invalid currency, missing fields, revoked key
• Refunds — if your integration supports them (note: Seerbit does not support refunds)
• Subscriptions — if applicable; verify interval support per provider

You are ready for production when:

• The full deposit → webhook → wallet-credit flow works end-to-end
• Webhook signature verification is implemented and passing
• Error and edge cases are handled gracefully in your integration
• Your KYB review is approved and a LIVE key pair has been generated
• A LIVE webhook URL is configured (separate from your TEST URL)