Core Systems Introduction — Payment Flow, UFS, UES, Redis

Use case: Internal team systems introduction / New hire onboarding
Suggested duration: 30–60 minutes
Document source: Pay Core Workspace - Microservices

Table of Contents

1. System Overview

2. Payment Flow (Focus)

   • 2.1 Stage Description
   • 2.2 Key Concept Distinctions
   • 2.3 Channel Routing Diagram

3. UFS — Unified File Service

   • 3.1 Positioning
   • 3.2 Architecture
   • 3.3 Two Authorization Modes
   • 3.4 Standalone Bucket Application Process
   • 3.5 Integration Methods
   • 3.6 HTTP API - Standalone Bucket
   • 3.7 HTTP API - Share Bucket
   • 3.8 Return Codes

4. UES — Unified Encryption/Decryption Service

   • 4.1 Positioning
   • 4.2 Core Concept: Ticket
   • 4.3 Ticket Type Comparison
   • 4.4 Main Capabilities
   • 4.5 Supported data_type (Partial)
   • 4.6 Key Version Evolution
   • 4.7 Java Integration Example
   • 4.8 HTTP API Access

5. Redis — redis-starter & Cluster Solution

   • 5.1 Positioning
   • 5.2 Integration Architecture
   • 5.3 Two Version Lines
   • 5.4 Deployment & Integration Methods
   • 5.5 Key Configuration
   • 5.6 Usage
   • 5.7 Usage in Payment Chain
   • 5.8 Evolution Direction
6. Summary
7. Reference Documents

1. System Overview

📖 References: Microservices main doc ｜ Core Systems Brief Introduction

Focus of this session: Payment Core payment flow + the three Basic infrastructure components UES / UFS / Redis.

2. Payment Flow (Focus)

📖 References:

• APP Payment Main Flow
• 21-pfs-Pre-payment
• 22-payment-Payment Engine
• Core Systems Brief Introduction

The complete APP payment main flow consists of 5 stages:

2.1 Stage Description

2.2 Key Concept Distinctions

Payment ≠ Settlement

• Payment: User's money enters the "pending settlement account"
• Settlement: Transfer from pending settlement account into the business's actual receiving account
• Settlement trigger modes: auto-settlement / periodic settlement / manual settlement

2.3 Channel Routing Diagram

Routing rule dimensions: verification method, card institution, order amount, merchant number, payer member number, priority.

3. UFS — Unified File Service

📖 References:

• ufs-Unified File Service
• ufs-2-Proxy Mode - Integration Guide
• ufs-Standalone bucket-http API
• ufs-Share bucket-http API

3.1 Positioning

UFS (Unified File Service) = unified wrapper for file storage/sharing.

• Underlying layer wraps Alibaba Cloud OSS / Azure Blob
• Design goal: shield differences between underlying cloud vendors, enabling easy future cloud migration
• Current implementation is Proxy mode: all upload/download traffic except download URLs flows through the UFS Server
• New applications uniformly integrate with ufs2 (legacy APIs are kept only for compatibility)

3.2 Architecture

3.3 Two Authorization Modes

3.4 Standalone Bucket Application Process

Application key points:

• sim bucket names end with test, prod bucket names end with prod
• sim and uat share the same bucket
• UFS Manager: shangkai.shi (backups: yongxing.cao, cong.zhou)

3.5 Integration Methods

Four types of API are provided:

• Java Client (recommended): ufs-Standalone bucket-java Client / ufs-Share bucket-java Client
• HTTP API (cross-language): ufs-Standalone bucket-http API / ufs-Share bucket-http API

Environment URLs (HTTP):

3.6 HTTP API - Standalone Bucket

📖 ufs-Standalone bucket-http API

Common request headers:

3.6.1 Upload File (PUT)

PUT {url}/standalone/file/{ossPath}

Optional request headers:

• x-ufs-forbid-overwrite: Forbid overwriting same-name file (default allows overwrite)
• x-ufs-encrypt: Encrypt on UFS side (default not encrypted)
• x-ufs-meta-*: Custom metadata (e.g. x-ufs-meta-check-sum, only a-z and -)

