Payments
go to Evonet
Start typing to search…

Direct API Integration Step

This guide is intended for developers, detailing how to integrate online payment functionality via the Direct API. It supports Payment, Retrieve, Capture, Refund, Cancel, and Recurring scenarios.

The following steps and field descriptions are designed to help you clearly understand the entire payment process and ensure a smooth integration.


1. Display Payment Methods

On the checkout page, display the available payment methods. After the user selects a payment method and enters the required information (e.g., card number, expiry date), submit the data to your backend.


2. Initiate a Payment Request

Your backend should submit a payment request via the POST /payment interface. The request must include the KeyID, secret Key, and an idempotency Key.

Request Example:

curl --location --request POST 'https://sandbox.evonetonline.com/payment' \
--header 'Authorization: sk_sandbox_3bf8181129cb4c9aa3d62cd113b6518a' \
--header 'DateTime: 2025-07-09T11:18:00+08:00' \
--header 'KeyID: kid_55209b3968f748609dbe3a9dde87fdd3' \
--header 'SignType: Key-based' \
--header 'Content-type: application/json' \
--header 'Idempotency-Key: order_202507091032_001' \
--data '{
    "merchantTransInfo": {
        "merchantTransID": "pay_250709135509000153215434"
        "merchantTransTime": "2025-07-09T11:18:00+08:00"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100"
    },
    "paymentMethod": {
        "type": "card",
        "card": {
            "cardInfo": {
                "cardNumber": "4761360072118507",
                "expiryDate": "0529",
                "holderName": "Paulette Homenick"
            }
        }
    },
    "captureAfterHours": "0",
    "allowAuthentication": true,
    "returnURL":"https://www.cardinfolink.com",
    "webhook": "https://webhook.merchant.com"
}

Key Fields：

Field NameTypeDescriptionNotes
merchantTransInfo.merchantTransIDstringUnique merchant transaction IDUsed for query, refund, and other operations
paymentMethod.typestringPayment method type (e.g., card, e-wallet)Must math the corresponding structure. See example below
captureAfterHoursstringHours to delay automatic capture"0" means capture immediately
allowAuthenticationbooleanWhether to enable 3DS authenticationRecommended: true
returnURLstringURL to redirect to after payment completionRequired if "allowAuthentication": true is sent
webhookstringAsynchronous notification URLFor receiving payment results

paymentMethod.type Example (e-wallet): Different type values have different structures. Please refer to the paymentMethod.type Values for specific parameters.

    "paymentMethod": {
        "type": "e-wallet",
        "e-wallet": {
            "paymentBrand": "Merpay"
        }
    }
📘

Note: Handling Timeouts

The API supports idempotency. If a request times out, retry with the same payload and Idempotency-Key to ensure a consistent response and avoid creating duplicate transactions.


3. Handle the Payment Response

Handle subsequent steps based on the action object in the response. Determine the transaction result using result.code and payment.status:

  • result.code start with 'S' (e.g., S0000): Check payment.status.

    • Success statues: authorized、captured、verified、identified
    • Processing states: verify_pending、auth_pending、identify_pending
      • Handle according to action.type (e.g., redirect user to threeDSData.url).

  • result.code does not start with 'S': Transaction failed. Check result.message.

Response Example：

{
    "action": {
        "threeDSData": {
            "method": "GET",
            "url": "https://counter-uat.everonet.com/3ds?dGhyZWVEU1BzcD1ISVRSVVNUJmluc0NvZGU9OTA0NTE5MDAmb3JkZXJOdW09cGF5XzI1MDcxMDE2MDczMDAwMDEwMDAwMDQzODg1NDEmc3RvcmVOdW09UzAwNTIyOCZ0aHJlZWRzSW50ZWdyYXRvck9pZD0xMzY4MjE5MCZ0aHJlZURTQXV0aFVSTD1hSFIwY0hNNkx5OXphWFF0TTJSemN5MWpjSGg1TG1ocGRISjFjM1J3WVhrdVkyOXRMblIzTDNSb2NtVmxaSE10YVc1MFpXZHlZWFJ2Y2k5aGRYUm9Mekl1TVM0d0wyOTJWRlJaWTJ0V1NGbGtjbVp1ZFRKUFVVNWthamxKU1V4S1VXVnNXbVJqYUU1dlowODRPRlZxUTBrPSZyZXR1cm5Vcmw9YUhSMGNITTZMeTkzZDNjdVkyRnlaR2x1Wm05c2FXNXJMbU52YlE9PQ=="
        },
        "type": "threeDSRedirect"
    },
    "authentication": {
        "liabilityShift": false,
        "type": "threeDSPage"
    },
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_250709135509000153215434",
            "evoTransTime": "2025-07-10T08:07:30Z",
            "retrievalReferenceNum": "519116015325",
            "traceNum": "015325"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "mc-250528",
            "merchantTransID": "pay_250709135509000153215434",
            "merchantTransTime": "2025-07-09T11:18:00+08:00"
        },
        "pspTransInfo": {
            "retrievalReferenceNum": "519116015325"
        },
        "status": "verify_pending",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "476136",
            "fundingType": "credit",
            "holderName": "Paulette Homenick",
            "issuingCountry": "IND",
            "last4No": "8507",
            "paymentBrand": "Visa"
        },
        "isNetworkToken": false
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

