Share amount registration

Procedure

Description:

• After receiving the collection webhook, CashPlus calls this API to register the amounts shared with the 3 receivers of the transaction:

Receiver	Field	Disbursement type
User (cashback)	User.Amount (U)	Always realtime
Merchant	Merchant.Amount (M)	Per Merchant.Type: realtime or T+1
CashPlus	Partner.Amount (P)	Always T+1

• This API only records the registered amounts; it does not transfer funds. Funds are disbursed only when CashPlus calls a Disbursement order for each receiver.
• Registration does not require a User account. If the User is not yet identified, U can still be registered; if no disbursement can be called for the User by cutoff, the U share goes to the Merchant.
• U + M + P must be less than or equal to N (see Overview). The remainder N − U − M − P (UnallocatedAmount) cannot be disbursed by order and is settled to the Merchant at cutoff.
• Each TransactionId is registered once only. Calling again with the same TransactionId (even with different amounts) → Baokim returns ResponseCode=200 with the allocation from the first call, no override. There is no API to modify registered amounts.

Registration deadline

• Accepted only before the 23:50:59 cutoff on day T (the day Baokim receives the funds), in Baokim system time (GMT+7) when the request is received.
• Past the deadline → 141; Baokim does not record it. The whole N is settled to the Merchant on T+1 (AUTO order, see Overview).
• Transactions whose funds are received between 23:50:59 and 23:59:59 on day T: registration is not accepted.
• Call it before 23:45 to avoid the request being processed after cutoff.

Fee waiver policy

Applies when the transaction meets both conditions:

• User.IsNewUser = 1 (new User).
• The sub-merchant has been registered with Baokim for no more than 3 months (counted from the first registration date that is still valid).

Type	Result	Quota
Collection fee waiver	Applied by Baokim immediately at registration: TransFeeAmount = 0, N = TransAmount. The response returns the new N	Number of uses per sub-merchant as announced by Baokim
Realtime Merchant disbursement fee waiver	The realtime Merchant disbursement order (Receiver=2, Type=1) of this transaction has FeeAmount = 0	Number of uses per sub-merchant as announced by Baokim, counted separately from the collection fee waiver

When the collection fee is waived, the U + M + P ≤ N check uses N after the waiver.

API Information

Method: POST

URL: {BASE_URL}/transaction/v2/share-amount

Header: Signature — RSA-SHA1 signature of raw body (see Security). Baokim verifies the signature before any other check.

Request

Main parameters

Field	Data type	Required	Description
RequestId	String	✅	Request ID. Max 50 characters, alphanumeric and hyphen only
RequestTime	Datetime	✅	Request time. Format: YYYY-MM-DD HH:mm:ss. Difference from Baokim time must not exceed 5 minutes
PartnerCode	String	✅	Merchant (sub-merchant) code of the collection transaction
TransactionId	String	✅	Baokim collection transaction ID (TransIdBk in collection webhook)
User	Object	✅	Share for User. See User table
Merchant	Object	✅	Share for Merchant. See Merchant table
Partner	Object	✅	Share for CashPlus. See Partner table

User

Field	Data type	Required	Description
Amount	Integer	✅	Cashback amount for User (VND), ≥ 0. 0 = no cashback; the other User fields are then optional. If not 0, minimum 4,500
IsNewUser	Integer	✅ (when Amount > 0)	1 = new User, 2 = existing User. Used for the fee waiver policy
Memo	String	✅ (when Amount > 0)	Default transfer content for the User disbursement order
Code	String	❌	Code of a User who has been synced, if already known. If provided, it must match the synced account (103)
AccNo	String	❌	User receiving account number, if already known (104)
BankNo	String	❌	Bank code of the receiving account, if already known (111)

The User's receiving account is fixed at the User Disbursement order, not at this step.

Merchant

Field	Data type	Required	Description
Amount	Integer	✅	Amount shared with Merchant (VND), ≥ 0. With Type=1 and not 0: must be greater than the realtime disbursement fee
Type	Integer	✅	Disbursement type for Merchant: 1 = realtime, 2 = T+1. The Merchant disbursement order must use exactly this Type
Memo	String	✅ (when Type = 1)	Transfer content for Merchant

Partner

Field	Data type	Required	Description
Amount	Integer	✅	Amount shared with CashPlus (VND), ≥ 0. Always T+1, free of charge

Request example

{
  "RequestId": "CP20250115100001",
  "RequestTime": "2025-01-15 10:00:01",
  "PartnerCode": "SHOP123",
  "TransactionId": "BK6AB9B10B92C04SZ",
  "User": {
    "Amount": 7000,
    "IsNewUser": 2,
    "Memo": "Hoan tien don hang 1001"
  },
  "Merchant": {
    "Amount": 6860,
    "Type": 1,
    "Memo": "Thanh toan don hang 1001"
  },
  "Partner": {
    "Amount": 150
  }
}

Response

note

HTTP 200 - Success

Main parameters

Field	Data type	Required	Description
ResponseCode	Integer	✅	Result code. 200 = registered (or already registered)
ResponseMessage	String	✅	Message
Data	Object	❌	Saved allocation. Present only when ResponseCode=200

Data

Field	Data type	Description
TransactionId	String	Baokim collection transaction ID
TransFeeAmount	Integer	Collection fee after applying the fee waiver policy
AmountAfterFee	Integer	N used for sharing
User	Object	Amount, Code, Memo, Type (always 1)
Merchant	Object	Amount, Type, Memo, FeeAmount (expected realtime disbursement fee; 0 if Type 2 or waived)
Partner	Object	Amount, Type (always 2)
UnallocatedAmount	Integer	Remainder N − U − M − P, goes to the Merchant at cutoff

Response example

{
  "ResponseCode": 200,
  "ResponseMessage": "Thành công",
  "Data": {
    "TransactionId": "BK6AB9B10B92C04SZ",
    "TransFeeAmount": 990,
    "AmountAfterFee": 14010,
    "User": {
      "Amount": 7000,
      "Code": null,
      "Memo": "Hoan tien don hang 1001",
      "Type": 1
    },
    "Merchant": {
      "Amount": 6860,
      "Type": 1,
      "Memo": "Thanh toan don hang 1001",
      "FeeAmount": 0
    },
    "Partner": {
      "Amount": 150,
      "Type": 2
    },
    "UnallocatedAmount": 0
  }
}

Error codes

Code	Description
200	Success (including duplicate TransactionId calls, returns first allocation)
11	Request failed (missing User/Merchant/Partner object or required fields)
101	Baokim processing error
102	RequestId or RequestTime invalid (wrong format or differs from Baokim time by more than 5 minutes)
103	User Code invalid (does not match the synced account)
104	User Account Number invalid
105	User Amount invalid (not an integer, < 0, or not 0 but below 4,500)
106	Merchant Amount invalid (not an integer, < 0, or Type=1 but insufficient for disbursement fee)
107	Merchant Type invalid
108	Partner Amount invalid
109	Total Amount invalid (U + M + P > N)
110	Partner Code invalid
111	User Bank No invalid
112	Transaction ID invalid (does not exist or does not belong to PartnerCode)
113	User memo invalid
114	Merchant memo invalid
115	User Is New User invalid
120	Signature incorrect
141	Past the 23:50:59 cutoff of the transaction day
143	Transaction was registered through API v1