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 nickname that the user gives to WorldCard.
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.
inAmount Amount
The amount of money that goes back to the WorldCard account after an order is placed, for example, a refund.
outAmount Amount REQUIRED
The amount of money that goes out of the WorldCard account after an order is placed.
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_CLEARANCESUCCESSFAILEDREFUNDEDCANCELLEDPARTIAL_CANCELPARTIAL_REFUNDWAITING_DEDUCT
lastUpdate String REQUIRED
The last time when the card bill was updated.
This parameter uses a timestamp such as 1722308496237.
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.
Request
Response
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: 2m, 10m, 10m, 1h, 2h, 6h, and 15h.
result.resultCode
| Code | Value | Message | Further action |
|---|---|---|---|
| SUCCESS | S | Success | |
| 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. |