Payments
go to Evonet
Start typing to search…

Direct API Integration Step - 中文

本指南面向开发者，详细说明如何通过 Direct API 集成线上支付功能，支持Payment、Retrieve、Capture、Refund、Cancel 及 Recurring 场景。

以下步骤和字段说明旨在帮助您清晰理解整个支付流程，确保顺利集成。


一、展示支付方式

在收银台页面展示可用的支付方式。用户选择支付方式后，输入支付信息（如卡号、有效期等），提交至后端。


二、发起支付请求

后端通过 POST /payment 接口提交支付请求，需包含 KeyID、密钥 Key 和幂等性密钥。

请求示例：

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

关键字段：

字段名类型描述注意事项
merchantTransInfo.merchantTransIDstring商户交易 ID，需唯一用于查询、退款等操作
paymentMethod.typestring支付方式（如 card）需匹配对应结构体，可参考下方举例
captureAfterHoursstring自动捕获延迟小时数“0” 表示立即捕获
allowAuthenticationboolean是否启用 3DS 认证建议 true
returnURLstring支付完成后页面重定向地址若上送了 "allowAuthentication": true，则必需
webhookstring异步通知地址接收支付结果

paymentMethod.type 举例：(此为 e-wallet)，不同的 type 下结构体不同，具体参数请参考 paymentMethod.type Values。

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

Note

请求超时处理建议：接口支持幂等性，超时后使用相同的报文和 Idempotency-Key 重试，确保响应一致，避免重复发起交易。


三、处理支付相应

根据响应中的 action 对象做后续处理，根据 result.code 和 payment.status 判断交易结果：

  • result.code 以 S 开头（如 S0000）：检查 payment.status

    • 成功状态：authorized、captured、verified、identified
    • 处理中：verify_pending、auth_pending、identify_pending
      • 需根据 action.type 处理，例如跳转至 threeDSData.url

  • 非 S 开头：交易失败，检查 result.message

响应示例：

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

关键字段：

字段名类型描述注意事项
action.typestring操作类型（如 threeDSRedirect）决定后续处理流程，可参考下方举例
payment.statusstring支付状态如 captured 表示成功，verify_pending 表示需认证
result.codestring状态码S 开头表示成功，非 S 开头表示失败
refund.messagestring状态描述如 “Success” 或错误信息

action.type 举例：(此为 redirectUser)，不同的 type 需按指定流程处理，相关数据（如 action.url）在 action 对象中提供，具体请参考 paymentMethod & action Flow。

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

Note

  • 若 “payment.status = authorized” 且未上送 “captureAfterHours” 字段，需调用 Cpature 接口手动捕获。
  • 兜底机制：通过 GET/payment 接口轮询最终状态。

更多参数详见：API Explorer Payment API 接口。


四、处理异步通知

Evonet 通过 POST 请求向 webhook 地址发送支付结果通知，仅包含已完成的状态，不包含处理中的状态。

通知示例：

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

响应：

SUCCESS

关键字段：

字段名类型描述注意事项
eventCodestring通知类型（如 Payment）
payment.statusstring支付状态如 captured 表示成功，declined 表示失败，详见 payment.status 处理逻辑
capture.statusstring捕获状态capture_successed 表示成功，capture_declined 表示失败
refund.statusstring退款状态refund_successed 表示成功，refund_declined 表示失败
cancel.statusstring取消状态cancel_successed 表示成功，cancel_declined 表示失败

处理逻辑

首先检查 eventCode 确定通知类型，然后再检查不同通知类型的 status。

  • Payment - payment.status：

    1. 卡支付（paymentMethod.type = card）：

      • captured：交易成功
      • verified：3DS 认证完成，等待 captured 通知，出现后表示交易成功
      • authorized：授权完成，等待 captured 通知，出现后表示交易成功
        • 若请求中没有上送 captureAfterHours = 0，需调用 Capture 接口进行捕获
      • identified：身份验证完成，可根据业务需求继续支付流程
      • declined：交易失败，检查 failureCode 和 failureReason，并向用户展示以便排查
      • verify_declined：3DS 认证失败
        • 若 POST/payment 请求参数中 allowAuthentication = true 且 authentication.preference = "preferred"，可能会收到 payment.status 为 authorized（需等待 captured）或 declined 的通知
        • 若请求参数非上述情况，收到 verify_declined 时即将交易置为失败处理
      • identifiy_declined：身份验证失败

    2. 非卡支付：

      • captured：交易成功
      • declined：交易失败，检查 failureCode 和 failureReason，并向用户展示以便排查

  • Capture - capture.status：

    • capture_successed：捕获成功
    • capture_declined：捕获失败

  • Refund - refund.status：

    • refund_successed：退款成功
    • refund_declined：退款失败

  • Cancel - cancel.status：

    • cancel_successed：取消成功
    • cancel_declined：取消失败
📘

Note

收到通知后，需返回纯文本 SUCCESS 表示接收成功。若未收到响应信息，系统会按照规定的频率（15/15/30/180/1800/1800/1800/1800/3600. 单位：秒）定期重新发送异步通知，直到成功收到 SUCCESS 或通知次数达到上限。

更多参数详见：API Explorer Payment Notification 。


五、展示支付结果

根据响应或异步通知，向用户展示支付结果。失败时建议显示 result.message 或 failureReason，便于用户采取后续操作。


六、代扣、一键支付与订阅

支持代扣、一键支付和订阅，通过 token 实现无需重复输入卡信息。首次需完成绑卡并扣款，后续使用 token 发起扣款。

首次支付

通过 POST /payment 发起支付，需设置以下字段生成 token：

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

请求示例（以订阅为例）：

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

响应示例：

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

关键字段：

字段名类型描述注意事项
paymentMethod.card.tokenizeboolean是否生成 token首次订阅设为 true
paymentMethod.card.userReferencestring用户唯一标识关联 token 和系统用户
paymentMethod.recurringProcessingModelstring交易类型Subscription（订阅）、Unscheduled（代扣）、COF（一键支付）
paymentMethod.recurringReferencestring定期扣款协议 ID用于后续扣款
paymentMethod.token.valuestringToken 值用于后续扣款

后续（MIT 交易）

使用保存的 token.value 发起后续扣款，设置 paymentMethod.type 为 token。

请求示例：

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

响应示例：

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

九、可选接口

查询支付状态 (GET)

通过 GET /payment/{merchantTransID} 接口查询支付状态。merchantTransID 需从支付响应或异步通知中的 payment.merchantTransInfo.merchantTransID 中获取。

捕获 (Capture)

对于 authorized 状态的交易，可通过 POST /payment/{merchantTransID}/capture 完成最终扣款。

退款 (Refund)

通过 POST /payment/{merchantTransID}/refund 接口对已经完成支付的订单发起全额或者部分退款。

取消 (Cancel)

通过 POST /payment/{merchantTransID}/cancel 接口取消未捕获的 authorized 或 pending 交易。

Updated 2 months ago