Receive account balance notification

2022-11-15 07:14

Signature required

WorldFirst uses the notifyVostro API to notify the Partner once the account balance changes. For instance, during the prefunding process, WorldFirst notifies the Partner after the account is successfully prefunded.

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
fundingId	String	Yes	The unique ID that is assigned by WorldFirst to identify a prefunding request. Note: This field is an API idempotency field. The Partner can use this parameter to perform idempotency control. For details about API idempotency, see the Idempotency chapter. More information: Maximum length: 128 characters
balanceResult	Result object	Yes	Indicates whether the prefunding process is successful.
payerBankAccount	Bank Account object	No	The payer's account information.
beneficiaryAccount	Bank Account object	No	The beneficiary's account information.
balanceChangeAmount	Amount object	Yes	The changed amount of the account balance.
balanceChangeTime	DateTime	No	Indicate the time that WorldFirst 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`, or `2019-01-01T01:01:01Z`(UTC timezone).
remitInfo	String	No	An additional memo attached to the prefunding request.

Result processing logic

WorldFirst indicates the result of the prefunding process in the balanceResult.result field. For more information, refer to the Result codes section.

After receiving the notification, you need to send 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:

Signature: Required. Example: Signature: algorithm=RSA256, keyVersion=2, signature=*****
Content-Type: Required. Example: Content-Type: application/json; charset=UTF-8
Client-Id: Required. Example: Client-Id: *****
Response-Time: Required. Example: Response-Time: 2019-04-04T12:08:56+08:00

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"
  }
}

In the absense of an ackowledgement reponse from the Partner, WorldFirst will resend the result.

The following policy represents how WorldFirst makes retry attempts:

WorldFirst 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	Note: This indicates a collection success.
REFUND	S	Refund success	Note: This indicates a refund success.
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	Human intervention is usually needed. It is recommended that you contact our Technical Support Team to resolve the issue.

`result.resultCode`

System-related result codes

resultCode	resultStatus	resultMessage	Further action
SUCCESS	S	Success
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.
PROCESS_FAIL	F	A general business failure occurred. Do not retry.	Human intervention is usually needed. It is recommended that you contact our Technical Support Team to resolve the issue.
UNKNOWN_EXCEPTION	U	API failed due to unknown reason.	The service might be down, retry later. If the issue persists, contact our Technical Support Team.
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.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.	Ensure the HTTP method is `POST`.

Samples

Request

Request body sample

copy
{
  "fundingId": "*****",
  "balanceResult": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "payerBankAccount": {
    "accountNo": "*****",
    "bankBIC": "payerBic123",
    "bankName": "ping**",
    "bankRegion": "payerBCC123",
    "holderAddress": "payerAddress123",
    "holderName": {
      "fullName": "xy****"
    }
  },
  "beneficiaryAccount": {
    "accountNo": "*****",
    "bankBIC": "CHASHK*****",
    "holderName": {
      "fullName": "x***y"
    }
  },
  "balanceChangeAmount": {
    "currency": "HKD",
    "value": "3333"
  },
  "remitInfo": "*****"
}

Response

Response header sample

copy
{
"headers": {
  "Content-Type": "application/json",
  "client-id": "*****",
  "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*****"
  }
}

Response body sample

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