Update BNPL Transaction

Flow

Description:

• Customer has completed down payment, merchant calls this API to update order status to "Down payment completed".
• Merchant does not want to continue with deferred payment and needs to cancel the order.

API Information

Method: POST

Request

(Parameters sent by the partner)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique ID of the request from Merchant to Baokim
2	request_time	String(20)	✅	Request sent time. Format: YYYY-MM-DD H:i:s
3	merchant_code	String(50)	✅	Unique merchant identifier
4	mrc_order_id	String(50)	✅	Merchant's order ID
5	reason	Text	❌	Reason for cancelling order. Required if cancelling

Request Example

{
  "request_id": "MERCHANT050015588AXE014",
  "request_time": "2020-08-11 14:41:00",
  "merchant_code": "MERCHANT",
  "mrc_order_id": "BK2231383795A6021334",
  "reason": "yêu cầu hủy đơn trả góp"
}

Response

(Parameters Baokim returns)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Number(3)	✅	Baokim error code
2	message	String(200)	✅	Error code message
3	data	Object	✅	Data returned

Data Information

No.	Field Name	Data Type	Required	Description
1	order_id	Number	✅	Baokim order ID
2	mrc_order_id	String(50)	✅	Merchant's order ID
3	merchant_code	String(50)	✅	Merchant code
4	customer_name	String(200)	✅	Full customer name, no accents with spaces
5	customer_phone	String(10)	✅	Customer phone number
6	customer_email	String(255)	✅	Customer email
7	customer_address	String(500)	✅	Customer address
8	package_code	String(255)	✅	Loan package code
9	name	String(20)	✅	Loan package name
10	period	Number	✅	Term (1, 3, 6, 9, 12 months)
11	min_amount	Number	✅	Minimum amount to apply for this loan package
12	max_amount	Number	✅	Maximum amount to apply for this loan package
13	down_payment_percent	Number	✅	% of down payment amount
14	down_payment_amount	Number	✅	Down payment amount
15	original_amount	Number	✅	Order amount
16	merchant_fee	Number	✅	Fee merchant pays
17	total_paylater_amount	Number	✅	Total deferred payment amount (includes fees)
18	payment_per_period	Number	✅	Payment amount per period
19	total_amount	Number	✅	Total amount user must pay (down payment + deferred)
20	difference_amount	Number	✅	Amount difference compared to straight payment
21	document_required	String(4)	✅	Documents required (CCCD/CMND)
22	provider_code	String(20)	✅	Finance provider code
23	description	String(255)	✅	Order description
24	url_success	String(255)	✅	URL Baokim redirects to when loan approved successfully
25	url_fail	String(255)	✅	URL Baokim redirects to when loan approval fails
26	status	Number	✅	Order status
27	extension	Object	✅	Extended information (Products, order, sales point)
28	created_at	Datetime	✅	Order creation time
29	updated_at	Datetime	✅	Order update time

Extension Information

No.	Field Name	Data Type	Required	Description
1	items	Array	✅	List of product information objects

Items Information

No.	Field Name	Data Type	Required	Description
1	item_id	String(50)	✅	Product ID
2	item_code	String(50)	✅	Product code
3	item_name	String(255)	✅	Product name
4	item_amount	Number	✅	Product price
5	quantity	Number	✅	Quantity
6	url	String(500)	✅	Product URL

Response Example

{
  "code": 0,
  "message": "Success",
  "data": {
    "order_id": 1870436,
    "mrc_order_id": "VLAD_1753867524",
    "merchant_code": "MERCHANT",
    "customer_name": "Nguyễn Trung Quân",
    "customer_phone": "0394827170",
    "customer_email": "[email protected]",
    "customer_address": "40, ngách 16/255 đường Láng, Đống Đa, Hà Nội",
    "package_code": "homecredit_1month",
    "name": "Home Credit 1 tháng",
    "period": 1,
    "min_amount": 1000000,
    "max_amount": 500000,
    "down_payment_percent": 20,
    "down_payment_amount": 2000000,
    "original_amount": 10000000,
    "merchant_fee": 100000,
    "total_paylater_amount": 8000000,
    "payment_per_period": 8000000,
    "total_amount": 10100000,
    "difference_amount": 100000,
    "document_required": "CCCD",
    "provider_code": "HOMECREDIT",
    "description": "Đơn hàng trả chậm",
    "url_success": "https://example.com/success",
    "url_fail": "https://example.com/fail",
    "status": 8,
    "extension": {
      "items": [
        {
          "item_id": 123456,
          "item_code": "AEIQ_4562",
          "item_name": "Máy tính xách tay ABC",
          "item_amount": 10000000,
          "quantity": 1,
          "url": "https://example.com/product-detail"
        }
      ]
    },
    "created_at": "2020-08-11 14:41:00",
    "updated_at": "2020-08-11 15:41:00"
  }
}

Error Codes

Error Code	Description
100	Success
101	System error
102	Provider error
104	JWT authentication error
105	Invalid digital signature
106	Insufficient order amount for refund
107	Order cannot be refunded
108	Order cannot be cancelled
109	Order does not exist
110	Merchant order code already exists
422	Validation error