V8Pay - Hướng dẫn tích hợp - V2

1. API tạo mới giao dịch

Hỗ trợ tạo mới giao dịch xuất khoản trên V8Pay

A. Xác thực

Dùng token giao dịch (cung cấp bởi V8Pay) và gán vào Request Header khi gọi lên API.

Để nhận thông tin các khoá tích hợp, vui lòng liên hệ với đội ngũ hỗ trợ V8.

Tên khoá được sử dụng: [4] Withdrawal Transaction Token (出款密钥): xxxxxxxxx

curl -H 'TransactionToken: xxxxxxxxx'

B. Bảo mật:

Chữ ký (Checksum):

1. Checksum sử dụng thuật toán HMAC-SHA256 và secretKey làm khóa mã hóa.
2. Để nhận thông tin các khoá tích hợp, vui lòng liên hệ với đội ngũ hỗ trợ V8.
3. Tên khoá được sử dụng: [1] Checksum Secret Key (安全码): xxxxxxxxx

4. Sau khi có Checksum, vui lòng thêm Checksum vào request Header khi gọi lên API

curl -H 'Checksum: AAFbPNzeaDbfyiuT8NE251EYpsKbbHUikGfavtKPE7uzs9bP9z'

// PHP sample code to create Checksum
// NOTE: $message = json_encode($array, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)
// hmac_sha256_digest('{"bankCode":8001,"accountNumber":"1113333000888","accountName":"NGUYEN VAN A","referId":"W111212222000888","quantity":100000,"requestedBy":"user001","callbackUrl":"https://your-callback-url.sample"}', "CbdESgRaDKi9btfG5dQK2O7gXBrW6W2K");

public function hmac_sha256_digest($message, $secret_key) {
    $sig = hash_hmac('sha256', $message, $secret_key, true);
    $sig = base64_encode($sig);
    return $sig;
}

// C# sample code to create Checksum

public static string HmacSha256Digest(string message, string secretKey) {
    byte[] keyBytes = System.Text.Encoding.UTF8.GetBytes(secretKey);
    byte[] messageBytes = System.Text.Encoding.UTF8.GetBytes(message);
    System.Security.Cryptography.HMACSHA256 cryptographer = new System.Security.Cryptography.HMACSHA256(keyBytes);
    byte[] bytes = cryptographer.ComputeHash(messageBytes);
    string base64String = Convert.ToBase64String(bytes, 0, bytes.Length);
    return base64String;
}

// Java sample code to create Checksum

<!-- Maven lib -->
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
</dependency>

public static String hmacSha256Digest(String message, String secretKey) {
    byte[] hmac = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, secretKey.getBytes()).hmac(message);
    return Base64.getEncoder().encodeToString(hmac);
}

Đường dẫn API dùng để tạo mới yêu cầu xuất khoản

Danh sách tham số được dùng khi gọi lên API

!!! KIỂM TRA NGƯỢC THÔNG TIN ĐƠN XUẤT KHOẢN !!!

(*) Vui lòng Cài đặt đường dẫn kiểm tra ngược (1) và Bật tính năng kiểm tra ngược (2) trong phần cài đặt Xuất khoản

(*) V8pay hổ trợ tính năng kiểm tra ngược cho đơn xuất khoản trước khi tạo lên hệ thống.
Vui lòng trả về mã 200 (HTTP 200) cho xác nhận thành công và đơn sẽ được tạo.
Tất cả mã khác 200 sẽ được xem là không hợp lệ và đơn xuất khoản sẽ bị bãi bỏ.

Thông tin tích hợp và thuật toán:

• Thuật toán được sử dụng: "AES-256-CBC".
  Thực hiện giải mã chuỗi "checksum" và so sánh với chuỗi "md5", nếu kết quả khớp là dữ liệu hợp lệ.
• Kiểm tra ngược dùng chung AES secret key chung với webhook callback và cách giải mã tương tự nhau.
  Tham khảo thêm tại: Webhook integration
