Authorization Introduction

Scope

This document describes the authorization flow for merchants integrating with the Pexx service B2B APIs. It only covers authorization-related content and does not include detailed business API specifications.

Basic Integration Information

API Base URLs

Merchant Onboarding Materials

Before integration, key exchange and merchant configuration must be completed.

1. The merchant generates its own RSA key pair.

2. The merchant provides the RSA public key to the Pexx service for storage.

3. The RSA private key must be securely stored by the merchant. The Pexx service does not store the merchant's private key.

4. After merchant configuration is completed, the Pexx service provides the following information:

   • merchantCode: merchant identifier
   • PexxApiKey: merchant API key

A 2048-bit RSA key is recommended.

Example: Generate RSA Key Pair

Use OpenSSL to generate the RSA key pair:

openssl genrsa -out merchant_private_key.pem 2048
openssl pkcs8 -topk8 -inform PEM -outform PEM -in merchant_private_key.pem -out merchant_private_key_pkcs8.pem -nocrypt
openssl rsa -in merchant_private_key.pem -pubout -out merchant_public_key.pem

Notes:

• merchant_private_key_pkcs8.pem is the recommended merchant private key file
• merchant_public_key.pem is the merchant public key file to be provided to the Pexx service
• If the Pexx service requires the public key in Base64 format, remove the PEM header, footer, and line breaks before submission

Glossary

Authorization Flow

1. Request Access Credentials

Call:

• POST /apis/v1/access-token

Purpose:

• Request business access credentials
• Obtain the accessToken, refreshToken, and secretKey required for subsequent business API calls

Optional: Follow the cURL walkthrough in Recipes

Open the Request an access token with cURL Recipe to see the request body, required headers, cURL command, and example success and failure responses side by side.

Use this page for the signing rules and parameter definitions, then use the Recipe when you want a request flow you can copy and adapt.

2. Call Business APIs

Applicable range:

• GET /apis/v1/**
• POST /apis/v1/**

Purpose:

• Use accessToken to access business APIs
• Use secretKey to generate the request signature for business APIs

3. Refresh Access Credentials

Call:

• POST /apis/v1/refresh-token

Purpose:

• Request a new set of access credentials after accessToken expires by using refreshToken

API Integration Details

Header Requirements

Common Headers

Additional Header for Business APIs

Signing Rules

1. Signature for access-token / refresh-token Requests

Applicable APIs:

• POST /apis/v1/access-token
• POST /apis/v1/refresh-token

Signature algorithm:

• SHA256withRSA

String to sign:

METHOD:path:sha256(minifyJson(body)):apiKey:merchantCode:timestamp:nonce

Example:

POST:/apis/v1/access-token:sha256(body):your-api-key:your-merchant-code:1714291200:6f2e7c1a4d9b4c2f9c7d1e3a5b6f8a0c

Notes:

• METHOD must be uppercase, for example POST
• path must use the actual request path, for example /apis/v1/access-token
• body must be serialized in a stable format before hashing
• The signature result must be Base64-encoded and passed in X-SIGNATURE

2. Signature for Business API Requests

Applicable APIs:

• All other /apis/v1/** business APIs except /apis/v1/access-token and /apis/v1/refresh-token

Signature algorithm:

• HmacSHA512

String to sign:

METHOD:path:accessToken:sha256(minifyJson(body)):timestamp:nonce

Example:

POST:/apis/v1/user/balance/list:your-access-token:sha256(body):1714291200:6f2e7c1a4d9b4c2f9c7d1e3a5b6f8a0c

Notes:

• The secretKey returned by /apis/v1/access-token is the HMAC key
• The accessToken carried in PexxAuthorization must match the accessToken used in the string to sign
• An empty request body participates in signing as an empty string

API Specifications

1. POST /apis/v1/access-token

Purpose:

• Request access credentials

Request body parameters:

Response parameters:

2. POST /apis/v1/refresh-token

Purpose:

• Refresh access credentials

Request body parameters:

Response parameters:

3. General Requirements for Business APIs

Purpose:

• Use the access credentials to call specific business APIs

General requirements:

• PexxAuthorization: Bearer {accessToken} must be included in the request header
• The request must generate X-SIGNATURE according to the business API signing rules
• The request and response parameters of each specific business API are subject to its corresponding API documentation

Authentication Failure Response

Response Structure

When authentication fails, the response body uses the following common fields:

Error Codes