notifyCardBill
This API is used to notify the merchant or partner about the card bill.
Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：
Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
- If the data type of a field is Integer and its value is
20, set it as "20". - If the data type of a field is Boolean and its value is
true, set it as "true".
Request parameters
assetId String REQUIRED
The unique identifier of a card.
More information:
- Maximum length: 32 characters
maskedCardNo String REQUIRED
The masked card number.
More information:
- Maximum length: 16 characters
orderNo String REQUIRED
The unique identifier for a purchase/payment by issued card.
Notes:
- An order contains all card authorizations (bills) that belong to the same payment.
- One order may contain multiple bills (e.g., initial authorization, incremental authorization).
- This field is generated by the system when the first card authorization for a checkout is created.
- The field cannot be empty and is an alphanumeric combination.
More information:
- Maximum length: 32 characters
billNo String REQUIRED
The unique identifier for a single card authorization within an order.
Notes:
- Each card authorization creates exactly one bill. Multiple bills can belong to the same order.
- This field is generated by the system when a card authorization is processed.
- The field cannot be empty and is an alphanumeric combination.
More information:
- Maximum length: 32 characters
cardNickName String
The card nickname defined by the cardholder, which can help cardholders manage multiple cards more conveniently.
More information:
- Maximum length: 64 characters
transactionTime Datetime REQUIRED
The creation time of the transaction order.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
merchantName String
The merchant name.
More information:
- Maximum length: 64 characters
tradeAmount Amount REQUIRED
The transaction amount of an order.
inAmount Amount
The amount that flows into the card account after the order is placed, such as refunds.
outAmount Amount
The amount that flows out of the card account after the 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
Transaction type. The current default value is CARD_PAYMENT.
More information:
- Maximum length: 32 characters
tradeCountry String
Represents the two-letter ISO-3166 code of the country/region where the transaction occurred.
More information:
- Maximum length: 2 characters
billStatus String REQUIRED
The transaction status. Valid values are:
-
WAITING_CLEARANCE: Pending settlement. -
SUCCESS: Successful. -
FAILED: Failed. -
REFUNDED: Refunded. -
CANCELLED: Authorization canceled. -
PARTIAL_CANCEL: Partial authorization canceled. -
PARTIAL_REFUND: Partially refunded. -
WAITING_DEDUCT: Pending deduction.
More information:
- Maximum length: 32 characters
billFailReason FailReason
Transaction failure reason.
lastUpdate String REQUIRED
Last updated time.
More information:
- The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".
metadata Map<String, String>
Customer metadata in key-value format. The format range is as follows:
- Key maximum length: 32
- Value maximum length: 128
- Maximum number of keys: 30
- JSON string maximum length: 3096
More information:
- Maximum length: 3096 characters
Response parameters
result Result REQUIRED
The result of the API call.
Request
Response
billFailReason.errorCode
| Code | Value | Message |
|---|---|---|
| CARD_BALANCE_NOT_ENOUGH | F | Insufficient account balance. |
| CARD_OVER_LIMIT | F | Insufficient daily/monthly limit. |
| CARD_AVS_RESULT | F | AVS verification failed. |
| CARD_ASSERT_ERROR | F | The card has expired. |
| CARD_SECURITY_REJECT | F | Risk control rejection. |
| CARD_INVALID_MERCHANT | F | Invalid merchant. |
| UNKNOWN_EXCEPTION | F | Unknown reason. |
| CARD_INVALID_AMOUNT | F | Invalid payment amount. |
| CARD_INVALID_CARD_NUMBER | F | Invalid card number. |
| CARD_EXPIRED_CARD | F | Card expired. |
| CARD_INCORRECT_PIN | F | Incorrect PIN. |
| CARD_INVALID_TRANSACTION | F | Abnormal transaction. |
| CARD_EXCEED_WITHDRAW_AMOUNT_LIMIT | F | Withdrawal amount limit exceeded. |
| CARD_EXCEED_WITHDRAW_FREQUENCY_LIMIT | F | Withdrawal frequency limit exceeded. |
| CARD_VERIFICATION_FAILED | F | Verification failed. |
| CARD_EXCEED_PIN_ALLOW_NUMBER | F | Exceeded allowed PIN attempts. |
| CARD_AUTHENTICATION_REQUIRED | F | Authentication required. |
| CARD_CVV2_FAILURE | F | CVV2 verification failed. |
| CARD_INVALID_CARD | F | Invalid card. |
| BALANCE_ACCOUNT_NOT_AVAILABLE | F | Account status abnormal. |
| SYSTEM_ERROR | F | System error. |