• Nội dung (tham khảo) được V8 gọi đến đường dẫn kiểm tra ngược.
  

  curl --location 'http://your-url-for-checking.com' \
  --header 'Content-Type: application/json' \
  --data '{
      "algorithm": {
          "type": "aes-256-cbc",
          "iv": "iVDXwgIk***"
      },
      "checksum": "7ae65cf3e6f80ff221ba3de***",
      "md5": "fb325aadcef01a95***",
      "payload": {
          "referId": "test001",
          "quantity": 100000,
          "requestedBy": "user001",
          "toBankCode": 8002,
          "toAccountName": "NGUYEN VAN A",
          "toAccountNumber": "1900009911"
      }
  }'
                                  

Danh sách mã ngân hàng (bankCode):

Ví dụ về 1 request hợp lệ dùng CURL:

curl -X POST https://cdn-api.v8pay.net/v2/auto/withdrawal/transactions \
  -H 'Checksum: AAFbPNzeaDbfyiuT8NE251EYpsKbbHUikGfavtKPE7uzs9bP9z' \
  -H 'TransactionToken: ABCDEBNRAZ5OQFwgNo87KkWPied5buNJPHbHwX9**********' \
  -H 'Content-Type: application/json' \
  -d '{
    "bankCode": 8001,
    "accountNumber": "1113333000888",
    "accountName": "NGUYEN VAN A",
    "referId":"W111212222000888",
    "quantity": 100000,
    "requestedBy": "user001",
    "callbackUrl": "https://your-callback-url.sample"
}'

Kết quả API trả về (dưới dạng JSON):

{
    "success": true,
    "message": "Success",
    "data": {
        "id": "646c91587c9cb3397******",
        "state": "queue",
        "toBankName": "Vietcombank",
        "toAccountNumber": "234234456663*****",
        "toAccountName": "NGUYEN VAN A",
        "quantity": 10,
        "referId": "XXX",
        "requestedBy": "YYY",
        "createdAt": 1684836696965
    }
}

Kết quả API trả về khi có lỗi xảy ra (dưới dạng JSON):

{
    "success": false,
    "message": "Field value must not empty [bankName]",
    "code": 422001
}

2. API thông tin giao dịch

Hỗ trợ lấy thông tin của 1 giao dịch

Xác thực

Dùng TransactionToken (cung cấp bởi V8Pay) và gán vào Request Header khi gọi lên API.
Để lấy TransactionToken vui lòng truy cập trang quản lý Tổ chức

Đường dẫn API

Danh sách tham số được dùng khi gọi lên API

Ví dụ về 1 request hợp lệ sử dụng CURL:

curl -X 'GET' \
  'https://cdn-api.v8pay.net/v2/auto/withdrawal/transactions/1234b38fc25fa023927b6f22' \
  -H 'Content-Type: application/json' \
  -H 'TransactionToken: ABCDEBNRAZ5OQFwgNo87KkWPied5buNJPHbHwX90wYCiI1Jt7n'

Kết quả API trả về (dưới dạng JSON):

{
    "success": true,
    "message": "Success",
    "data": {
        "id": "648704eeafce546a******",
        "state": "done",
        "toBankName": "Techcombank",
        "toAccountNumber": "109906917******",
        "toAccountName": "DOAN ******",
        "quantity": 7920000,
        "referId": "W2111790040261******",
        "requestedBy": "DOAN ******",
        "createdAt": 1686570222399,
        "finishedAt": 1686571394755
    }
}

Kết quả API trả về khi có lỗi xảy ra (dưới dạng JSON):

{
    "success": false,
    "message": "This is a message",
    "code": 422XXX
}

3. API thu hồi giao dịch

Hỗ trợ thu hồi 1 giao dịch khi giao dịch đó chưa được V8pay thực hiện

Xác thực

Dùng TransactionToken (cung cấp bởi V8Pay) và gán vào Request Header khi gọi lên API.
Để lấy TransactionToken vui lòng truy cập trang quản lý Tổ chức

Đường dẫn API

Danh sách tham số được dùng khi gọi lên API

Ví dụ về 1 request hợp lệ sử dụng CURL:

