inquirePayment

2022-11-09 08:58

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

After the Partner makes a payment, the Partner can inquire about the result of the payment order with this API.

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

payToRequestIds

List<String>

Yes(Conditional)

A list of the requests that the Partner inquires about. Each request is identified by a unique payToRequestId, which is assigned by the Partner to identify each payment.

Note:

PayToRequestIds and payToIds cannot both be empty.

More information:

Maximum length: 64 characters

payToIds

List<String>

Yes(Conditional)

A list of the requests that the Partner inquires about. Each request is identified by a unique payToId, which is assigned by WorldFirst to identify each payment.

Note:

PayToRequestIds and payToIds cannot both be empty.

More information:

Maximum length: 64 characters

Response parameters

Field	Data type	Required	Description
result	Result object	Yes	Indicates the result of the payment order.
payToSummaries	Array<PayToSummary object>	Yes	Details about the payment that the Beneficiary receives.
paymentDetailSummaries	Array<PaymentDetailSummary object>	Yes	Details about the payment, such as the payment amount, payment method, etc. Note: If the payment failed, the parameter remains empty.
feeDetailSummaries	Array<FeeDetailSummary object>	Yes	Details about fees.

Result processing logic

To get the result of the payment order, you can call the inquirePayment API or wait for the asynchronous notification to obtain the payment result:

If the payment is successful, proceed with other tasks.
If the payment is being processed, call the inquirePayment API again or wait for the result notification from the notifyPayment API.
If the payment is not successful, call the createCashierPayment API again with a different payToRequestId.

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

Result status	Description
S	This indicates the API call succeeded.
F	This indicates the API call failed. For more information on why the call failed, see `result.resultCode`.
U	This indicates the API call result is unknown. Partner can make a query when the returned status is `UNKNOWN`. Use the following query strategy: A Partner can make 7 queries at maximum. Intervals between queries: 5m, 10m, 20m, 40m, 80m, 160m, and 320m. If none of the queries is successful, contact WorldFirst Technical Support.

Note: result.resultStatus only indicates the result of the API request. For the payment result, refer to the payToSummaries.orderResult.status.

Possible values for payToSummaries.orderResult.status are:

payToSummaries.orderResult.status	Description
WAIT_PAY	WorldFirst is processing the payment.
PAY_SUCCESS	Payment is successful.
PAY_FAILED	Payment failed.
PAY_CANCELLED	Payment is canceled.

Result codes

resultCode	resultStatus	resultMessage	Further action
SUCCESS	S	Success
PROCESSING	S	The payment order is being processed.	Call the inquirePayment API again for the payment order result or wait for notifications.
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
{
    "payToRequestIds":["requestId_*****"]
}

Response

copy
{
    "feeDetailSummaries": [
        {
            "feeAmount": {
                "currency": "USD",
                "value": "3"
            },
            "paymentMethodType": "WALLET_WF"
        }
    ],
    "payToSummaries": [
        {
            "orderResult": {
                "status": "PAY_SUCCESS"
            },
            "payToAmount": {
                "currency": "USD",
                "value": "1000"
            },
            "payToCreateTime": "2022-06-17T01:43:58-07:00",
            "payToId": "*****",
            "payToRequestId": "requestId_*****"
        }
    ],
    "paymentDetailSummaries": [
        {
            "paymentAmount": {
                "currency": "USD",
                "value": "1000"
            },
            "paymentMethodMetaData": "{}",
            "paymentMethodType": "WALLET_WF"
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}