Skip to main content

Timeout Handling

Recommendations​

The principles below are general recommendations, inferred from the Idempotency mechanism (request_id) described on the Security page — most of the original documentation for each API group (VA, BNPL, Installment, International Card, Master Basic/Pro, Master VA, Master Credit Card) does not have its own Timeout Handling section, so this is not yet an official spec confirmed by developers for each API.

Clients should set reasonable timeouts to avoid two extreme situations:

  • Infinite wait — causes application hang if server does not respond.
  • Cutting off too early — cancels requests while server is processing normally (especially for payment APIs that need time to process with banks).

Recommendation: set timeout to 30–60 seconds for transaction creation APIs.

Timeout Requirements​

When a timeout occurs, do not perform blind retry. Instead:

  1. Call the transaction status query API (Get Transaction Status) to check if the transaction was created.
  2. Only create a new transaction if confirmed that the transaction does not exist.

Idempotency Key​

request_id is a mandatory Idempotency key for all transaction creation APIs (Create Payment). When retrying after timeout, the merchant must keep the same request_id so Baokim recognizes this as a previously processed request and returns the old result instead of creating a new transaction — preventing duplicate charges.

Retryable APIs​

These APIs can be safely retried (idempotent by nature):

  • GET query transaction status
  • GET get bank list / loan packages

These APIs should not be blindly retried:

  • All transaction creation APIs (Create Payment, create order, create VA...) without a new request_id or without checking status first.

Special Notes for QRPay/QRGlobal​

When MERCHANT calls QRPay API without receiving a response:

  • Do not conclude transaction failed. Final status should always be based on webhook transaction notification or query result.

  • For Create QR Code API: call Query Transaction API using mrc_order_id to confirm if order was created before retrying. If retrying with an existing mrc_order_id, the system returns error 707.

  • For Refund API (asynchronous flow): if unable to receive acknowledgment, retry with a new request_id; the system ensures duplicate refund requests do not exceed the refundable amount of the original transaction.

  • No webhook received after expected wait time: MERCHANT should actively call Query Transaction API to sync status.

When MERCHANT calls the Deeplink API without receiving a response:

  • Do not conclude the transaction failed. Final status should always be based on the result notification from Baokim.
  • For the Create Deeplink API: do not retry immediately. Check whether request_id has already been processed before calling again. If retrying, use the same previous request_id to avoid creating a duplicate transaction.
  • Deeplink has an expiration (expired_at): if the Deeplink has expired and the user has not paid, a new Deeplink must be created with a new request_id.
  • For the Get Bank List API (GET): can be safely retried since it is a pure query API.