Webhook thông báo thông tin VCN

Quy trình

• Baokim gọi API webhook của MERCHANT để gửi thông báo kết quả tạo VCN kèm theo thông tin VCN đã được mã hoá theo cơ chế mã hoá của Baokim.

• Trường hợp Đối tác không muốn nhận thẻ VCN, hãy response với code = 1600 để từ chối.

Thông tin API

URL: Merchant cung cấp

Method: POST

• Header:

  • Content-Type: Application/json

  • Signature: $signature

Baokim gửi lên Đối tác (Webhook)

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	request_id	String(100)	✅	Id duy nhất ứng với mỗi Request từ Baokim gửi sang Merchant
2	request_time	String(20)	✅	Thời gian gửi Request. Format: YYYY-MM-DD H:i:s
3	master_merchant_code	String(50)	✅	Mã định danh duy nhất cho MASTER MERCHANT
4	sub_merchant_code	String(50)	✅	Mã định danh duy nhất cho SUB MERCHANT
5	operation	String(50)	✅	CREATE_VCN
6	reference_id	String(50)	✅	Mã tham chiếu yêu cầu tạo VCN
7	status	Number	✅	Trạng thái tạo VCN 3: Thành công 4: Thất bại
8	card_data	Object	❌	Dữ liệu thẻ NULL nếu trạng thái tạo VCN thất bại
9	created_at	DateTime	✅	Thời gian tiếp nhận yêu cầu
10	updated_at	DateTime	✅	Thời gian cập nhật yêu cầu

Thông tin card_data

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	vcn_id	Number	✅	ID của VCN
2	card_info_encrypt	String	✅	Dữ liệu thẻ VCN đã được mã hoá
3	card_status	Number	✅	Trạng thái của thẻ VCN 1. Active
4	control_type	Number	✅	1: accountControl 2: inControlRules
5	account_control	Object	❌	Bắt buộc nếu control_type = 1
6	in_control_rules	Object	❌	Bắt buộc nếu control_type = 2

Thông tin object sau khi giải mã card_data.card_info_encrypt

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_number	String	✅	Số thẻ VCN
2	cvc	String	✅	Số CVC của thẻ
3	expiry	String(7)	✅	Ngày hết hạn thẻ
4	card_holder	String	✅	Tên chủ thẻ

Thông tin card_data.account_control

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	alias	String	✅	Mã unique gợi nhớ của Control
2	card_limit	Object	❌	Thiết lập giới hạn chung cho thẻ - trong suốt vòng đời thẻ
3	monthly_limit	Object	❌	Thiết lập giới hạn cho thẻ theo tháng
4	daily_limit	Object	❌	Thiết lập giới hạn cho thẻ theo ngày
5	weekly_limit	Object	❌	Thiết lập giới hạn cho thẻ theo tuần
6	quarterly_limit	Object	❌	Thiết lập giới hạn cho thẻ theo quý
7	yearly_limit	Object	❌	Thiết lập giới hạn cho thẻ theo năm
8	geographies	Object	❌	Thiết lập sử dụng thẻ theo khu vực địa lý
9	merchant_category_codes	Object	❌	Thiết lập sử dụng thẻ theo MCC
10	start_date	String	❌	Thời gian sử dụng thẻ - Bắt đầu
11	end_date	String	❌	Thời gian sử dụng thẻ - Kết thúc

Thông tin card_data.account_control.card_limit

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_amount	Number	✅	Giá trị giao dịch
2	available_balance	Number	❌	Số dư khả dụng readOnly -> Có giá trị thì truyền, MasterCard chỉ dùng để collect thông tin (nếu có), không dùng để validate thông tin
3	authorisation_count	Number	✅	Số lượng giao dịch

Thông tin card_data.account_control.monthly_limit

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_amount	Number	✅	Giá trị giao dịch
2	available_balance	Number	❌	Số dư khả dụng readOnly -> Có giá trị thì truyền, MasterCard chỉ dùng để collect thông tin (nếu có), không dùng để validate thông tin
3	authorisation_count	Number	✅	Số lượng giao dịch

Thông tin card_data.account_control.daily_limit

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_amount	Number	✅	Giá trị giao dịch
2	available_balance	Number	❌	Số dư khả dụng readOnly -> Có giá trị thì truyền, MasterCard chỉ dùng để collect thông tin (nếu có), không dùng để validate thông tin
3	authorisation_count	Number	✅	Số lượng giao dịch

