Chuyển tới nội dung chính

Tạo Thanh toán

API VA Flow

Đường dẫn​

  • URL: /cb-core/api/v1/payment/create
  • Method: POST
  • Mô tả: API này được sử dụng để tạo thanh toán. Hiện tại chúng tôi chỉ hỗ trợ phương thức thanh toán VA, các phương thức thanh toán khác sẽ được hỗ trợ sớm

Request​

Bảng Request​

Tham sốLoại dữ liệu + Độ dàiBắt buộcMô tả
request_idstring(50)CóID request duy nhất, định dạng gợi ý: MerchantCode+YYYYMMDDHHMMSS+UniqueId
request_timestring(19)CóThời gian request theo định dạng: YYYY-MM-DD HH:MM:SS
merchant_codestring(20)CóMã merchant được Baokim cung cấp trước khi tích hợp
sub_merchant_codestring(20)CóNếu Seller nằm dưới sub-merchant của bạn, điền mã sub merchant được Baokim cung cấp.
Nếu Seller nằm dưới bạn, điền Merchant_code được Baokim cung cấp như trên
seller_idstring(50)CóID Seller trong hệ thống merchant
merchant_payment_idstring(50)CóID thanh toán của merchant
amountdecimal(12,2)CóSố tiền thanh toán
currencystring(3)CóMã tiền tệ của đơn. Điền VND cho giao dịch VND
descriptionstring(255)CóMô tả thanh toán
payment_methodstring(20)CóPhương thức thanh toán: ATM/CREDIT/VA/QRCODE
cardobjectCó điều kiệnThông tin thẻ yêu cầu nếu phương thức thanh toán là ATM/CREDIT
card.typestring(20)Có điều kiệnLoại thẻ: ATM/CREDIT
card.informationstring(500)Có điều kiệnThông tin thẻ. Thông tin thẻ được mã hóa. Nếu save_token là true, trường này không bắt buộc. Nếu save_token là false, trường này bắt buộc.
extensionsobjectKhôngMở rộng của đơn. extensions.key1 = value1, extensions.key2 = value2
payment_urlstring(255)CóURL của website nơi giao dịch được tạo
payment_expirestring(19)CóThời gian hết hạn của đơn. Thời gian tối đa là 30 phút kể từ khi thanh toán được tạo. Định dạng: YYYY-MM-DD HH:MM:SS

Ví dụ Request​

Ví dụ request cho phương thức thanh toán QRCODE/VA​

{
  {
    "request_id": "MERCHANT12345678901234510281",
    "request_time": "2024-11-15 14:36:00",
    "merchant_code": "PHUONGTT",
    "sub_merchant_code": "SUBPHUONGTT",
    "seller_id": "SELLER12345678901234510281",
    "merchant_payment_id": "1234567890",
    "amount": "300000.00",
    "currency": "VND",
    "payment_method": "VA",
    "payment_period": "2024-11-15 15:36:00",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    },
    "payment_url": "https://baokim.vn",
    "payment_expire": "2024-11-15 15:36:00"
  }
}

Ví dụ request cho phương thức thanh toán ATM/CREDIT​

(Lưu ý: Mã hóa thông tin thẻ trước khi gửi request) card.information là chuỗi được mã hóa base64, được mã hóa bằng AES-256-CBC. Key và iv sẽ được Baokim gửi cho merchant trước khi tích hợp.

