Copy page

Start here

Quickstart

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

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

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

3. Verify OTP

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

The response includes an otpToken. Use it 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","fullName":"Awa Koné","pin":"742913","otpToken":"<otpToken>"}'

The response includes accessToken, refreshToken, and walletProvisioning.

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"}'