Key Fields：

Field NameTypeDescriptionNotes
action.typestringType of action required (e.g., threeDSRedirect)Determines the next steps. See example below
payment.statusstringPayment statuse.g., captured means success, verify_pending requires authentication
result.codestringResult code'S' prefix indicates success, otherwise failure
refund.messagestringResult descriptione.g., "Success" or error message

action.type Example (redirectUser): Different type values require specific handling flows. Relevant data (e.g., action.url) is provided in the action object. Please refer to paymentMethod & action Flow

    "action": {
        "redirectData": {
            "method": "GET",
            "url": "https://stg.openapi.mul-pay.jp/wallet/startSession?p=eyJhY2Nlc3NJZCI6IjBjYWE4M2ZmMzA0NjVhODhhOWE1NjEzZDc3NzMyMzdiIn0"
        },
        "type": "redirectUser"
    }
📘

Note

  • If "payment.status": "authorized" and the captureAfterHours field was not sent, you must manually capture the amount by calling the Capture interface.
  • Implement a fallback mechanism: poll for the final status using the GET /payment interface.

For more parameters, see: API Explorer Payment API.


4. Handle Asynchronous Notificaations (Webhook)

Evonet will send payment result notifications via a POST request to your webhook URL. These notifications only contain finalized states, not intermediate processing states.

Notification Example：

{
    "eventCode": "Payment",
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_2507091522550001000000860156",
            "evoTransTime": "2025-07-09T15:22:55+08:00"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "mc-250709",
            "merchantTransID": "pay_2507091522550001000000860156",
            "merchantTransTime": "2025-07-09T11:18:00+08:00"
        },
        "status": "captured",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "476136",
            "last4No": "8507",
            "paymentBrand": "Visa"
        }
    }
}

Required Response：

SUCCESS

Key Field：

Field NameTypeDescriptionNotes
eventCodestringType of notification (e.g., Payment)Check this first to determine the notification type
payment.statusstringPayment statussee logic below
capture.statusstringCapture statuscapture_successed (success), capture_declined (failure)
refund.statusstringRefund statusrefund_successed (success), refund_declined (failure)
cancel.statusstringCancel statuscancel_successed (success), cancel_declined (failure)

Processing Logic:

First, check the eventCode to determine the notification type, then check the relevant status field.

  • Payment - payment.status:

    1. Card Payments (paymentMethod.type = card):

      • captured: Transaction successful.
      • verified: 3DS authentication completed. Wait for a captured notification to confirm success.
      • authorized: Authorization completed. Wait for a captured notification to confirm success. If captureAfterHours = 0 was not sent in the request, you must call the Capture interface.
      • identified: Identity verification completed. Proceed with the payment flow based on business needs.
      • declined: Transaction failed. Check failureCode and failureReason to display to the user for troubleshooting.
      • verify_declined: 3DS authentication failed.
        • If the original POST /payment request had allowAuthentication = true AND authentication.preference = "preferred", you might receive a final status of authorized (wait for captured) or declined instead.
        • If the request parameters were different from the above, treat verify_declined as a final failure.
      • identifiy_declined: Identity verification failed. Treat this as a final failure.

    2. Non-card Payments：

      • captured: Transaction successful.
      • declined: Transaction failed. Check failureCode and failureReason to display to the user for troubleshooting.

  • Capture - capture.status:

    • capture_successed: Capture successful.
    • capture_declined: Capture failed.

  • Refund - refund.status:

    • refund_successed: Refund successful.
    • refund_declined: Refund failed.

  • Cancel - cancel.status:

    • cancel_successed: Cancel successful.
    • cancel_declined: Cancel failed.
