API Khởi tạo đơn hàng

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

T

  

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

customMerchantId

String

T

  

Mã khách 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ệ (VND)

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

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

3. Thanh toán ngay với thẻ quốc tế và nội địa (ATM, IB,QRCODE, VA, VIETQR, BANK_TRANSFER_ONLINE), thanh toán trả góp thiết lập allowDomestic = true 

4. Thanh toán ngay với thẻ quốc tế và nội địa (ATM, IB, QRCODE, VA, VIETQR, BANK_TRANSFER_ONLINE) thiết lập allowDomestic = true

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 bằng ATM, IB, VIETQR ,QRCODE, BANK_TRANSFER_ONLINE (data có được sau khi gọi api): POST /get-list-banks 

Hoặc Mã ngân hàng cho phép User thực hiện thanh toán trả góp với thẻ quốc tế (data có được sau khi gọi api): POST /get-installment-info

paymentMethod

String

F

  

Phương thức thanh toán: 

Trường hợp thanh toán ngay: 

- ATM_ON: thanh toán bằng thẻ ATM 

- IB_ON: thanh toán bằng tài khoản IB 

- QRCODE: thanh toán bằng cách quét

mã QRCODE (tạm đóng)

- VIETQR: thanh toán bằng cách quét mã

QRCODE napas247 (Ví điện tử)

- VA: Thanh toán quét mã VietQr (QRcode Napas247) | chuyển khoản 24/7

- BANK_TRANSFER_ONLINE: thanh

toán bằng hình thức chuyển khoản tự

động thành công (tạm đóng)

- APPLEPAY: Thanh toán bằng Apple Pay

- GOOGLEPAY: Thanh toán bằng GooglePay

Trường hợp thanh toán trả góp: paymentMethod là Loại thẻ cho phép user thực hiện thanh toán trả góp gồm VISA, MASTER, JCB, AMERICAN_EXPRESS, NAPAS_CREDIT

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

F

  

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

promotionCode

String

F

  

Mã chương trình khuyến mại

allowDomestic

Boolean

F

False

True: Cho phép thanh toán bằng thẻ ATM/ IB hoặc QRCODE, VA, VIETQR, BANK_TRANSFER_ONLINE

False: Cho phép chỉ thanh toán bằng thẻ quốc tế

language

String

F

vi

Ngôn ngữ hiển thị trên trang checkout. 

vi – tiếng Việt or  en – tiếng Anh

cashback

Integer

F

  

1: Giao dịch áp dụng CTKM Cashback

discount

Integer

F

  

1: Giao dịch áp dụng CTKM Ngân Lượng Discount

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 9.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

Kiểu

Mô tả dữ liệu

errorCode

String

Mã lỗi (được mô tả trong Phụ lục 9.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.

 

e. Demo API

- Data Request:

  {
      "allowDomestic": true,
      "amount": 3000000,
      "bankCode": null,
      "cashback": null,
      "buyerAddress": "18 Tam Trinh",
      "buyerCity": "Hà Nội",
      "buyerCountry": "Việt Nam",
      "buyerEmail": "virtual_buyer@alepay.vn",
      "buyerName": "Virtual Buyer",
      "buyerPhone": "0321654987",
      "cancelUrl": "https://alepay-v3-sandbox.nganluong.vn/cancel_url",
      "checkoutType": 3,
      "currency": "VND",
      "customMerchantId": "20112000",
      "installment": false,
      "language": "vi",
      "month": null,
      "orderCode": "ALE30_API_1110",
      "orderDescription": "Description",
      "paymentHours": 0.5,
      "paymentMethod": null,
      "promotionCode": null,
      "returnUrl": "https://alepay-v3-sandbox.nganluong.vn/return_url",
      "signature": "885d6a832e90cbc06ad1596ee572378919e2863835442be19d99a0c4f24647bb",
      "tokenKey": "SI85PMt00k9SfmIbupQinvHVPCHYUd",
      "totalItem": 1
  }

- Data Response:

  {
      "code": "000",
      "message": "Thành công",
      "signature": "fc3810a30768bbee84ce7531b5115a53af5bec51d40026c62fdceb052e6652e9",
      "checkoutUrl": "https://alepay-v3-sandbox.nganluong.vn/checkout/vi/v3/index/3b8b309e63cd4634a585bea5157e4545",
      "transactionCode": "ALE00U0H8"
  }