curl -X 'POST' \
  'https://cdn-api.v8pay.net/v2/auto/withdrawal/transactions/1234b38fc25fa023927b6f22/delete' \
  -H 'Content-Type: application/json' \
  -H 'TransactionToken: ABCDEBNRAZ5OQFwgNo87KkWPied5buNJPHbHwX90wYCiI1Jt7n'

Kết quả API trả về (dưới dạng JSON):

{
    "success": true,
    "message": "Success",
    "data": {
        "id": "648704eeafce546a******",
        "state": "delete",
        "toBankName": "Techcombank",
        "toAccountNumber": "109906917******",
        "toAccountName": "DOAN ******",
        "quantity": 7920000,
        "referId": "W2111790040261******",
        "requestedBy": "DOAN ******",
        "createdAt": 1686570222399,
        "finishedAt": 1686571394755
    }
}

Kết quả API trả về khi có lỗi xảy ra (dưới dạng JSON):

{
    "success": false,
    "message": "This is a message",
    "code": 422XXX
}

4. Tích hợp Webhook

Webhook là 1 đường dẫn bất kỳ không thuộc quản lí của V8Pay và được tích hợp vào V8Pay.
Khi giao dịch thành công, V8Pay sẽ gọi qua đường dẫn Webhook này kèm với thông tin giao dịch thành công.

Cơ chế bảo mật và đảm bảo toàn vẹn thông tin:

Để tăng cường bảo mật thông tin khi gọi Webhook, V8Pay cung cấp cơ chế mã hóa thông tin sử dụng thuật toán AES-256-CBC

V8Pay khuyến khích khách hàng sử dụng và tuân theo đúng các bước để giải mã, đảm bảo thông tin được gửi tới từ V8pay.

Xác thực thông tin request có 2 bước:

1. Giải mã chuỗi checksum trong request sử dụng thuật toán AES-256-CBC với 2 tham số:
- AES secret key (xem hình minh hoạ)
- IV (được truyền lên theo request)

Để nhận thông tin các khoá tích hợp, vui lòng liên hệ với đội ngũ hỗ trợ V8.

Tên khoá được sử dụng: [5] Withdrawal AES Secret Key (出款公钥): xxxxxxxxx

2. So sánh chuỗi đã giải mã (ở bước 1) với chuỗi md5 đi kèm.
Nếu giống nhau thì request là hợp lệ, nếu khác nhau là request không hợp lệ (không đến từ v8Pay)

Các tham số được V8Pay gửi lên Webhook URL (dạng JSON):

(1) Giao dịch thành công (done):

{
  algorithm: { type: 'aes-256-cbc', iv: 'IVIVIVIV***' },
  checksum: '***This is a string ***',
  md5: '***This is a MD5 string ***',
  payload: {
    id: 6441e74d0289bc635cf11***,
    state: 'done'
    quantity: 1000,
    createdAt: 1682040653827,
    requestedBy: 'U001',
    referId: 'R1341423423237789***',
    searchId: 'R1341423423237789***',
    toBankName: 'Bank Name',
    toAccountName: 'BANK ACCOUNT NAME',
    toAccountNumber: '1111111111'
  }
}

(2) Giao dịch đã bị xóa (delete):

{
  algorithm: { type: 'aes-256-cbc', iv: 'IVIVIVIV***' },
  checksum: '***This is a string ***',
  md5: '***This is a MD5 string ***',
  payload: {
    id: 6441e74d0289bc635cf11***,
    state: 'delete', // NOTE!!!: 'delete' or 'rejected'
    deleteReason: 'This is a note...'
    quantity: 1000,
    createdAt: 1682040653827,
    requestedBy: 'U001',
    referId: 'R1341423423237789***',
    searchId: 'R1341423423237789***',
    toBankName: 'Bank Name',
    toAccountName: 'BANK ACCOUNT NAME',
    toAccountNumber: '1111111111'
  }
}

Mô tả chi tiết nội dung payload:

5. Tích hợp Telegram

Contact customer service. Thank you.