📘

Note

Upon receiving a notification, you must return the plain text SUCCESS to acknowledge receipt. If Evonet does not receive this response, the system will retry sending the notification according to a fixed schedule (intervals: 15/15/30/180/1800/1800/1800/1800/3600 seconds) until it receives SUCCESS or the maximum number of attempts is reached.

For more parameters: see API Explorer Payment Notification .


5. Display Payment Result

Display the payment result to the user based on the response or asynchronous notification. In case of failure, it is recommended to display the result.message or failureReason to help the user take subsequent actions.


6. Recurring

Recurring payments consist of two types of transactions: the initial (or first) recurring transaction and subsequent transactions. The first transaction must complete card binding and payment, subsequent payments use the generated token.

Initial Payment (Save Credentials)

Initiate a payment via POST /payment and set the following fields to generate a token:

{
  "paymentMethod": {
    "card": {
      "tokenize": true,
      "userReference": "your-user-reference"
    }
  }
}

Request Example (Subscription):

{
    "merchantTransInfo": {
        "merchantTransTime": "2025-05-28T09:55:57Z"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100"
    },
    "paymentMethod": {
        "type": "card",
        "card": {
            "cardInfo": {
                "cardNumber": "4895330111111119",
                "expiryDate": "1231"
            },
            "tokenize": true,
            "userReference": "fill in buyer id in your system"
        },
        "recurringProcessingModel": "Subscription"
    },
    "captureAfterHours": "0",
    "allowAuthentication": true,
    "returnURL":"https://www.cardinfolink.com",
    "webhook": "https://webhook.merchant.com"
}

Response Example:

{
    "action": {
        "threeDSData": {
            "method": "GET",
            "url": "https://counter-uat.everonet.com/3ds?dGhyZWVEU1BzcD1ISVRSVVNUJmluc0NvZGU9OTA0NTE5MDAmb3JkZXJOdW09cGF5XzI1MDcxNDA5NDczNTAwMDEwMDAwOTU2MjkwNjQmc3RvcmVOdW09UzAwNTIyOCZ0aHJlZWRzSW50ZWdyYXRvck9pZD0xMzY5MDYxNSZ0aHJlZURTQXV0aFVSTD1hSFIwY0hNNkx5OXphWFF0TTJSemN5MWpjSGg1TG1ocGRISjFjM1J3WVhrdVkyOXRMblIzTDNSb2NtVmxaSE10YVc1MFpXZHlZWFJ2Y2k5aGRYUm9Mekl1TVM0d0wwWjJhMUpPTVRsRmRXTm9TekJxVDBwWWJWaGZRamMxUWpad1pEa3RSbWxQWWpFMlNrazRhekJSUVRBPSZyZXR1cm5Vcmw9YUhSMGNITTZMeTkzZDNjdVkyRnlaR2x1Wm05c2FXNXJMbU52YlE9PQ=="
        },
        "type": "threeDSRedirect"
    },
    "authentication": {
        "liabilityShift": false,
        "type": "threeDSPage"
    },
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_2507140947350001000095629064",
            "evoTransTime": "2025-07-14T01:47:35Z",
            "retrievalReferenceNum": "519509794653",
            "traceNum": "794653"
        },
        "merchantTransInfo": {
            "merchantTransID": "pay_2507140947350001000095629064",
            "merchantTransTime": "2025-05-28T09:55:57Z"
        },
        "pspTransInfo": {
            "retrievalReferenceNum": "519509794653"
        },
        "status": "verify_pending",
        "transAmount": {
            "currency": "USD",
            "value": "39.51"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "222242",
            "fundingType": "debit",
            "issuingBank": "JACK HENRY & ASSOCIATES",
            "issuingCountry": "BEL",
            "last4No": "0000",
            "paymentBrand": "Mastercard"
        },
        "isNetworkToken": false,
        "paymentMethodVariant": "Recurring",
        "recurringReference": "recurring_064f9279eb3547ac840484f19c286773"
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

Key Fields：