curl -v --request PUT \
  'https://sim-api-intra.test2pay.com/ufs2/standalone/file/demo/helloworld.txt' \
  --header 'x-ufs-client-id: demo' \
  --header 'Authorization: Basic dWZzX3VuaXR0ZXN0OnVmc191bml0dGVzdA==' \
  --form 'file=@/Users/cong.zhou/temp/hello.txt'
# < HTTP/1.1 200

3.6.2 Download File (GET)

GET {url}/standalone/file/{ossPath}

Response header x-ufs-meta-* returns the metadata set during upload.

curl -v --request GET \
  'https://sim-api-intra.test2pay.com/ufs2/standalone/file/demo/helloworld.txt' \
  --header 'x-ufs-client-id: demo' \
  --header 'Authorization: Basic dWZzX3VuaXR0ZXN0OnVmc191bml0dGVzdA=='
# < HTTP/1.1 200
# < Content-Type: application/octet-stream;charset=UTF-8
# < Content-Disposition: attachment; filename="helloworld.txt"

3.6.3 Get Temporary Authorized Download URL (STS)

GET {url}/standalone/fileUrl/{ossPath}

Optional request headers:

• x-ufs-expire-seconds: Link validity period (seconds, default 5 minutes)
• x-ufs-public-access: true returns OSS signed external URL; false returns UFS STS intranet URL (default)

curl -v --request GET \
  'https://sim-api-intra.test2pay.com/ufs2/standalone/fileUrl/demo/helloworld.txt' \
  --header 'x-ufs-client-id: demo' \
  --header 'Authorization: Basic dWZzX3VuaXR0ZXN0OnVmc191bml0dGVzdA=='
# Response:
# {"url":"https://.../ufs2/sts/file/b37e2707...","stsToken":"b37e2707..."}

3.6.4 Copy File (POST)

POST {url}/standalone/copyFile

Request headers specify source and target: x-ufs-from-bucket-alias / x-ufs-from-oss-path / x-ufs-to-bucket-alias / x-ufs-to-oss-path

3.6.5 Copy Shared File to Own Bucket (POST)

POST {url}/standalone/copyShareFile/

Copies a file from the Share Bucket (identified by fileTag) into the standalone bucket.

curl -v --request POST \
  'https://sim-api-intra.test2pay.com/ufs2/standalone/copyShareFile/' \
  --header 'x-ufs-client-id: demo' \
  --header 'Authorization: Basic dWZzX3VuaXR0ZXN0OnVmc191bml0dGVzdA==' \
  --header 'x-ufs-from-file-tag: ce0a58c2...' \
  --header 'x-ufs-to-oss-path: demo/ce0a58c2...' \
  --header 'x-ufs-copy-suffix: true'
# Response: {"ossPath":"demo/ce0a58c2....txt"}

3.7 HTTP API - Share Bucket

📖 ufs-Share bucket-http API

Share Bucket does not require Authorization, only x-ufs-client-id. The returned fileTag is the file's unique ID.

3.7.1 Upload File (PUT)

PUT {url}/share/file

Optional request headers:

• x-ufs-expire-seconds: File expiration time; file is inaccessible after expiration (default no expiration)
• x-ufs-encrypt: Encrypt on UFS side
• x-ufs-meta-*: Custom metadata

curl -v --request PUT \
  'http://sim-api-intra.test2pay.com/ufs2/share/file' \
  --header 'x-ufs-client-id: demo' \
  --form 'file=@/Users/cong.zhou/temp/hello.txt'
# Response: {"fileTag":"0abe2b6a57c5463cb5837c523d8fa601"}

3.7.2 Download File (GET)

GET {url}/share/file/{fileTag}

curl -v --request GET \
  'http://sim-api-intra.test2pay.com/ufs2/share/file/0abe2b6a...' \
  --header 'x-ufs-client-id: demo'

3.7.3 Get File Metadata (GET)

GET {url}/share/fileMeta/{fileTag}

Returns the x-ufs-meta-* data from response headers.

