WorldFirst DocsWorldFirst Docs

Receive bill notification

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

CodeValueMessageFurther action
SUCCESSSSuccess

None

PROCESS_FAILFA general business failure occurred. Do not retry.

Human intervention is usually needed. Contact our Technical Support Team to resolve the issue.

UNKNOWN_EXCEPTIONUAPI failed due to unknown reason.

The service might be down, please retry later. If the issue persists, contact our Technical Support Team.