Ví dụ thông tin thẻ trước khi mã hóa​
{
  "number": "4242424242424242",
  "first_name": "A",
  "last_name": "Nguyen Van",
  "expiration_month": "12",
  "expiration_year": "2025",  
  "security_code": "123",
  "country": "Viet Nam",
  "cvn": "123"
}
Ví dụ thông tin thẻ sau khi mã hóa​
{
  "card": {
    "information": "5f+7bD4XzMZGdfm7hXV2YmtlnMZ5PtHmsnU4v+NdeLg=",
  }
}
Ví dụ request body sử dụng thẻ tín dụng​
{
  "request_id": "MERCHANT12345678901234510281",
  "request_time": "2024-11-15 14:36:00",
  "merchant_code": "PHUONGTT",
  "sub_merchant_code": "SUBPHUONGTT",
  "seller_id": "SELLER12345678901234510281",
  "merchant_payment_id": "1234567890",
  "amount": "300000.00",
  "currency": "VND",
  "payment_method": "ATM",
  "card": {
    "type": "ATM",
    "information": "5f+7bD4XzMZGdfm7hXV2YmtlnMZ5PtHmsnU4v+NdeLg=",
  }
}

Response​

Bảng Response​

Tham sốLoại dữ liệu + Độ dàiBắt buộcMô tả
response_codeint(4)CóMã lỗi từ Baokim theo Bảng mã lỗi
response_messagestring(100)CóMô tả mã lỗi từ Baokim theo Bảng mã lỗi
dataobjectCóDữ liệu của response
data.merchant_codestring(20)CóMã merchant được Baokim cung cấp trước khi tích hợp
data.sub_merchant_codestring(20)CóMã sub merchant được Baokim cung cấp trước khi tích hợp
data.seller_idstring(100)CóID Seller trong hệ thống merchant
data.order_codestring(20)CóMã đơn hàng trong hệ thống Baokim. Mã này là duy nhất
data.paymentobjectCóDữ liệu thanh toán
data.payment.transaction_idstring(100)CóMã giao dịch trong hệ thống Baokim. Mã này là duy nhất
data.payment.amountdecimal(12,2)CóSố tiền giao dịch
data.payment.merchant_payment_idstring(100)CóMã tham chiếu của đơn hàng được quản lý trong hệ thống của bạn. Mã này là duy nhất
data.payment.currencystring(3)CóTiền tệ của đơn hàng
data.payment.va_infoobjectCóThông tin tài khoản ảo khi phương thức thanh toán là VA
data.payment.va_info.qr_codestring(255)Có điều kiệnMã QR của đơn hàng nếu phương thức thanh toán là QRCODE/VA
data.payment.va_info.qr_pathstring(255)Có điều kiệnĐường dẫn QR code của đơn hàng nếu phương thức thanh toán là QRCODE/VA
data.payment.va_info.account_namestring(255)Có điều kiệnTên tài khoản của đơn hàng nếu phương thức thanh toán là QRCODE/VA
data.payment.va_info.account_nostring(255)Có điều kiệnSố tài khoản của đơn hàng nếu phương thức thanh toán là QRCODE/VA
data.payment.va_info.bank_nostring(255)Có điều kiệnMã ngân hàng của đơn hàng nếu phương thức thanh toán là QRCODE/VA
data.payment.va_info.bank_branchstring(255)Có điều kiệnChi nhánh ngân hàng của đơn hàng nếu phương thức thanh toán là QRCODE/VA

Ví dụ Response​

{
  "response_code": 200,
  "response_message": "Success",
  "data": {
    "merchant_code": "PHUONGTT",
    "sub_merchant_code": "PHUONGTT",
    "seller_id": "SELLER12345678901234510281",
    "order_code": "ORDER12345678901234510281",
    "payment": {
      "transaction_id": "TRANSACTION12345678901234510281",
      "amount": "300000.00",
      "merchant_payment_id": "1234567890",
      "currency": "VND",
      "payment_method": "VA",
      "va_info": {
        "qr_code": "ORDER12345678901234510281",
        "qr_path": "https://example.com/qr/ORDER12345678901234510281.jpg",
        "account_name": "BAOKIM PHUONGTT",
        "account_no": "963336009805939",
        "bank_no": "970418",
        "bank_branch": "Hà Nội"
      }
    }
  }
}

Mã lỗi​

Mã ResponseThông báo Response
200Thành công
99Đang xử lý
11Thất bại
101Lỗi hệ thống
110Mã merchant không hợp lệ
120Signature không hợp lệ
422Lỗi xác thực