WorldFirst DocsWorldFirst DocsDOCS

notifyBalance

Signature required

WorldFirst(Alipay) uses the notifyBalance interface to notify the Partner once WorldFirst(Alipay) receives the prefunding deposits and credits the prefunding balance.

When WorldFirst(Alipay) receives the prefunding deposits from banking institutions, it takes less than 30 minutes to process the prefunding deposits. Partner can either wait for the notification about the prefunding result or make active inquiries with the inquiryBalance interface.

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

Field

Data type

Required

Description

balanceResult

Result object

Yes

Result of the prefunding balance.

payerAccount

Account object

No

The payer's account information.

beneficiaryAccount

Account object

No

The beneficiary's account information.

balanceChangeAmount

Amount object

Yes

The changed amount of the prefunding balance.

balanceChangeTime

DateTime object

No

Indicate the time that WorldFirst(Alipay) receives the prefunding deposit.

Note:

  • The value of this field follows the ISO 8601 standard format. For example, 2019-01-01T01:01:01+08:00.

fundingId

String

Yes

The unique ID assigned by WorldFirst(Alipay) to identify a prefunding request.

Note:

  • This field is an API idempotency field. Partner can use this parameter to perform idempotency control. For details about API idempotency, see the Idempotency chapter.

More information:

  • Maximum length: 128 characters

Result processing logic

In the request message:

  • The balanceResult.resultCode field indicates the result of the prefunding process. For more information, refer to the Result codes section.

After receiving the notification from WorldFirst(Alipay), the Partner needs to send WorldFirst(Alipay) a response message to acknowledge the receipt of the notification.

The Partner needs to properly sign the message before making the response. For details, refer to the Sign a request and validate the signature chapter.

The response header observes the following structure:

Header field

Required

Code sample

Signature

Yes

Signature: algorithm=RSA256, keyVersion=2, signature=****

Content-Type

Yes

Content-Type: application/json; charset=UTF-8

Client-Id

Yes

Client-Id: ****

Response-Time

Yes

Response-Time: 2019-04-04T12:08:56+08:00

Sample response header:

copy
{
"headers": {
  "Content-Type": "application/json",
  "client-id": "5J5Y2Z1GSG5ET508239",
  "response-time": "2022-03-07T07:49:27Z",
  "signature": "algorithm=RSA256,keyVersion=1,signature=VelVji6jp8UJVrBUvZrwij8uPmjc//hfmVJqCCW0x+Yh/HEs5pz9wiMyYLRjykTOii+f5EznxcFIUxPae5KITe3fChufJzFhJ4iku5U/w6exmBWVR5vrvQZSYO0vG5aJKwUQW/jjgaUWg1d+ySmaJ0VZ0pniQRtwYRGCvzdey+gI0+jMFbChIQDemZ0uLCExRQ0SBKAjEH/Vq14KlY88Wr2bR829tqsxaECSq2M5eeDC7j6FGPMazfX1W+EGqa2go2Hif6BnodwXzNsEAfQlUrbwCi9Ey/uNO4ScTX6FVG1nb+q8/k09wTkCz/nHnwTQolDrLRndZqZfz79a344/FQ=="
  }
}

For more details about the response message, refer to the API overview chapter.

The response body has the following fixed value:

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

If the Partner does not respond to WorldFirst(Alipay) that the notification has been received successfully, WorldFirst(Alipay) will resend the result.

The following policy represents how WorldFirst(Alipay) makes retry attempts:

  • WorldFirst(Alipay) retries notifications 7 times.
  • Intervals between notifications: 2m, 10m, 10m, 1h, 2h, 6h, and 15h.

Response parameters

Field

Data type

Required

Description

result

Result object

Yes

Indicates whether this API is called successfully.

Result codes

balanceResult.resultCode

resultCode

resultStatus

resultMessage

Further action

SUCCESS

S

Success

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

Human intervention is usually needed. It is recommended that you contact WorldFirst Technical Support to resolve the issue.

result.resultCode

resultCode

resultStatus

resultMessage

Further action

SUCCESS

S

Success

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

Human intervention is usually needed. It is recommended that you contact WorldFirst Technical Support to resolve the issue.

PARAM_ILLEGAL

F

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

Check and verify whether the request fields, including the header fields and body fields, are correct and valid.

For details on the fields of each API, see the specific API Structure section.

INVALID_API

F

The called API is invalid or not active.

Check whether the correct API is being called.

INVALID_CLIENT

F

The client is invalid.

The Client ID does not exist or is invalid.

INVALID_SIGNATURE

F

The signature is invalid.

Make sure the request is properly signed with a valid signature. For more details, refer to the following chapter:

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

Ensure the HTTP method is POST.

UNKNOWN_EXCEPTION

U

The API call is failed, which is caused by unknown reasons.

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

Samples

Request

copy
{
  "payerAccount": {
    "holderName": {
      "fullName": "zhangsan"
    },
    "accountNo": "23****",
    "bankName": "SampleName"
  },
  "beneficiaryAccount": {
    "holderName": {
      "fullName": "Lisi"
    },
    "accountNo": "23****",
    "bankName": "SampleName",
    "bankBIC": "CHAS****"
  },
  "balanceChangeAmount": {
    "value": "1200",
    "currency": "USD"
  },
  "balanceChangeTime": "2019-01-01T12:08:56+08:00",
  "balanceResult": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "success"
  },
  "fundingId": "********"
}

Response

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

@2024 WorldFirst