Thông tin card_data.account_control.weekly_limit

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_amount	Number	✅	Giá trị giao dịch
2	available_balance	Number	❌	Số dư khả dụng readOnly -> Có giá trị thì truyền, MasterCard chỉ dùng để collect thông tin (nếu có), không dùng để validate thông tin
3	authorisation_count	Number	✅	Số lượng giao dịch

Thông tin card_data.account_control.quarterly_limit

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_amount	Number	✅	Giá trị giao dịch
2	available_balance	Number	❌	Số dư khả dụng readOnly -> Có giá trị thì truyền, MasterCard chỉ dùng để collect thông tin (nếu có), không dùng để validate thông tin
3	authorisation_count	Number	✅	Số lượng giao dịch

Thông tin card_data.account_control.yearly_limit

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_amount	Number	✅	Giá trị giao dịch
2	available_balance	Number	❌	Số dư khả dụng readOnly -> Có giá trị thì truyền, MasterCard chỉ dùng để collect thông tin (nếu có), không dùng để validate thông tin
3	authorisation_count	Number	✅	Số lượng giao dịch

Thông tin card_data.account_control.geographies

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	country_codes	Array	✅	Danh sách mã quốc gia - format 3 ký tự
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.account_control.merchant_category_codes

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	mccs	Array	✅	Danh sách MCC
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	alias	String	✅	Mã unique gợi nhớ của Control
2	transaction_limits	Object	❌	Thiết lập giới hạn số tiền/ mỗi giao dịch thẻ
3	geographies	Object	❌	Thiết lập sử dụng thẻ theo khu vực địa lý
4	velocities	Object	✅	Thiết lập giới hạn tần suất và/hoặc tổng số tiền giao dịch thẻ trong một khoảng thời gian nhất định
5	validity_periods	Object	❌	Kiểm soát thời gian hiệu lực của control
6	amount_ranges	Object	❌	Kiểm soát giá trị giao dịch trong khoảng min, max
7	acceptor_ids	Object	❌	Thiết lập kiểm soát cho phép các Merchant/Acquirer nào thẻ được phép thực hiện giao dịch
8	ageing_velocities	Object	❌	Thiết lập và kiểm soát hạn mức tín dụng khả dụng trên thẻ
9	curfews	Object	❌	Thiết lập kiểm soát giao dịch thẻ theo khung giờ trong các ngày nhất định, và có thể xác định múi giờ áp dụng
10	time_of_days	Object	❌	Thiết lập kiểm soát giao dịch thẻ theo trong các khung giờ cụ thể của từng ngày
11	merchant_category_codes	Object	❌	Thiết lập kiểm soát GD thẻ theo mã ngành nghề MCC của merchant
12	merchant_names	Object	❌	Thiết lập kiểm soát GD thẻ theo tên của Merchant (ĐVi chấp nhận thẻ)
13	merchant_amounts	Object	❌	Thiết lập kiểm soát GD thẻ theo số tiền mỗi giao dịch trên 1 loại tiền tệ cụ thể
14	transaction_environments	Object	❌	Thiết lập kiểm soát giao dịch thẻ theo Phương thức giao dịch
15	approve_control	Object	❌	Thiết lập kiểm soát GD thẻ - Toàn bộ rule thiết lập sẽ là cho approve/decline GD
16	entry_modes	Object	❌	Thiết lập kiểm soát GD theo loại hình thẻ

Thông tin card_data.in_control_rules.transaction_limits

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	amount	Float	✅	Giá trị giao dịch tối đa/ 1 giao dịch Giá trị này được setup theo billing currency của RCN đã đăng ký BPC min: 0 max: 99999999999999
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.geographies

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	country_codes	Array	✅	Danh sách mã quốc gia - format 3 ký tự
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.velocities

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	max_trans	Number	✅	Số lượng giao dịch tối đa được phép giao dịch trong 1 khoảng thời gian nhất định min: 1 max: 99999999
2	cumulative_limit	Number	✅	Số tiền giao dịch cộng dồn tối đa được phép giao dịch trong 1 khoảng thời gian nhất định min: 1000 max: 5000000
3	period	String	✅	Kỳ áp dụng - DAILY -> Hàng ngày - WEEKLY -> Hàng tuần - QUARTERLY -> Hàng quý - CONTINUOUS -> Từ lúc thiết lập và ko có ngày reset đếm/cộng dồn lại (bao giờ chạm ngưỡng thì báo) - MONTHLY -> Hàng tháng - YEARLY -> Hàng năm
4	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.validity_periods

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	from	String	✅	Thời gian bắt đầu hiệu lực của control
2	to	String	✅	Thời gian kết thúc hiệu lực của control
3	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.amount_ranges

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	min_amount	Float	✅	Số tiền giao dịch tối thiểu min: 0 max: 99999999999999 min_amount < max_amount
2	max_amount	Float	✅	Số tiền giao dịch tối đa min: 0 max: 99999999999999 min_amount < max_amount
3	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.acceptor_ids

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	acceptors	Object	✅	Có thể set merchant hoặc acquire
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.acceptor_ids.acceptors

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	acceptor_id	String	✅	Mã Merchant ID – định danh của đơn vị chấp nhận thẻ (merchant) nơi giao dịch diễn ra.
2	acquirer_id	String	✅	Mã Acquirer ID – định danh của ngân hàng/đơn vị thanh toán (acquirer) xử lý giao dịch cho merchant.

