# Quickstart

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

## 1. Read country metadata

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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`.

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