Settlement

The figure below shows the entire process from the marketplace initiating split-funds settlement to Antom notifying the settlement result:

Figure 1. Settlement flow

1. Once the transaction is completed, the funds go into the sub-merchant's Antom settlement account and settlement cannot be initiated during the predefined settlement date.
2. Once the funds reach the predefined settlement date, the marketplace initiates a settlement request through the interface to split the funds.
3. Antom stores the funds in each side's Antom settlement account based on the split information in the settlement request.
4. Antom notifies the marketplace of the split settlement request's result.
5. Once the funds reach the predefined settlement date, Antom initiates a settlement and transfers the funds to all sides involved.
6. Antom notifies the marketplace of the transaction's settlement payment result.

Initiate settlement request

Before initiating a settlement request, the marketplace must obtain the earliest time that a payment can be initiated from Antom. This is obtained through the asynchronous notification of the notifyPayment API or through earliestSettlementTime in the return result of the inquiryPayment API.

When the transaction reaches the earliest settlement time, the marketplace can call the Settle API to initiate funds split and settlement. In the request, the marketplace needs to upload details of funds split and settlement via settlementDetails. An example is as follows:

{
  "settlementRequestId": "REQUEST_20230618160427985",
  "paymentId": "20230618194010800190188000009014801",
  "settlementDetails": [
    {
      "settleTo": "SELLER",
      "settlementAmount": {
        "currency": "BRL",
        "value": "100"
      }
    },
    {
      "settleTo": "MARKETPLACE",
      "settlementAmount": {
        "currency": "BRL",
        "value": "200"
      }
    }
  ]
}

A sample settlement response is as follows:

{
  "settlementRequestId": "REQUEST_2023061816065****",
  "settlementId": "2023061819401888819018800000901****",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

resultStatus in the response represents the result of whether the current settlement application is successful, and does not mean that the settlement has been successful.

Receive asynchronous notification for settlement

Multiple payments within the same account period are combined into a single payment to the settlement bank account of the marketplace or sub-merchant. Once the payment is made, Antom sends an asynchronous notification of the settlement result to the marketplace via notifySettlement API.

The marketplace must set the asynchronous notification address by editing Notification URL under the Integration Settings tab in Alipay Developer Center.

The following is an example of a settlement asynchronous notification:

{
  "settlementBatchId": "2023061819411188819018800000901****",
  "notifyType": "SETTLEMENT_RESULT",
  "settleTo": "SELLER",
  "referenceMerchantId": "MERCHANT_2023061813584****",
  "settlementArrivalTime": "2023-06-27T12:01:01+08:00",
  "actualSettlementAmount": {
    "currency": "BRL",
    "value": "20000"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

settleTo field in the notification indicates the object of the settlement, result.resultStatus indicates the result of the settlement. When the value of result.resultStatus is S, it means the settlement is successful, when the value of result.resultStatus is F, it means the settlement fails. You can view the failure reason through result.resultCode and the corresponding result.resultMessage.

Return the following message with fixed values to Antom after receiving the notification. If no such message is returned to Antom due to operation issues or network issues, Antom will send the notification again within 24 hours. The notification will be resent up to eight times or terminated after receiving the correct response, with an interval of 0 sec, 2 min, 10 min, 10 min, 1 h, 2 h, 6 h, and 15 h.

{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "success."
  }
}