Khởi tạo VCN

⚠️ API này trả về kết quả tiếp nhận yêu cầu, không phải kết quả khởi tạo VCN cuối cùng (status chỉ có giá trị 2-Đang xử lý hoặc 4-Thất bại). Kết quả khởi tạo VCN thực tế (thông tin thẻ) được gửi qua Webhook thông báo thông tin VCN.

Quy trình

• MERCHANT gọi API để khởi tạo VCN.

Thông tin API

URL: /b2b-iccp-service/api/ext/mm/iccp/vcn-create

Method: POST

Request

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ừ MERCHANT sang Baokim.
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	reference_id	String(50)	✅	Mã tham chiếu
6	customer_name	String(255)	✅	Tên khách hàng
7	expiry	String(7)	✅	Ngày hết hạn trên thẻ VCN, format MM/YYYY expiry lớn hơn tối thiểu 1 tháng so với thời gian hiện tại và max 24 tháng so với thời điểm hiện tại
8	control_type	Number	✅	1: accountControl 2: inControlRules
9	account_control	Object	❌	Bắt buộc nếu control_type = 1
10	in_control_rules	Object	❌	Bắt buộc nếu control_type = 2
11	real_card_guid	String	✅	Mã định danh thẻ vật lý RCN Baokim cung cấp

Thông tin 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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

Mô tả dữ liệu bên trong in_control_rules.acceptor_ids.acceptors(1)

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 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 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(3)	❌	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 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 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 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 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 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 Mặc định: 704
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 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 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 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

{
  "request_id": "TT20260209163542",
  "request_time": "2026-03-24 16:28:32",
  "master_merchant_code": "MASTERMERCHANTCODE",
  "sub_merchant_code": "SUBMERCHANTCODE",
  "reference_id": "TT20260209163542",
  "customer_name": "NGUYỄN VĂN A",
  "expiry": "12/2026",
  "control_type": 1,
  "account_control": {
    "alias": "TT20260209163542",
    "card_limit": {
      "card_amount": 10000000000,
      "available_balance": 0,
      "authorisation_count": 100
    },
    "daily_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "weekly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "monthly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "quarterly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "yearly_limit": {
      "card_amount": 10000000000,
      "available_balance": 10000000000,
      "authorisation_count": 100
    },
    "geographies": {
      "country_codes": [
        "704",
        "840"
      ],
      "negate": 0
    },
    "merchant_category_codes": {
      "mccs": [
        "3001",
        "3005"
      ],
      "negate": 0
    },
    "start_date": "2025-12-01",
    "end_date": "2035-12-01"
  },
  "real_card_guid": "real_card_guid_test"
}

Ví dụ Request

{
  "request_id": "TT20260209163542",
  "request_time": "2026-03-24 15:33:06",
  "master_merchant_code": "MASTERMERCHANTCODE",
  "sub_merchant_code": "SUBMERCHANTCODE",
  "reference_id": "TT20260209163542",
  "customer_name": "NGUYỄN VĂN A",
  "expiry": "12/2026",
  "control_type": 2,
  "in_control_rules": {
    "alias": "TT20260209163542",
    "transaction_limits": {
      "amount": 100,
      "negate": 0
    },
    "velocities": {
      "max_trans": 100,
      "cumulative_limit": 1500000,
      "period": "CONTINUOUS",
      "negate": 0
    },
    "validity_periods": {
      "from": "2026-07-24 15:35:06",
      "to": "2035-12-01 00:00:00",
      "negate": 0
    },
    "acceptor_ids": {
      "acceptors": {
        "acceptor_id": "126548888899997",
        "acquirer_id": "12325435"
      },
      "negate": 0
    },
    "ageing_velocities": {
      "authorization_hold_days": 0,
      "cumulative_limit": 0,
      "time_zone": "UTC",
      "negate": 0
    },
    "time_of_days": {
      "times": [
        {
          "from_time": "00:00",
          "to_time": "23:59",
          "days": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY"
          ]
        }
      ],
      "time_zone": "UTC",
      "negate": 0
    },
    "merchant_names": {
      "merchant_names": [
        "Amazon"
      ],
      "negate": 0
    },
    "merchant_amounts": {
      "value": 10000000,
      "currency_code": "704",
      "negate": 0
    },
    "transaction_environments": {
      "environment_codes": [
        "ECOM",
        "POS"
      ],
      "negate": 0
    },
    "approve_control": {
      "negate": 0
    },
    "entry_modes": {
      "mode": "EMV",
      "negate": 0
    }
  },
  "real_card_guid": "real_card_guid_test"
}

Response

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	Number(3)	✅	Mã lỗi của Baokim
2	message	String(200)	✅	Thông báo mã lỗi của Baokim
3	data	Object	✅	Dữ liệu Baokim trả về

Thông tin data

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	reference_id	String	✅	Mã tham chiếu yêu cầu tạo VCN
2	status	Number	✅	Trạng thái tạo VCN 2: Đang xử lý 4: Thất bại
3	created_at	DateTime	✅	Thời gian tiếp nhận yêu cầu
4	updated_at	DateTime	✅	Thời gian cập nhật yêu cầu

Ví dụ Response - khi tạo yêu cầu thành công

{
  "code": 100,
  "message": "Success",
  "data": {
    "reference_id": "MERCHANT1774336134305",
    "status": 2,
    "created_at": "2026-03-24 16:33:47",
    "updated_at": "2026-03-24 16:33:47"
  }
}

Ví dụ Response - khi tạo yêu cầu thất bại

{
  "code": 11,
  "message": "Fail",
  "data": {
    "reference_id": "MERCHANT1774336134305",
    "status": 4,
    "created_at": "2026-03-24 16:33:47",
    "updated_at": "2026-03-24 16:33:47"
  }
}

Bảng mã lỗi

Mã lỗi	Mô tả
100	Thành công
11	Thất bại
104	Không được uỷ quyền
401	Merchant verify failed
422	Lỗi validate
1000	Lưu request ICCP thất bại
1001	Lưu thẻ VCN thất bại
1100	JWT không hợp lệ hoặc đã hết hạn
1101	Xác thực chữ ký thất bại
1200	master_merchant_code và sub_merchant_code không khớp cấu hình real_card_guid
1202	real_card_guid không tồn tại
1500	Request {request_id} đã tồn tại
1501	reference_id đã tồn tại
1502	Alias đã tồn tại