refund

2022-11-09 08:58

POST: /amsin/api/v1/business/refund
Signature required

Use this interface to initiate a refund request.

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
refundRequestId	String	Yes	The unique ID that is assigned by the Partner to identify a refund request. Note: This field is an API idempotency field. For details about API idempotency, refer to the Idempotency chapter.More information: Maximum length: 64 characters
payToId	String	Yes	The unique ID that is assigned by WorldFirst for every payment order. More information: Maximum length: 64 characters
refundToDetails	Array<RefundToDetail object>	Yes	Details about the refund that the payer receives.
refundDetails	Array<RefundDetail object>	Yes	Details about the refund that the payee refunds. More information: In this scenario, `refundDetails` is the same as `refundToDetails`.
refundReason	String	Yes	The reason for the refund order. More information: Maximum length: 256 characters
refundRequestTime	DateTime object	Yes	Time that the Merchant(Customer) initiates a refund request. Note: The value of this field follows the ISO 8601 standard format and +08:00 timezone. For example, `2022-08-30T02:02:39-07:00`.
refundOrder	RefundOrder object	No	Transaction information of the refund order.

Response parameters

Field	Data type	Required	Description
result	Result object	Yes	Indicate the result of the refund request.
responseId	String	Yes	The unique ID that is assigned by WorldFirst to identify a response. More information: Maximum length: 32 characters
payToId	String	No	The unique ID that is assigned by WorldFirst for every payment order. More information: Maximum length: 64 characters
refundId	String	No	The unique ID that is assigned by WorldFirst to identify a specific refund request. More information: Maximum length: 64 characters
refundToDetails	Array<RefundToDetail object>	Yes	Details about the refund that the payer receives.
refundTime	DateTime object	No	Time that WorldFirst accepts the refund request. Note: The value of this field follows the ISO 8601 standard format and +08:00 timezone. For example, `2022-08-30T02:02:39-07:00`.

Result processing logic

After calling the API, a response is returned. The possible responses for result.resultStatus are:

Result status	Description
S	This indicates the API request succeeded.
F	This indicates the API request failed. For more information on why the request failed, see `result.resultCode`.
U	This indicates the result of the API request is unknown. For more details about the further action to be taken, refer to the specific `resultCode` in the Result codes section.

Result codes

`result.resultCode`

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 WorldFirst Technical Support 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 WorldFirst Technical Support.
UNKNOWN_CLIENT	F	Unknown client.	Check whether the Client ID is correct.
API_IS_INVALID	F	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_API	F	The called API is invalid or not active.	Check whether the correct API is being called.
CLIENT_FORBIDDEN_ACCESS_API	F	Client is not authorized to use this API.	Check whether the Client ID is correct.
ACCESS_DENIED	F	Access denied.	Contact WorldFirst support for help.
KEY_NOT_FOUND	F	Key is not found.	This indicates that the client ID in the request has no matching key on the server, or the client ID exists but the RSA key is not configured.
INVALID_CLIENT_STATUS	F	Invalid client status.	Check whether the Client ID is correct.
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`.
CURRENCY_NOT_SUPPORT	F	The currency is not supported.	Make sure the currency input is correct and try again.
CONTRACT_NOT_EXIST	F	contract does not exist	Ensure the Partner has already signed a contract with WorldFirst, and the input is correct.
REFUND_AMOUNT_EXCEED	F	REFUND_AMOUNT_EXCEED	Retry with another refund order.

Samples

Request

copy
{
  "payToId":"*****",  
  "refundRequestTime":"2019-11-27T18:14:41-08:00",
  "refundToDetails":[
    {
      "refundMethod":{
        "paymentMethodType":"WALLET_WF"
      },
      "refundToAmount":{
        "currency":"TWD",
        "value":100
      },
      "refundAmount":{
        "currency":"TWD",
        "value":100
      }
    }
  ],
  "refundRequestId":"*****"
}

Response

copy
{
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  },
  "payToId":"*****",
  "refundId":"*****",
  "refundRequestId":"*****",
  "refundTime":"2019-11-28T10:14:41+08:00",
  "refundToDetails":[
    {
      "refundAmount":{
        "currency":"TWD",
        "value":"100"
      },
      "refundMethod":{
        "paymentMethodType":"WALLET_WF"
      },
      "refundToAmount":{
        "currency":"TWD",
        "value":"100"
      }
    }
  ]
}