Skip to main content

Create Payment

API VA Flow

Path​

  • URL: /cb-core/api/v1/payment/create
  • Method: POST
  • Description: This API is used to create an payment. Now we only support payment method is VA, another payment method will be supported soon

Request​

Request Table​

ParamsData Type + LengthRequiredDescription
request_idstring(50)YesUnique request ID, suggested format: MerchantCode+YYYYMMDDHHMMSS+UniqueId
request_timestring(19)YesRequest time in format: YYYY-MM-DD HH:MM:SS
merchant_codestring(20)YesMerchant code provided by Baokim before integration
sub_merchant_codestring(20)YesIf the Seller is under your sub-merchant, fill your sub merchant code provided by Baokim.
If Seller is under you, fill your Merchant_code provided by Baokim as above
seller_idstring(50)YesSeller ID on merchant's system
merchant_payment_idstring(50)YesMerchant payment's ID
amountdecimal(12,2)YesAmount of the payment
currencystring(3)YesThe currency code of the order Fill VND for VND transaction
descriptionstring(255)YesDescription of the payment
payment_methodstring(20)YesPayment method ATM/CREDIT/VA/QRCODE
cardobjectConditionalCard information required if payment method is ATM/CREDIT
card.typestring(20)ConditionalCard type ATM/CREDIT
card.informationstring(500)ConditionalCard information Encrypted card information. If save_token is true, this field is not required. If save_token is false, this field is required.
extensionsobjectNoExtension of the order. extensions.key1 = value1, extensions.key2 = value2
payment_urlstring(255)YesURL of website where transaction is created
payment_expirestring(19)YesThe expired time of the order. Maximum time is 30 minutes since the payment of order is created. Format: YYYY-MM-DD HH:MM:SS

Request Example​

Request example for payment method is 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"
  }
}

Request example for payment method is ATM/CREDIT​

(Note: Encrypt card information before sending request) card.information is a base64 encoded string, which is encoded using AES-256-CBC encryption. Key and iv will be sent to merchant by Baokim before the integration.

Card information example before encryption​
{
  "number": "4242424242424242",
  "first_name": "A",
  "last_name": "Nguyen Van",
  "expiration_month": "12",
  "expiration_year": "2025",  
  "security_code": "123",
  "country": "Viet Nam",
  "cvn": "123"
}
Card information example after encryption​
{
  "card": {
    "information": "5f+7bD4XzMZGdfm7hXV2YmtlnMZ5PtHmsnU4v+NdeLg=",
  }
}
Example request body using credit card​
{
  "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​

Response Table​

ParamsData Type + LengthRequiredDescription
response_codeint(4)YesError code from Baokim as per Error Codes Table
response_messagestring(100)YesDescription of the error code from Baokim as per Error Codes Table
dataobjectYesData of the response
data.merchant_codestring(20)YesMerchant code provided by Baokim before integration
data.sub_merchant_codestring(20)YesSub merchant code provided by Baokim before integration
data.seller_idstring(100)YesSeller ID on merchant's system
data.order_codestring(20)YesThe order code in Baokim system. This code is unique
data.paymentobjectYesData of the payment
data.payment.transaction_idstring(100)YesThe transaction code in Baokim system. This code is unique
data.payment.amountdecimal(12,2)YesAmount of the transaction
data.payment.merchant_payment_idstring(100)YesThe reference code of order managed in your system. This code is unique
data.payment.currencystring(3)YesCurrency of the order
data.payment.va_infoobjectYesInfomation of virtual account when payment method is VA
data.payment.va_info.qr_codestring(255)ConditionalQR code of the order if payment method is QRCODE/VA
data.payment.va_info.qr_pathstring(255)ConditionalQR code path of the order if payment method is QRCODE/VA
data.payment.va_info.account_namestring(255)ConditionalAccount name of the order if payment method is QRCODE/VA
data.payment.va_info.account_nostring(255)ConditionalAccount number of the order if payment method is QRCODE/VA
data.payment.va_info.bank_nostring(255)ConditionalBank number of the order if payment method is QRCODE/VA
data.payment.va_info.bank_branchstring(255)ConditionalBank branch of the order if payment method is QRCODE/VA

Response Example​

{
  "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"
      }
    }
  }
}

Error Code​

Response CodeResponse Message
200Success
99Pending
11Failed
101System Error
110Merchant Code Invalid
120Invalid Signature
422Validation Error