API Thanh toán kèm liên kết thẻ

a. Tổng quan

- Phương thức gửi nhận: POST JSON

- HTTP Request: POST <BASE_URL> /request-payment

b. Data Request (Thông tin gửi sang Alepay)

Tên trường

Định dạng

Bắt buộc

Mặc định

Mô tả

tokenKey

String

T

  

Mã token key do alepay cung cấp khi đăng ký tài khoản trên alepay

orderCode

String (255)

T

  

Mã đơn hàng của Merchant

amount

Double

T

  

Giá trị đơn hàng (Nếu currency là VND thì gửi lên amount làm tròn đến 1 VND)

currency

String

T

  

Loại tiền tệ

orderDescription

String

T

  

Mô tả đơn hàng (Không bao gồm các ký tự đặc biệt, sẽ tự động loại bỏ các kí tự đặc biệt ra khỏi mô tả đơn hàng)

totalItem

Integer

T

  

Tổng số sản phẩm trong đơn hàng

checkoutType

Integer

F

  

0. Chỉ thanh toán ngay và trả góp với thẻ quốc tế
1. Chỉ thanh toán ngay với thẻ quốc tế
2. Chỉ thanh toán trả góp với thẻ quốc tế

installment

Boolean

F

 False

True: Đơn hàng chỉ cho phép trả góp ( Phải truyền lên cả month, bankCode và paymentMethod )
False : Đơn hàng cho phép trả góp hoặc thanh toán thường

month

Integer

F

  

Thông tin chu kỳ trả góp: 3, 6 ,9, 12, 15, 18, 24 tháng

bankCode

String

F

  

Mã ngân hàng cho phép User thực hiện thanh toán trả góp

paymentMethod

String

F

  

Loại thẻ cho phép user thực hiện thanh toán trả góp

returnUrl

String

T

  

URL Alepay sẽ callback lại Merchant khi user thanh toán thành công 

cancelUrl

String

T

  

URL Alepay sẽ callback lại Merchant khi user từ chối thanh toán checkout

buyerName

String

T

  

Tên người mua hàng

buyerEmail

String

T

  

Email người mua hàng

buyerPhone

String

T

  

Số điện thoại người mua

buyerAddress

String

T

  

Địa chỉ người mua

buyerCity

String

T

  

Tên thành phố của người mua

buyerCountry

String

T

  

Tên quốc gia của người mua

paymentHours

String

T

  

Thời gian cho phép thanh toán (tính bằng giờ)

merchantSideUserId

String

F

  

 ID của người dùng bên phía Merchant

buyerPostalCode

String

F

  

 Mã bưu chính của người dùng

buyerState

String

F

  

Tỉnh

isCardLink

Boolean

F

 False

True: Thanh toán kèm liên kết thẻ.
False: Chỉ thanh toán mà không liên kết thẻ

signature

String

T

  

Chữ ký để kiểm tra thông tin. Xem hướng dẫn tạo Signature

 

c. Data Response (Thông tin nhận về từ Alepay)

Tên trường

Định dạng

Mô tả

code

String

Mã lỗi (được mô tả trong Phụ lục 12.a)

message

String

Mô tả lỗi

checkoutUrl

String

URL thanh toán

transactionCode

String

Mã giao dịch tại Alepay, sử dụng để thực hiện đối soát

signature

String

Chữ ký để kiểm tra thông tin. Xem hướng dẫn tạo Signature

 

d. Trả kết quả về returnUrl

Khi End User kết thúc quá trình thanh toán Checkout trên Alepay, Alepay sẽ callback tới link “returnUrl” mà Merchant đã cung cấp khi gọi API request payment, sau đó Merchant cần gọi API GetTransactionInfo lấy thông tin chính xác của giao dịch. Dưới đây là mô tả các thông số Alepay sẽ truyền về cho Merchant khi thực hiện callback.

- HTTP Request: GET <MERCHANT_RETURN_URL>

- Response:

+ Trường hợp chỉ thanh toán: <MERCHANT_RETURN_URL>?code=000&transactionCode=XXXX&cancel=true

Trường

Kiểu

Mô tả dữ liệu

code

String

Mã lỗi (được mô tả trong Phụ lục 12.a)

transactionCode

String

Mã giao dịch Alepay

cancel

String

True: Người mua cancel giao dịch,

False: người mua thực hiện xong quá trình thanh toán.

+ Trường hợp vừa thanh toán vừa liên kết thẻ: <MERCHANT_RETURN_URL>?code=000&merchantSideUserId=XXXX&cancel=true

Trường

Kiểu

Mô tả dữ liệu

code

String

Mã lỗi (được mô tả trong Phụ lục 12.a)

merchantSideUserId

String

ID của người dùng bên phía Merchant

cancel

String

True: Người dùng hủy liên kết thẻ

False: Người dùng thực hiện xong quá trình liên kết thẻ

 

e. Demo API

- Data Request:

 
  {
      "tokenKey": "63vhaCjfe96SZlBH1ma200yUPBraqH",
      "orderCode": "orderTest000",
      "amount": 10000,
      "currency": "VND",
      "orderDescription": "mo ta don hang",
      "totalItem": 1,
      "checkoutType": 1,
      "returnUrl": "https://alepay-sandbox.nganluong.vn/demo/alepay/result.php",
      "cancelUrl": "https://alepay-sandbox.nganluong.vn/demo/alepay/",
      "buyerName": "lam",
      "buyerEmail": "lam@gmail.com",
      "buyerPhone": "0312345678",
      "buyerAddress": "Tam Trinh",
      "buyerCity": "Ha Noi",
      "buyerCountry": "Viet Nam",
      "paymentHours": 48,
      "merchantSideUserId": "test123",
      "buyerPostalCode": "100000",
      "buyerState": "Ha Noi",
      "isCardLink": true,
      "signature": "5197cb1e40aafa0bdaafbaf7f57291f524ae96a44e2726e95d6e79d98ceaaa5a"
  }
 

- Data Response:

  {
      "code": "000",
      "message": "Thành công",
      "signature": "cdb710b8e190c753ada26de607a969663b9b9d32ee87d6960a3aa10729256d04",
      "checkoutUrl": "https://alepay-v3-sandbox.nganluong.vn/checkout/vi/v3/index/4ec23520310541469543a2f1fe083b46",
      "transactionCode": "ALE00U1BD"
  }