Thông tin card_data.in_control_rules.ageing_velocities

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	authorization_hold_days	Number	✅	Số ngày hold giao dịch trên thẻ ảo để tính toán khi nào reset lại Hạn mức tín dụng đang thiết lập min: 0 max: 9999
2	cumulative_limit	Number	✅	Hạn mức tổng Nếu truyền vào = 0 - Đồng nghĩa với unlimited (Bỏ qua giới hạn thiết lập này) min: 0 max: 99999999999999
3	time_zone	String	✅	Múi giờ áp dụng cho việc tính ngày và giờ để thực hiện unhold giao dịch để loại bỏ khỏi phần tính avaliableCredit
4	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.curfews

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	from_time	String	✅	Thời gian bắt đầu cho phép giao dịch.
2	to_time	String	✅	Thời gian kết thúc cho phép giao dịch (sau thời gian này, giao dịch bị từ chối)
3	time_zone	String	❌	Múi giờ áp dụng khung giờ trên Ví dụ: UTC
4	days	Array	✅	Danh sách các ngày trong tuần áp dụng giới hạn SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY. Được truyền multi, cách nhau dấu phẩy
5	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.time_of_days

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	times	Array	✅	Danh sách object cấu hình thời gian cho phép giao dịch (sau thời gian này, giao dịch bị từ chối) Có thể truyền 1 mảng các config
2	time_zone	String	✅	Múi giờ áp dụng cho khung giờ trên (fromTime-toTime) Lưu ý default áp dụng là GMT (không phải là timezone register cho RCN) Nên lưu ý phải truyền vào Example: UTC
3	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Mô tả dữ liệu object bên trong card_data.in_control_rules.time_of_days.times(1)

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	from_time	String	✅	Thời gian bắt đầu cho phép giao dịch.
2	to_time	String	✅	Thời gian kết thúc cho phép giao dịch (sau thời gian này, giao dịch bị từ chối)
3	days	Array	✅	Các ngày trong tuần áp dụng giới hạn SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY. Được truyền multi, cách nhau dấu phẩy

