notifyPayment

2023-08-23 02:37

Signature required

Once the payment order is completed, WorldFirst notifies the Partner with this API. The Partner needs to make a response for acknowledgment of receipt.

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
result	Result object	Yes	Indicates the result of the payment order.
notifyType	String	Yes	Defines the type of notification that WorldFirst sends to the Partner. Valid values are: `PAYMENT_RESULT`: The payment order is concluded and a result is returned. `PAYMENT_PROCESS`: The payment is still being processed.
payToAmount	Amount object	Yes	The amount of the payment that the Beneficiary receives.
payToId	String	Yes	The unique ID that is assigned by WorldFirst to identify each payment. More information: Maximum length: 64 characters
payToRequestId	String	Yes	The unique ID that is assigned by the Partner to identify each payment. Note: This field is an API idempotency field. For details about API idempotency, refer to the Idempotency chapter. More information: Maximum length: 64 characters
paymentId	String	Yes	The unique ID that is assigned by WorldFirst to identify the payment. More information: Maximum length: 64 characters
paymentTime	DateTime object	Yes	The time that WorldFirst finishes processing the payment and returns the payment result to the Partner. Note: The value of this field follows the ISO 8601 standard format and +08:00 timezone. For example, `2018-09-03T00:00:00+08:00`.
paymentAmount	Amount object	Yes	The amount of the payment that the Customer needs to pay.
paymentDetailSummaries	Array<PaymentDetailSummary object>	Yes	Details about the payment, such as the payment amount, payment method, etc.

Response parameters

Field	Data type	Required	Description
result	Result object	Yes	Indicates whether this API is called successfully.

Result processing logic

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

Note:
The Partner needs to properly sign the message before making the response. The process is the same as sign a request message. For details, refer to the Sign a request and validate the signature chapter.
Method: HTTP POST
URI is defined by the paymentNotifyUrl field in the createCashierPayment API. For example, when the address for the notification is https://{domain_name}.com/in1d/conasdtroller/pay/manag, URI is /in1d/conasdtroller/pay/manag

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": "*****",
  "response-time": "2022-03-07T07:49:27Z",
  "signature": "algorithm=RSA256,keyVersion=1,signature=VelVji6jp8*****"
  }
}

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 that the notification has been received successfully, 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.

Result codes

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.
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
{
  "notifyType": "PAYMENT_RESULT",
  "payToAmount": {
    "currency": "USD",
    "value": "11000"
  },
  "payToId": "*****",
  "payToRequestId": "*****",
  "paymentAmount": {
    "currency": "USD",
    "value": "11000"
  },
  "paymentDetailSummaries": [{
    "customerId": "*****",
    "customerName": {
      "fullName": "******"
    },
    "extendInfo": "{\"chargeAmount\":\"{\\\"currency\\\":\\\"USD\\\",\\\"value\\\":\\\"33\\\"}\"}",
    "paymentAmount": {
      "currency": "USD",
      "value": "33"
    },
    "paymentMethodType": "WALLET_WF"
  }, {
    "customerId": "*****",
    "customerName": {
      "fullName": "******"
    },
    "extendInfo": "{}",
    "paymentAmount": {
      "currency": "USD",
      "value": "11000"
    },
    "paymentMethodType": "WALLET_WF"
  }],
  "paymentId": "*****",
  "paymentTime": "2022-07-18T17:38:04+08:00",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Response

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