3.7.4 Adopt File (PATCH)

PATCH {url}/share/adopt/{fileTag}

Convert a temporary file into a permanent file (prevents cleanup on expiration).

curl -v --request PATCH \
  'http://sim-api-intra.test2pay.com/ufs2/share/adopt/83a151bb...' \
  --header 'x-ufs-client-id: demo'

3.7.5 Get Temporary Authorized Download URL (GET)

GET {url}/share/fileUrl/{fileTag}

Parameters same as Standalone mode. If x-ufs-public-access=true, must be called by the application that uploaded or adopted the file.

3.8 Return Codes

4. UES — Unified Encryption/Decryption Service

📖 References:

• ues(Unified encryption and decryption service)
• Credit UES API Documentation (HTTP API reference)

4.1 Positioning

UES (Unified Encryption/Decryption Service) = unified handling of sensitive field encryption/decryption.

• Client dependency: com.uaepay.basis.ues:ues-client, current version 2.3.4
• Business database stores only tickets, not plaintext; use ticket to decrypt when needed
• Maintainer: Cao Yongxing

4.2 Core Concept: Ticket

4.3 Ticket Type Comparison

4.4 Main Capabilities

• Temporary ticket / persistent ticket / persistent ticket with digest
• Large field persistent ticket (≤ 5,000,000 characters, stored in MongoDB; MySQL sharding)
• Temporary ticket → persistent ticket conversion (data_type can be changed)
• Look up ticket by plaintext (queryTicket)
• Batch encryption (saveDatas)

4.5 Supported data_type (Partial)

4.6 Key Version Evolution

4.7 Java Integration Example

<!-- pom.xml -->
<dependency>
    <groupId>com.uaepay.basis.ues</groupId>
    <artifactId>ues-client</artifactId>
    <version>2.3.4</version>
</dependency>

@Autowired
UesClientV2 uesClient;

// Persistent ticket encryption
EncryptContextV2 context = new EncryptContextV2(plain, "card_no");
uesClient.saveData(context);
String ticket = context.getTicket(); // Business DB stores this ticket

// Decryption
context = new EncryptContextV2();
context.setTicket(ticket);
uesClient.getDataByTicket(context);
String plainData = context.getPlainData();

4.8 HTTP API Access

📖 Credit UES API Documentation

UES primarily recommends Java Client integration, but internal HTTP endpoints are also provided (using Credit UES as an example; the inner API design is identical for other modules).
External HTTP APIs are generally exposed through CGS (Client Gateway Service):

• Internal call path: /bapi/...
• Public API path: /api/...
• Gateway can automatically handle UES tokens via encrypt / responseEncrypt extensions

Base Path: /credit-ues/inner
Content-Type: application/json

4.8.1 Single Encryption

POST /inner/encrypt

{
  "plainData": "sensitive-data",
  "dataType": "USER_INFO",
  "summary": "User personal information"
}

Response:

{
  "success": true,
  "data": "ticket-string",
  "message": null
}

curl -X POST http://localhost:8080/credit-ues/inner/encrypt \
  -H "Content-Type: application/json" \
  -d '{"plainData":"sensitive-data","dataType":"USER_INFO","summary":"User info"}'

4.8.2 Batch Encryption

POST /inner/batchEncrypt

[
  {"plainData":"d1","dataType":"USER_INFO","summary":"s1"},
  {"plainData":"d2","dataType":"USER_INFO","summary":"s2"}
]

Response: data array maps one-to-one with the request; failed entries are null.

{ "success": true, "data": ["ticket1", "ticket2", null], "message": null }

4.8.3 Single Decryption

POST /inner/decrypt

{ "ticket": "ticket-string" }

Response:

{ "success": true, "data": "decrypted-plain-text", "message": null }

Error example:

{ "success": false, "data": null, "message": "ticket not exist in database." }

4.8.4 Batch Decryption

POST /inner/batchDecrypt

{ "tickets": ["ticket1", "ticket2", "ticket3"] }

Response: returns Map<ticket, plain>, including only valid tickets.