Thông tin card_data.in_control_rules.merchant_category_codes

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	mccs	Array	✅	Danh sách MCC
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.merchant_names

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	merchant_names	Array	✅	Danh sách merchant names (được gửi trong trường DE43 của thông điệp ủy quyền (authorization message) Tên này phải khớp với tên trong dữ liệu thanh toán của ngân hàng (trường DE43)
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.merchant_amounts

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	value	Float	✅	Số tiền tối đa/giao dịch theo currency_code thiết lập bên dưới min: 0 max: 99999999999999
2	currency_code	String	✅	Mã tiền tệ áp dụng theo chuẩn (ISO) 4217
3	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.transaction_environments

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	environment_codes	Array	✅	Danh sách các phương thức giao dịch - ATM – Giao dịch tại máy rút tiền tự động. - ECOM – Giao dịch thương mại điện tử (online). - MOTO – Mail Order/Telephone Order (đặt hàng qua thư/điện thoại, không có mặt thẻ và chủ thẻ). - PAYPASS – Thanh toán không tiếp xúc (contactless). - POS – Giao dịch trực tiếp tại cửa hàng (quẹt trên máy POS). - PWCB – Mua hàng kèm rút tiền mặt (Purchase with Cash Back).
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.approve_control

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Thông tin card_data.in_control_rules.entry_modes

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	mode	String	✅	Truyền loại hình thẻ chấp nhận thanh toán Default: EMV
2	negate	Number	✅	Xác định rule có bị áp dụng ngược lại không ? 1. true 0. false => Default

Ví dụ Request tạo thẻ thành công

{
  "request_id": "818bca12-f0aa-4152-ba27-e3bd4dcb3abe",
  "request_time": "2026-05-21 10:14:14",
  "master_merchant_code": "mmthiither22",
  "sub_merchant_code": "b2bthiither127",
  "operation": "CREATE_VCN",
  "status": 3,
  "reference_id": "TT1774927943",
  "card_data": {
    "vcn_id": 2393,
    "card_info_encrypt": "d3VY98QAQCvAmZsEj8u6JHHE7+sswy7cNluSXPy5HJc6Tf/fl9JFXK/GTdZdetE4sMw/bwjVn7HDRa/7Z2Lqjrmey5BHxYLBizRxZGsLMGSlm8PyBoZg8N8akGpORFa3cgWWbCOJji/MVl56jrN3UzoRgee43B+62HUObWwqAUM=",
    "card_status": 1,
    "control_type": 2,
    "account_control": null,
    "in_control_rules": {
      "alias": "TT1774927943",
      "velocities": {
        "period": "CONTINUOUS",
        "negate": 0,
        "max_trans": 100,
        "cumulative_limit": 1500000
      },
      "curfews": {
        "days": [
          "MONDAY",
          "TUESDAY",
          "WEDNESDAY"
        ],
        "negate": 0,
        "from_time": "00:00",
        "to_time": "23:59",
        "time_zone": "UTC"
      },
      "transaction_limits": {
        "amount": 100,
        "negate": 0
      },
      "validity_periods": {
        "from": "2026-03-31 10:34:22",
        "to": "2035-12-01 00:00:00",
        "negate": 0
      },
      "amount_ranges": {
        "negate": 0,
        "min_amount": 0,
        "max_amount": 100000000
      },
      "acceptor_ids": {
        "acceptors": {
          "acceptor_id": "126548888899997",
          "acquirer_id": "12325435"
        },
        "negate": 0
      },
      "ageing_velocities": {
        "negate": 0,
        "authorization_hold_days": 0,
        "cumulative_limit": 0,
        "time_zone": "UTC"
      },
      "time_of_days": {
        "times": [
          {
            "days": [
              "MONDAY",
              "TUESDAY",
              "WEDNESDAY"
            ],
            "from_time": "00:00",
            "to_time": "23:59"
          }
        ],
        "negate": 0,
        "time_zone": "UTC"
      },
      "merchant_category_codes": {
        "mccs": [
          "3001",
          "3005"
        ],
        "negate": 0
      },
      "merchant_names": {
        "negate": 0,
        "merchant_names": [
          "Amazon"
        ]
      },
      "merchant_amounts": {
        "value": 10000000,
        "negate": 0,
        "currency_code": "704"
      },
      "transaction_environments": {
        "negate": 0,
        "environment_codes": [
          "ECOM",
          "POS"
        ]
      },
      "approve_control": {
        "negate": 0
      },
      "entry_modes": {
        "mode": "EMV",
        "negate": 0
      }
    }
  },
  "created_at": "2026-03-31 10:32:34",
  "updated_at": "2026-05-21 10:14:14"
}

Ví dụ Request tạo thẻ thất bại

{
  "request_id": "818bca12-f0aa-4152-ba27-e3bd4dcb3abe",
  "request_time": "2026-05-21 10:14:14",
  "master_merchant_code": "MASTERMERCHANTCODE",
  "sub_merchant_code": "SUBMERCHANTCODE",
  "operation": "CREATE_VCN",
  "status": 4,
  "reference_id": "TT1774927943",
  "card_data": null,
  "created_at": "2026-03-31 10:32:34",
  "updated_at": "2026-05-21 10:14:14"
}

Đối tác phản hồi Webhook

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	String(4)	✅	code trả về cho phía Baokim, bảo đảm phía MERCHANT đã nhận được
2	message	String	✅	Message trả về cho phía Baokim
3	data	Object	❌	Dữ liệu Merchant trả về cho Baokim nếu có

Ví dụ Response chấp nhận webhook

{
  "code": 100,
  "message": "Success",
  "data": null
}

Ví dụ Response từ chối webhook

{
  "code": 1600,
  "message": "Reject",
  "data": null
}