Authorization Flow

Purpose: Obtain an access_token using a password grant + OTP-based MFA.

Prerequisites:

client_id: "merchant_app_client"
username: "[email protected]"
password: "MySecurePassword123"

Token Usage: Use the returned access_token in subsequent calls:

Authorization: Bearer <access_token>

1️⃣ Step 1: Request MFA Token

➡ API Reference: POST /reg/auth/token

Description: Exchange username + password for a temporary mfa_token indicating MFA is required.

Request Body (JSON):

{
  "grant_type": "password",
  "client_id": "merchant_app_client",
  "password": "MySecurePassword123",
  "username": "[email protected]"
}

Response 200 (JSON):

{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.mfaTokenExample123"
}

Persist:

mfa_token → eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.mfaTokenExample123

2️⃣ Step 2: Get Active MFA Authenticators

➡ API Reference: GET /reg/mfa/authenticators?onlyActive=true

Description: Retrieve active authenticators bound to the mfa_token.

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.mfaTokenExample123

Response 200 (JSON):

{
  "authenticator_type": "otp",
  "id": "auth_otp_83fbc91e-203f-4c9c-8b2a-718e573cde47",
  "active": true
}

Persist:

authenticator_id → auth_otp_83fbc91e-203f-4c9c-8b2a-718e573cde47

3️⃣ Step 3: Create MFA Challenge

➡ API Reference: POST /reg/mfa/challenge

Description: Initiate an OTP challenge for the selected authenticator.

Request Body (JSON):

{
  "challenge_type": "otp",
  "authenticator_id": "auth_otp_83fbc91e-203f-4c9c-8b2a-718e573cde47",
  "mfa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.mfaTokenExample123",
  "client_id": "merchant_app_client"
}

Response 200 (JSON):

{
  "challenge_type": "otp"
}

Next:

Retrieve the one-time password (OTP) from the configured authenticator (e.g., TOTP app).

4️⃣ Step 4: Exchange OTP for Access Token

➡ API Reference: POST /reg/auth/token

Description: Finalize MFA by exchanging the OTP and mfaToken for an access_token.

Request Body (JSON):

{
  "grant_type": "mfa-otp",
  "client_id": "merchant_app_client",
  "otp": "482931",
  "mfaToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.mfaTokenExample123"
}

Response 200 (JSON):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.accessTokenExample456",
  "token_type": "Bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.refreshTokenExample789",
  "scope": "payin:read withdraw:read accounts:show transfer:create",
  "expires_in": 86400,
  "user_id": "merchant_112233"
}

Use in Subsequent Requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.accessTokenExample456