Copy page

Start here

Quickstart

This flow creates a sandbox user, verifies OTP, logs in, and calls an authenticated endpoint.

Sandbox Plane A auth is tenant-scoped. POST /auth/otp/issue, POST /auth/otp/verify, POST /auth/register, and POST /auth/login all require businessEntityId. The sandbox deployment id documented in the sandbox manifest and mobile brand config is heritagepay. Other programmes must use the id issued in Partner Console / Plane B — do not invent a tenant id.

1. Read country metadata

Code
curl https://sandbox-heritagepay-api.paypm.net/api/v1/mobile/countries/CI

Use the returned phone prefix, formatting rules, and operator catalog to validate the user input before issuing OTP.

2. Issue OTP

Live POST /auth/otp/issue requires phone, businessEntityId, and channel: "sms". purpose is also required (register, login, or reset_pin). A body of {phone, purpose} returns 400.

Code
curl -X POST https://sandbox-heritagepay-api.paypm.net/api/v1/auth/otp/issue \
  -H 'content-type: application/json' \
  -d '{"phone":"+2250748805663","businessEntityId":"heritagepay","channel":"sms","purpose":"register"}'

A 202 returns otpChallengeId, expiresAt, channel, and maskedPhone. That is a challenge record, not proof that an SMS was delivered. Do not assume a code was sent.

3. Verify OTP

Live POST /auth/otp/verify requires otpChallengeId and code, plus the same phone and businessEntityId. {phone, code} alone is rejected.

Code
curl -X POST https://sandbox-heritagepay-api.paypm.net/api/v1/auth/otp/verify \
  -H 'content-type: application/json' \
  -d '{"otpChallengeId":"<otpChallengeId>","code":"<code>","phone":"+2250748805663","businessEntityId":"heritagepay"}'

The response is {verified, otpToken, expiresAt}. Use otpToken once to register or reset PIN.

4. Register

Code
curl -X POST https://sandbox-heritagepay-api.paypm.net/api/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{"phone":"+2250748805663","businessEntityId":"heritagepay","fullName":"Awa Koné","pin":"742913","otpToken":"<otpToken>","termsAccepted":true,"privacyAccepted":true,"legalAcceptanceVersion":"heritagepay-ci-legal-2026-06-21"}'

The response includes accessToken, refreshToken, and walletProvisioning.

To log in an existing user, POST /auth/login also requires businessEntityId:

Code
curl -X POST https://sandbox-heritagepay-api.paypm.net/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"phone":"+2250748805663","businessEntityId":"heritagepay","pin":"742913"}'

5. Call an authenticated endpoint

Code
curl https://sandbox-heritagepay-api.paypm.net/api/v1/auth/me \
  -H "authorization: Bearer <accessToken>" \
  -H "x-deployment-scope: end-user"

6. Use idempotency for money movement

Every retryable money mutation should carry a stable Idempotency-Key.

Code
curl -X POST https://sandbox-heritagepay-api.paypm.net/api/v1/wallets/transfer \
  -H "authorization: Bearer <accessToken>" \
  -H "idempotency-key: transfer-demo-0001" \
  -H 'content-type: application/json' \
  -d '{"amount":5000,"currency":"XOF","recipientAlias":"+2250700000000"}'