{
  "success": true,
  "data": {
    "ticket1": "decrypted-data-1",
    "ticket2": "decrypted-data-2"
  }
}

4.8.5 Encryption/Decryption with Redis Cache

Usage recommendations:

• Frequently read, latency-sensitive data → use *WithCache
• One-off, strong consistency, write-heavy / read-light → use standard API

4.8.6 Security Model

Encryption: random AES Key encrypts data → RSA public key encrypts AES Key → both stored → ticket generated
Decryption: ticket queries DB → RSA private key restores AES Key → AES decrypts plaintext → GZIP decompress if needed

4.8.7 Common Errors

4.8.8 Best Practices

• Prefer batch APIs to reduce network overhead
• Use *WithCache for frequently accessed data
• Check for null in batch responses (partial failures appear as null)
• Use consistent dataType for the same kind of field for easier data governance
• Always check the success field before consuming data

5. Redis — redis-starter & Cluster Solution

📖 Reference: redis-starter

5.1 Positioning

• Internally, Redis is uniformly accessed via com.uaepay.starter:redis-starter
• Encapsulates Spring Cache, RedisTemplate, Redisson distributed lock
• Maintainers: Cong Zhou / Yongxing Cao

5.2 Integration Architecture

5.3 Two Version Lines

1.2.x:

• 1.2.18 switched to Lettuce + Cluster support
• 1.2.19 topology auto-refresh
• 1.2.22 scan interval configurable
• 1.2.26-SNAPSHOT exposes Redisson configuration

1.3.x:

• 1.3.6-SNAPSHOT back-ports 1.2.22 + 1.2.26 enhancements

5.4 Deployment & Integration Methods

When Cluster and Db Index are both configured, only Cluster takes effect.

5.5 Key Configuration

spring:
  application:
    name: redis-starter      # Required, used as key prefix
  redis:
    password: ******
    timeout: 15s
    expireDefault: 10m
    clusterScanInterval: 1m
    cluster:
      max-redirects: 6
      nodes: redis-cluster.sim.test2pay.com:6379
    lettuce:
      pool:
        max-idle: 5
        min-idle: 5
        max-active: 20
        max-wait: 10s
    redisson:
      ping-connection-interval: 1m
      check-lock-synced-slaves: true

5.6 Usage

Annotation-based caching:

@Service
public class SampleUserService {
    public static final String CACHE_NAME = "SAMPLE_USER_BY_ID";

    @Cacheable(value = CACHE_NAME)
    public User getUserById(long id) { /* ... */ }

    @CacheEvict(value = CACHE_NAME)
    public void flushUserById(long id) {}
}

Key rule: keys are automatically prefixed with the application name:

redis-starter:SAMPLE_USER_BY_ID:2971133547753664512

API calls:

@Resource
private RedisTemplate<String, Object> redisTemplate;

@Resource
private RedisService<String, Object> redisService;

⚠️ Do not inject RedisTemplate<String, String> — it pulls in the default StringRedisTemplate and loses the application-name prefix.

Distributed lock:

@Autowired
RedissonClient redissonClient;

public void demo() {
    RLock lock = redissonClient.getSpinLock("lock-key");
    if (!lock.tryLock()) return;
    try {
        // Default 120s auto-renewal
    } finally {
        lock.unlock();
    }
}

5.7 Usage in Payment Chain

• Cashier token ↔ order number binding cache
• Business-level caching (auth / product config / risk rules)
• Distributed locks (prevent duplicate payment / concurrent settlement)
• UES Temporary Ticket (in-memory sensitive data)
• Plaintext cache for UES *WithCache endpoints

5.8 Evolution Direction

• Migrate the legacy G42Cloud cluster to Azure (Redis Cluster supported)
• See Sunset Legacy Redis and Guide for upgrading to cluster Redis

6. Summary

7. Reference Documents

7.1 Microservices Overview

7.2 Payment Flow Related

7.3 UFS Related

7.4 UES Related

7.5 Redis Related

Document compiled from Pay Core Workspace Confluence documents
Generated: 2026-05-24