Payments
go to Evonet

Network Token

一、概述

本指南面向开发者，详细说明如何通过 Evonet API 获取 Network Token 并使用其发起支付交易。Network Token 由卡组织签发，可替代真实卡号（PAN）进行交易，提升支付成功率并增强卡信息安全性。

步骤接口操作说明
1paymentMethod传入持卡人真实卡号，获取 Network Token 及 tokenID
2cryptogram使用 tokenID 获取一次性密文（tokenCryptogram）和最新有效期
3payment使用 Network Token 信息 + Cryptogram 发起支付

二、获取 Network Token

通过 POST paymentMethod 接口，传入持卡人真实卡信息，生成 Network Token。

接口地址

POST {apiurl}/g2/v1/payment/mer/{sid}/evo.e-commerce.paymentMethod

请求示例

{
    "networkTokenOnly": true,
    "allowAuthentication": false,
    "paymentMethod": {
        "type": "card",
        "card": {
            "cardInfo": {
                "cardNumber": "4835830052621912",
                "expiryDate": "1231",
                "cvc": "390"
            }
        }
    },
    "merchantTransInfo": {
        "merchantTransID": "your_unique_trans_id",
        "merchantTransTime": "2026-08-18T11:26:47+08:00"
    },
    "transAmount": {
        "currency": "USD",
        "value": "1"
    },
    "userInfo": {
        "reference": "fill in buyer id in your system",
        "email": "[email protected]"
    },
    "returnURL": "https://YOUR_COMPANY.com/RETURNURL",
    "webhook": "https://webhook.merchant.com"
    ...
}

请求关键字段说明

字段说明注意事项
networkTokenOnly是否仅获取 Network Token设为 true，表示本次请求仅用于生成 Token，不发起实际交易
paymentMethod.recurringProcessingModel代扣模式可选值：Subscription（订阅）、Unscheduled（代扣）、COF（一键支付）
paymentMethod.card.cardInfo持卡人真实卡信息包含卡号、有效期、CVC
merchantTransInfo.merchantTransID商户交易 ID需唯一，用于标识本次请求
transAmount交易金额用于验证，实际不扣款
userInfo.reference用户唯一标识建议使用商户系统中的用户 ID，便于后续关联

响应示例

