WorldFirst DocsWorldFirst Docs

notifyBillResult

使用万里付卡进行交易后，万里汇会调用此接口将交易金额、交易结果等相关账单信息通知给集成商。

报文结构

万里汇接口的报文结构包括：请求头、请求体和响应体。关于头信息，详见：

入参

assetId String  REQUIRED

卡资产ID。

maskedCardNo String  REQUIRED

脱敏卡号。

orderNo String  REQUIRED

订单编号。

cardNickName String  

由用户定义的卡昵称，可以帮助用户更方便地管理多张万里付卡。

transactionTime DateTime  REQUIRED

交易单的创建时间。

更多信息：

  • 值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

merchantName String  

商户名称。

tradeAmount Amount  REQUIRED

交易金额。

Show child parameters

inAmount Amount  

下单后流入万里付卡账户的金额，如：退款。

Show child parameters

outAmount Amount  REQUIRED

下单后流出万里付卡账户的金额。

Show child parameters

exchangeRate String  

汇率值。

公式：exchangeRate = outAmount /tradeAmount

当 outAmount.currency 字段取值与 tradeAmount.currency 字段取值相同时，此字段的取值恒为1。

billType String  REQUIRED

交易类型。当前默认取值为CARD_PAYMENT。

tradeCountry String  

代表交易所在国家/地区的二字母ISO-3166 代码。

更多信息：

  • 最大长度：2 字符

billStatus String  REQUIRED

账单状态。可取值范围：

  • WAITING_CLEARANCE 待结算
  • SUCCESS 成功
  • FAILED 失败
  • REFUNDED 已退款
  • CANCELLED 授权取消
  • PARTIAL_CANCEL 部分授权取消
  • PARTIAL_REFUND 部分退款
  • WAITING_DEDUCT 待扣款

billFailReason FailReason  

交易失败原因。

此字段仅在 billStatus 字段取值为FAILED时返回。 

Show child parameters

balanceType String  

该字段表示客户拥有的不同余额类型。

客户在不同业务场景下，可使用不同的余额类型对资金余额做分隔管理，作用是为了风险管控。

此字段的可取值为：

  • NORMAL_BALANCE: 普通余额类型（即电商余额类型)。（默认）
  • SAME_NAME_TOP_UP_BALANCE: 同名充值余额类型。
  • BUDGET_BALANCE : 预算账户余额类型。

budgetAccountId String  

预算账户ID。

当 balanceType 字段取值为 BUDGET_BALANCE 时，此字段为必传。

lastUpdate String  REQUIRED

最后一次更新时间。

此字段的格式为13位时间戳，示例：1722308496237

出参

result Result  REQUIRED

代表 API 接口的调用结果。

Show child parameters
API Explorer

请求

请求体

响应

响应体

响应处理

在收到万里汇的请求之后，集成商需要向万里汇发送响应信息，以确认信息已收到。

发送响应信息前，集成商需正确加签。详见：生成签名及加验签 章节。

关于响应信息的头参数，详见：API概览-响应报文结构。

响应体范例：

Sample Code


如果集成商不向万里汇发送响应信息，万里汇会重新发送请求通知。万里汇重发通知的规则为：

  • 重试总数：7次
  • 两次重发请求之间的间隔：2分钟，10分钟，10分钟，1小时，2小时，6小时，15小时

billFailReason.resultCode

结果码

结果码信息

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

结果码值结果码信息行动建议
SUCCESSSSuccess
PROCESS_FAILFA general business failure occurred. Do not retry.

需要人工介入，联系万里汇技术支持以解决此问题。

UNKNOWN_EXCEPTIONUAPI failed due to unknown reason.

服务器错误，若稍后重试问题依旧，联系万里汇技术支持以解决问题。