Field NameTypeDescriotionNotes
paymentMethod.card.tokenizebooleanWhether to generate a tokenSet to true for the initial subscription/tokenization
paymentMethod.card.userReferencestringUnique user identifier in your systemAssociates the token with your user
paymentMethod.recurringProcessingModelstringType of MIT transactionSubscription, Unscheduled(Auto-debit), COF (One-click Payment)
paymentMethod.recurringReferencestringRecurring agreement IDUsed for subsequent payments
paymentMethod.token.valuestringToken valueUsed for subsequent payments

Subsequent (MIT) Transaction

Use the saved token.value to initiate subsequent payments. Set paymentMethod.type to token.

Request Example:

{ 
    "merchantTransInfo": {
        "merchantTransTime": "{{merchantTransTime}}"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "100"
    },
    "paymentMethod": {
        "type": "token",
        "token":{
            "value":"pmt_938ed7ae0fc5415d937e400040ddbce0"
        },
        "recurringProcessingModel": "Subscription"
    },
    "captureAfterHours": "0",
    "allowAuthentication": true,
    "returnURL": "https://www.cardinfolink.com",
    "webhook": "https://webhook.merchant.com"
}

Response Example:

{
    "action": {
        "threeDSData": {
            "method": "GET",
            "url": "https://counter-uat.everonet.com/3ds?dGhyZWVEU1BzcD1ISVRSVVNUJmluc0NvZGU9OTA0NTE5MDAmb3JkZXJOdW09cGF5XzI1MDcxNDA5NTYwNjAwMDEwMDAwMTY5MTI1MzUmc3RvcmVOdW09UzAwNTIyOCZ0aHJlZWRzSW50ZWdyYXRvck9pZD0xMzY5MDYzOSZ0aHJlZURTQXV0aFVSTD1hSFIwY0hNNkx5OXphWFF0TTJSemN5MWpjSGg1TG1ocGRISjFjM1J3WVhrdVkyOXRMblIzTDNSb2NtVmxaSE10YVc1MFpXZHlZWFJ2Y2k5aGRYUm9Mekl1TVM0d0wyRjJUMUpRWTFsV2VGcE1kek5vUm01S2FGcHlPVlZJWmpWaFFsVTFjVVpmWlZreFUxVkhWV1ZUY0dzPSZyZXR1cm5Vcmw9YUhSMGNITTZMeTkzZDNjdVkyRnlaR2x1Wm05c2FXNXJMbU52YlE9PQ=="
        },
        "type": "threeDSRedirect"
    },
    "authentication": {
        "liabilityShift": false,
        "type": "threeDSPage"
    },
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay_2507140956060001000016912535",
            "evoTransTime": "2025-07-14T01:56:06Z",
            "retrievalReferenceNum": "519509795840",
            "traceNum": "795840"
        },
        "merchantTransInfo": {
            "merchantTransID": "pay_2507140956060001000016912535",
            "merchantTransTime": "2025-07-14T09:56:05+08:00"
        },
        "pspTransInfo": {
            "retrievalReferenceNum": "519509795840"
        },
        "status": "verify_pending",
        "transAmount": {
            "currency": "HKD",
            "value": "100.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "489533",
            "fundingType": "credit",
            "issuingCountry": "USA",
            "last4No": "1119",
            "paymentBrand": "Visa"
        },
        "isNetworkToken": false,
        "paymentMethodVariant": "Recurring",
        "recurringReference": "recurring_83e9b74c15024820a0445378772c68d2",
        "token": {
            "createTime": "2025-07-11T16:32:17+08:00",
            "fingerprint": "6fae07340096b1dc087f52ddbf69e577",
            "status": "enabled",
            "updateTime": "2025-07-11T16:32:33+08:00",
            "userReference": "fill in buyer id in your system",
            "value": "pmt_938ed7ae0fc5415d937e400040ddbce0"
        }
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

7. Other Optional APIs:

Get Payment Details

Using GET /payment/{merchantTransID} to enquiry a payment status, merchantTransID is obtained from payment.merchantTransInfo.merchantTransID

Capture Payment

For authorized transactions, it could be using this API to carry out capture POST /payment/{merchantTransID}/capture

Refund Payment

For transaction that is captured, use POST /payment/{merchantTransID}/refund to carry out partial or full refund of the transaction.

Cancel Payment

Cancel an uncaptued authorized or pending transaction using POST /payment/{merchantTransID}/cancel.

Updated 20 days ago