{
    ...
    "paymentMethod": {
        "networkToken": {
            "expiryDate": "1231",
            "paymentBrand": "Visa",
            "status": "enabled",
            "tokenID": "9fd96089049f2ed18b7a1331cc5f2c01",
            "tokenReferenceID": "DNITHE302619027557956444",
            "value": "4851681440000007"
        },
        ...
        "status": "Success"
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

响应关键字段

字段说明用途
networkToken.tokenIDNetwork Token 唯一标识需持久化保存，后续获取 Cryptogram 和发起支付均需使用
networkToken.valueNetwork Token 卡号（DPAN）卡组织签发的虚拟卡号
networkToken.expiryDateToken 有效期格式 MMYY
networkToken.statusToken 状态enabled 表示可正常使用
networkToken.paymentBrand卡组织品牌如 Visa、Mastercard
networkToken.tokenReferenceID卡组织侧的 Token 参考 ID供排查问题使用
networkToken.paymentAccountReference支付账户参考号用于识别同一持卡人的不同 Token
📘

Note

  • tokenID 是后续所有操作的核心标识，请妥善保存并与用户关联
  • networkToken.status 为 enabled 时才可用于交易；若状态异常，需重新申请 Token

二、获取 Token Cryptogram

每次使用 Network Token 发起交易前，需调用 cryptogram 接口获取一次性交易密文（tokenCryptogram）。Cryptogram 由卡组织动态生成，用于验证交易的合法性。

接口地址

POST {apiurl}/g2/v1/payment/mer/{sid}/cryptogram

相关参数请参考：API Explorer

请求示例

{
    "merchantTransInfo": {
        "merchantTransID": "your_unique_trans_id",
        "merchantTransTime": "2026-08-18T11:26:47+08:00"
    },
    "paymentMethod": {
        "type": "networkToken",
        "networkToken": {
            "tokenID": "9fd96089049f2ed18b7a1331cc5f2c01"
        }
    },
    "webhook": "https://webhook.merchant.com"
}

请求关键字段说明

字段说明注意事项
paymentMethod.type支付方式类型固定为 networkToken
paymentMethod.networkToken.tokenIDToken 唯一标识使用步骤一获取的 tokenID
merchantTransInfo.merchantTransID商户交易 ID需唯一，可使用任意唯一值

响应示例

{
    "cryptogram": {
        "status": "Success"
    },
    ...
    "paymentMethod": {
        "networkToken": {
            "eci": "07",
            "expiryDate": "1231",
            "first6No": "485168",
            "last4No": "0007",
            "paymentAccountReference": "V0010013025018333000890649902",
            "paymentBrand": "Visa",
            "status": "enabled",
            "tokenCryptogram": "CQAAAAABfjauDGAAmfSdguYAAAg=",
            "tokenID": "9fd96089049f2ed18b7a1331cc5f2c01",
            "tokenReferenceID": "DNITHE302619027557956444",
            "value": "4851681440000007"
        }
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

响应关键字段

字段说明用途
networkToken.tokenCryptogram一次性交易密文每笔交易必须重新获取，用于步骤三发起支付
networkToken.eci电子商务指示符标识交易认证级别（如 Visa: 05/06/07）
networkToken.expiryDateToken 最新有效期使用此值发起支付，确保有效期为最新
networkToken.statusToken 当前状态确认为 enabled 后再发起支付
cryptogram.statusCryptogram 获取状态Success 表示获取成功
📘

Note

  • tokenCryptogram 具有时效性且仅能使用一次，获取后应尽快发起支付
  • 若 networkToken.status 不为 enabled，表示 Token 已失效（如卡片挂失、销户等），不应继续发起交易

三、发起支付

使用 Network Token 及 Cryptogram 信息，调用 payment 接口完成支付。

接口地址

POST {apiurl}/g2/v1/payment/mer/{sid}/payment

请求示例

{
    "merchantTransInfo": {
        "merchantTransID": "your_unique_payment_trans_id",
        "merchantTransTime": "2026-08-18T11:26:47+08:00"
    },
    "transAmount": {
        "currency": "USD",
        "value": "22"
    },
    "paymentMethod": {
        "type": "token",
        "token": {
            "value": "9fd96089049f2ed18b7a1331cc5f2c01",
            "type": "networkToken",
            "paymentBrand": "Visa",
            "walletIdentifiers": "MDESForMerchants",
            "expiryDate": "1231",
            "tokenCryptogram": "CgAAAAABdLdhIjMAmfSdguIAAAg="
        }
    },
    "captureAfterHours": "0",
    "allowAuthentication": false,
    "userInfo": {
        "reference": "fill in buyer id in your system",
        "email": "[email protected]"
    },
    "returnURL": "https://YOUR_COMPANY.com/RETURNURL",
    "webhook": "https://webhook.merchant.com"
    ...
}

请求关键字段说明

字段说明注意事项
paymentMethod.type支付方式类型固定为 token
paymentMethod.token.valueToken 标识使用步骤一获取的 tokenID
paymentMethod.token.typeToken 类型固定为 networkToken
paymentMethod.token.paymentBrand卡组织品牌如 Visa、Mastercard，需与 Token 对应的品牌一致
paymentMethod.token.walletIdentifiers钱包标识如 MDESForMerchants或其他标识
paymentMethod.token.expiryDateToken 有效期使用步骤二 cryptogram 响应中的 expiryDate
paymentMethod.token.tokenCryptogram交易密文使用步骤二获取的 tokenCryptogram
allowAuthentication是否启用 3DSNetwork Token 交易通常设为 false（Cryptogram 已提供交易验证）

响应示例

{
    "payment": {
        "evoTransInfo": {
            "evoTransID": "pay-2608181612130001000083543383",
            "evoTransTime": "2026-08-18T08:12:12Z"
        },
        "merchantTransInfo": {
            "merchantTransID": "tte123113333",
            "merchantTransTime": "2026-05-20T06:41:15Z"
        },
        "status": "Captured",
        "transAmount": {
            "currency": "USD",
            "value": "22.00"
        },
        ...
    },
    "paymentMethod": {
        "isNetworkToken": true,
        ...
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

响应关键字段

字段说明
result.codeS0000 表示交易成功
payment.statusCaptured 表示资金已捕获
paymentMethod.isNetworkTokentrue 确认本次交易使用了 Network Token
payment.merchantTransInfo.merchantTransID商户交易 ID


Updated 1 day ago

Did this page help you?