Receive bill notification

2025-07-01 06:07

When a transaction is made using the WorldCard account, WorldFirst notifies you of the transaction details by calling this API.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

assetId String REQUIRED

The unique identifier of a card.

maskedCardNo String REQUIRED

The masked card number.

orderNo String REQUIRED

The order number.

cardNickName String

The WorldCard nickname.

transactionTime String REQUIRED

The time when the transaction is made.

More information:

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

merchantName String

The merchant name.

tradeAmount Amount REQUIRED

The transaction amount of an order.

Show child parameters

inAmount Amount

The amount of money returned to the WorldCard account after an order is placed, for example, a refund.

Show child parameters

outAmount Amount REQUIRED

The amount of money that leaves the WorldCard account after an order is placed.

Show child parameters

exchangeRate String

The exchange rate.

Formula: exchangeRate=outAmount/tradeAmount

When the outAmount.currency and tradeAmount.currency are the same, the value of this parameter, if returned, is always 1.

billType String REQUIRED

The type of the transaction.

Valid value is: CARD_PAYMENT.

tradeCountry String

Two-letter ISO3166 code that represents the country/region when the transaction is made.

More information:

Maximum length: 2 characters

billStatus String REQUIRED

The transaction status.

Valid values are:

WAITING_CLEARANCE
SUCCESS
FAILED
REFUNDED
CANCELLED
PARTIAL_CANCEL
PARTIAL_REFUND
WAITING_DEDUCT

billFailReason FailReason

The reason that indicates why the transaction has failed.

This field is returned when the value of billType is FAILED.

Show child parameters

lastUpdate String REQUIRED

The last time when the card bill was updated.

This parameter uses a timestamp such as 1722308496237.

balanceType String

Indicates different balance types.

Customers can use different types of balances to manage their funds separately to meet specific business needs and achieve better risk control.

Valid values are:

NORMAL_BALANCE: indicates the e-commerce balance.
SAME_NAME_TOP_UP_BALANCE: indicates the samename funds.
BUDGET_BALANCE: indicates the budget account balance.

budgetAccountId String

The unique ID that is assigned by WorldFirst to identify a budget account.

This field is required when the value of balanceType is BUDGET_BALANCE.

Response parameters

result Result REQUIRED

The result of the API call.

Respond to WorldFirst with this parameter to acknowledge the reception of the status change notification.

Show child parameters

API Explorer

Request

Request Body

Response

Response Body

Result processing logic

After receiving the result notification, you must send a response to acknowledge receipt.

Note: You must sign the message before making the response. For more information, see Sign a request and validate the signature and the Response header.

If you do not acknowledge receipt, WorldFirst will retry sending the result according to the following rules:

WorldFirst retries sending the notification up to 7 times.
Intervals between notifications: 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

billFailReason.resultCode

errorCode	errorDesc
WORLD_CARD_BALANCE_NOT_ENOUGH	Insufficient account balance.
WORLD_CARD_OVER_LIMIT	Insufficient daily/monthly limit.
WORLD_CARD_AVS_RESULT	AVS verification failed.
WORLD_CARD_ASSERT_ERROR	The card has expired.
WORLD_CARD_SECURITY_REJECT	Risk control rejection.
WORLD_CARD_INVALID_MERCHANT	Invalid merchant.
UN_KNOWN_EXCEPTION	Unknow reason.
WORLD_CARD_INVALID_AMOUNT	Invalid payment amount.
WORLD_CARD_INVALID_CARD_NUMBER	Invaild card number.
WORLD_CARD_EXPIRED_CARD	Card expired.
WORLD_CARD_INCORRECT_PIN	Incorrect PIN.
WORLD_CARD_INVALID_TRANSACTION	Abnormal transaction.
WORLD_CARD_EXCEED_WITHDRAW_AMOUNT_LIMIT	Withdrawal amount limit exceeded.
WORLD_CARD_EXCEED_WITHDRAW_FREQUENCY_LIMIT	Withdrawal frequency limit exceeded.
WORLD_CARD_VERIFICATION_FAILED	Verification failed.
WORLD_CARD_EXCEED_PIN_ALLOW_NUMBER	Exceeded allowed PIN attempts.
WORLD_CARD_AUTHENTICATION_REQUIRED	Authentication required.
WORLD_CARD_CVV2_FAILURE	CVV2 verification failed.
WORLD_CARD_INVALID_CARD	Invalid card.
BALANCE_ACCOUNT_NOT_AVAILABLE	Account status abnormal.
SYSTEM_ERROR	System error.

result.resultCode

Code	Value	Message	Further action
SUCCESS	S	Success	None
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	Human intervention is usually needed. Contact our Technical Support Team to resolve the issue.
UNKNOWN_EXCEPTION	U	API failed due to unknown reason.	The service might be down, please retry later. If the issue persists, contact our Technical Support Team.