Collection Webhook

Process

Description:

• When a virtual account receives money, Baokim sends a webhook (POST) to CashPlus's registered URL.
• CashPlus must:
  1. Verify signature in header Signature (see Security).
  2. Record transaction by TransIdBk.
  3. Return correct response format below so Baokim confirms successful send.
• After receiving the webhook, CashPlus registers share amounts for the transaction (using TransIdBk as TransactionId) before the 23:50:59 cutoff on the day the funds are received.

IsFull — Sender account information

Webhook always has IsFull field:

• IsFull = 0: Baokim doesn't have sender account information yet.
• IsFull = 1: Baokim has sender account information. Code is the User code if this account matches a CashPlus user who synced.

The first webhook is sent as soon as Baokim records the funds, even if sender account information is not yet available (IsFull = 0).

When sender account information becomes available later, Baokim sends exactly one update webhook with the same TransIdBk, IsFull = 1, and Code (if it matches a synced User). Transactions that already have IsFull = 1 in the first webhook do not get an update. CashPlus must not treat the update as a duplicate: update the sender information for the existing transaction and do not create a new transaction.

API Information

Method: POST

URL: Webhook URL provided by CashPlus to Baokim.

Header:

• Content-Type: application/json
• Signature: RSA-SHA1 signature (Base64) of raw body using Baokim's private key

Request

(Baokim sends to CashPlus)

Main Parameter Table

Field Name	Data Type	Required	Description
RequestId	String	✅	Request ID generated by Baokim
RequestTime	Datetime	✅	Send time. Format: YYYY-MM-DD HH:mm:ss
PartnerCode	String	✅	Always BAOKIM
AccNo	String	✅	Virtual account number that received funds
TransIdBk	String	✅	Baokim collection transaction ID, unique
TransAmount	Integer	✅	Transaction amount (VND)
TransTimeBk	Datetime	✅	Transaction time. Format: YYYY-MM-DD HH:mm:ss
TransFeeAmount	Integer	✅	Collection fee (VND)
AmountAfterFee	Integer	✅	TransAmount − TransFeeAmount
OrderId	String	✅	Order ID CashPlus provided when creating virtual account
Code	String	❌	User code of sender. null if not yet identified
Memo	String	✅	Transaction description. Empty string if none
IsFull	Integer	✅	0 = no sender account info, 1 = sender info complete

Request Example

{
  "RequestId": "BK8F3K2A",
  "RequestTime": "2025-01-15 10:30:45",
  "PartnerCode": "BAOKIM",
  "AccNo": "1234567890",
  "TransIdBk": "BK6AB9B10B92C04SZ",
  "TransAmount": 15000,
  "TransTimeBk": "2025-01-15 10:30:30",
  "TransFeeAmount": 990,
  "AmountAfterFee": 14010,
  "OrderId": "ORD202501150001",
  "Code": "USER001",
  "Memo": "Order payment",
  "IsFull": 1
}

Response

(CashPlus returns to Baokim)

note

HTTP 200 - Success

Main Parameter Table

Field Name	Data Type	Required	Description
ResponseCode	Integer	✅	200 = received. Other code → Baokim will resend
ResponseMessage	String	✅	Response message
ReferenceId	String	✅	CashPlus transaction ID corresponding to TransIdBk
AccNo	String	✅	Virtual account number of transaction (return received AccNo)

Response Example

{
  "ResponseCode": 200,
  "ResponseMessage": "Success",
  "ReferenceId": "CPTXN0001",
  "AccNo": "1234567890"
}

Retry Policy

Baokim confirms webhook sent successfully only when CashPlus returns HTTP 200, JSON body has all 4 fields ResponseCode, ResponseMessage, ReferenceId, AccNo, and ResponseCode = 200.

All other cases treated as failure and Baokim will resend:

• No response within 30 seconds.
• Connection error, HTTP 4xx/5xx.
• Body not JSON or missing one of 4 fields above.
• ResponseCode other than 200.

Number of sends: maximum 6 times (1 initial + 5 retries), at least 1 minute apart. After that Baokim stops. CashPlus uses Query transaction for reconciliation.

note

Idempotent processing by TransIdBk: if receiving same TransIdBk again (due to retry), return ResponseCode=200 and don't record transaction twice. Exception is supplementary webhook with IsFull = 1 described above.