Merchant Onboarding

Overview

Onboarding connects your merchant organization, receiving wallet, API keys, webhooks, and Android SMS Agent. Complete sandbox setup before requesting live activation.

Step-by-step guide

1. Create or accept access to your merchant dashboard account.
2. Configure the merchant receiving wallet number, for example 01700000001.
3. Create a sandbox API key.
4. Register and verify a sandbox webhook endpoint.
5. Create a sandbox payment intent from your backend.
6. Open the hosted checkout URL.
7. Send a matching sandbox SMS event from the Visual SMS Simulator.
8. Confirm the intent becomes PAID.
9. Test wrong amount, wrong receiver, duplicate transaction ID, expiry, and webhook retry behavior.
10. Create live API keys and configure the Android SMS Agent only after sandbox validation.

Code example

Store environment-specific keys separately:

SMS_PAY_SANDBOX_KEY=sk_test_xxxxxxxxxxxxxxxxx
SMS_PAY_LIVE_KEY=sk_live_xxxxxxxxxxxxxxxxx
SMS_PAY_WEBHOOK_SECRET=whsec_minimum_16_characters

Use the sandbox key while onboarding:

const apiKey =
  process.env.NODE_ENV === "production"
    ? process.env.SMS_PAY_LIVE_KEY
    : process.env.SMS_PAY_SANDBOX_KEY;

Request and response samples

Verify that a key is working by listing recent payment intents:

GET /v1/payments/intents?limit=5
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx

{
  "data": [],
  "total": 0,
  "page": 1,
  "limit": 5
}

Register a webhook:

POST /v1/webhooks/endpoints
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "url": "https://merchant-site.com/webhooks/sms-pay",
  "secret": "whsec_minimum_16_characters"
}

Production readiness checklist

• Merchant wallet number is correct.
• Sandbox payment intent creation works.
• Sandbox simulator SMS event matches a pending intent.
• Webhook endpoint is verified.
• Your webhook handler is idempotent.
• Android SMS Agent can validate device connectivity.
• Dashboard users know how to inspect payment intents and SMS events.

Edge cases and constraints

• Platform owner accounts are not merchant-scoped and cannot run merchant sandbox tools unless acting inside a merchant organization.
• API keys are environment-specific; do not pass an environment field to switch modes.
• Webhook endpoints must use HTTPS.
• Keep the phone running the Android SMS Agent powered, connected, and assigned to the correct receiving wallet.