Translation disclaimer

Documentation is written in English and subsequently translated. This page, therefore, might not have the most up-to-date content. If any questions arise relating to the accuracy of the translated content, please refer to the English version of the page.

Menu

接受预存卡号授权

在您的客户使用已存的卡详情来发起支付时，可以使用我们的预存卡号授权资源。 请在此处阅读有关预存卡号规定的更多详情。

什么是预存卡号支付？

  • 客户在授权点使用您先前存储/打算存储的银行卡信息主动参与支付
  • 不按时间表支付
  • 需要客户的明确许可才能将卡存储在其账户上，以便在“一键式”模式下使用
  • 有时也称为客户启动的交易 (CIT)

在此页面上：

预存卡号授权且需要验证

验证您客户的账户，然后再提交您的第一次预存卡号支付以便进行授权。

预存卡号请求

POST 您发至在成功的cardOnFile 智能或dynamicCardOnFile验证中收到的payments:cardOnFileAuthorize操作链接中的预存卡号请求。

预存卡号请求示例

POST https://try.access.worldpay.com/payments/authorizations/cardonFile/{resource}

单击下表以查看全部支持的 paymentInstrument 参数的所有必需字段。

预存卡号请求正文：

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}",
            "cvc": "898"
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/checkout",
            "tokenHref": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ",
            "cvcHref": "https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoiNjQxbUswTlVFYW05NWY2R0IvUEtqWXY0QjVyY2V5VHBBU0Q1TDNuSFQrMGtEc3RIZm1NQnFtNDhKcVB1TkoySDkycWhpRHVwSHBZY3F6NEZiUGwxVHc9PSJ9"
        }
    }
}

必需参数描述

参数描述
transactionReference由您生成的独特参考号，用于在支付的整个生命周期中对其进行识别。请参见交易参考格式，了解更多详情和最佳实践。
merchant包含有关商户信息的对象。
merchant.entity确定您支付的方向，以协助开单、报告和对账。这对于身份验证和查询为必需。
请联系您的实施经理了解更多详情。
instruction包含与支付相关的所有信息的对象。
instruction.narrative出现在您的客户对账单上的文本。用于识别商户。
请参见商户落款格式，了解更多详情和最佳实践。
narrative.line1出现在您客户的对账单上的叙述文字的第一行（最多 24 个字符。如果不支持某个字符，则以空格代替）。
请参见商户落款line1格式，了解更多详情。
instruction.value包含有关支付值信息的对象。
value.currency3 位数货币代码。
请参见支持的货币列表。
value.amount支付金额。这是一个包含小数位的整数，e.g.，如果小数位是二，则 250 就表示 2.50.您可以在我们的货币表中查找相关小数位。
instruction.paymentInstrument包含支付类型和详情的对象。
可用的 paymentInstrument：
payoutInstrument.cardExpiryDate包含您的客户卡过期日期的对象。
对所有 "type": "card/plain" 请求为必需。
payoutInstrument.cardNumber包含您的客户卡号的对象。对 "type": "card/plain" 请求为必需。

3DS

3DS 授权请求参数描述

若要获得 customer 身份验证对象，您必须使用我们的3DS API填写身份验证请求。

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "z9UKb06xLziZMOXBEmWSVA1kwG0="
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}"
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "z9UKb06xLziZMOXBEmWSVA1kwG0="
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}"
        }
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
        }
    }
}

您的 3DS 授权请求中的参数描述

参数描述
customer包含您的客户验证结果的对象。有关更多详情，请参见3DS 验证。
authentication.type3DS
authentication.version用于处理交易的 3DS 版本。
对于 3DS1 - 1.0.2
对于 3DS2 - 2.1.0 或 2.2.0

注释：对于授权中的 Mastercard 身份校验交易是必需的。

authentication.eci电子商务指标 (ECI)。
表示3DS 验证的结果。
  • 02 或 05 - 完全身份验证的交易
  • 01 或 06 - 尝试身份验证交易
  • 00 或 07 - 非 3-D 安全交易
  • Mastercard - 02、01、00
  • Visa - 05、06、07
  • Amex - 05、06、07
  • JCB - 05、06、07
  • Diners - 05、06、07
authentication.authenticationValue是必需的 - 如果 authentication.eci 值为 01、02、05 或 06。
提供 3DS 验证结果证据的密码值。
  • Visa - 持卡人身份验证的验证值 (CAVV)
  • Mastercard - 通用持卡人身份验证字段 (UCAF)
authentication.authenticationValue 必须最大为 28 位，并且必须采用 base64 编码。
authentication.transactionId是必需的 - 如果 authentication.eci 值为 01、02、05 或 06。
由发行机构生成的独特身份验证交易识别码。

对于版本 3DS1： transactionId 为 base64 编码且长度为 28 位数。
对于版本 3DS2： transactionId 符合 RFC 4122 UUID 标准且长度为 36 个字符。

可选参数

预存卡号响应

最佳实践：Access Worldpay 在服务响应的头文件中返回WP-CorrelationId。我们强烈建议您将此记录下来。我们使用WP-CorrelationId检查单个服务请求。

成功支付

您会接收到：

  • HTTP 代码 201
  • "outcome": "authorized"
  • 风险因素（仅在发卡机构发现冲突时才返回）
  • 豁免结果和原因（仅在您提供了风险预测时）
  • 发卡机构授权代码
  • 方案参考号（由主要银行卡方案支持，但可能不会为所有的方案/地区返回）
  • 取消、结算、部分结算或跟踪支付事件的链接
  • 在您的重复支付协议中的下次支付时使用的授权链接

已拒绝的支付

您会接收到：

  • HTTP 代码 201
  • "outcome": "refused"
  • 拒绝代码
  • 为拒绝提供更多上下文的 description
  • 风险因素（仅在发卡机构发现冲突时才返回）
  • 豁免结果和原因（仅在您提供了风险预测时）

示例响应

Copied!
{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "issuer": {
        "authorizationCode": "0"
    },
    "scheme ": {
        "reference": "1260019172"
    },
    "exemption": {
        "result": "honored",
        "reason": "issuerHonored"
    },
    "_links": {
        "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:cardOnFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }]
    }
}
{
    "outcome": "refused",
    "description": "CARD EXPIRED",
    "code": "33",
    "refusalAdvice": {
        "code": "01"
    },
    "riskFactors": [{
            "risk": "not_supplied",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "verificationFailed",
            "type": "riskProfile"
        }
    ]
}

riskFactors

exemption

您必须始终存储并使用payments:cardOnFileAuthorize操作链接中返回的链接，以便授权您的下一次预存卡号支付。

注释：如果出现错误，您可以在我们的错误参考中获取更多信息。


后续步骤

支付退款

预存卡号授权且无需验证

在您的客户使用已存的卡详情来发起支付而无需先验证其账户时，可以使用我们的迁移预存卡号授权资源。 请在此处阅读有关预存卡号规定的更多详情。

无需验证授权请求的预存卡号

POST 您的预存卡号授权至我们在您的查询支付根资源请求中收到的payments:migrateCardOnFileAuthorize操作链接资源。

migrateCardOnFile 授权示例请求

POST https://try.access.worldpay.com/payments/authorizations/migrateCardOnFile

单击下表以查看全部支持的 paymentInstrument 参数的所有必需字段。

migrateCardOnFile 授权请求正文：

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}",
            "cvc": "898"
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/checkout",
            "tokenHref": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjd5bnJnSTR3a3FITW00SHNjaE90YnAwcVlvZ1pSZ3RFOXJjcklzVzY1ND0ifQ",
            "cvcHref": "https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoiNjQxbUswTlVFYW05NWY2R0IvUEtqWXY0QjVyY2V5VHBBU0Q1TDNuSFQrMGtEc3RIZm1NQnFtNDhKcVB1TkoySDkycWhpRHVwSHBZY3F6NEZiUGwxVHc9PSJ9"
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/networkToken+applepay",
            "dpan": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "customer": {
        "authentication": {
            "type": "card/networkToken",
            "authenticationValue": "abc123=="
        }
    }
}

参数描述

参数描述
customer.authentication.type将 card/networkToken 用于解码的钱包流。
instruction.paymentInstrument包含支付类型和详情的对象。
可用的 paymentInstrument：
  • card/plain
  • card/token- 首先创建 Token
  • card/checkout - 使用我们的Checkout SDK 来创建会话并使用此会话来首先创建 Token。您必须在 tokenHref 中使用 Token，而非在 Checkout 会话中使用。
  • card/networkToken+applepay- 用于解码的钱包流。此 paymentInstrument 包含取代原始卡号的 dpan。它由卡网络/钱包提供商生成。

您可以在此处了解完整的参数描述。

可选参数描述

无需验证响应的预存卡号

最佳实践：Access Worldpay 在服务响应的头文件中返回WP-CorrelationId。我们强烈建议您将此记录下来。我们使用WP-CorrelationId检查单个服务请求。

成功支付

您会接收到：

  • HTTP 代码 201
  • "outcome": "authorized"
  • 风险因素（仅在发卡机构发现冲突时才返回）
  • 豁免结果和原因（仅在您提供了风险预测时）
  • 发卡机构授权代码
  • 方案参考号（由主要银行卡方案支持，但可能不会为所有的方案/地区返回）
  • paymentInstrument（仅用于 Apple Pay 解码）
  • 取消、结算、部分结算或跟踪支付事件的链接
  • 在您的重复支付协议中的下次支付时使用的授权链接

已拒绝的支付

您会接收到：

示例响应

Copied!
{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "issuer": {
        "authorizationCode": "0"
    },
    "scheme ": {
        "reference": "1260019172"
    },
    "exemption": {
        "result": "honored",
        "reason": "issuerHonored"
    },
    "_links": {
        "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:cardOnFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }]
    }
}
{
    "outcome": "authorized",
    "riskFactors": [
        {
            "risk": "not_supplied",
            "type": "cvc"
        },
        {
            "risk": "not_supplied",
            "detail": "address",
            "type": "avs"
        },
        {
            "risk": "not_supplied",
            "detail": "postcode",
            "type": "avs"
        }
    ],
    "issuer": {
        "authorizationCode": "594554"
    },
    "scheme": {
        "reference": "000000000000020005060720116005061"
    },
    "paymentInstrument": {
        "type": "card/network",
        "card": {
            "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E"
        }
    },
    "_links": {
        "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiaz"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiIs"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzM"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJ"
        },
        "curies": [
            {
                "name": "payments",
                "href": "https://try.access.worldpay.com/rels/payments/{rel}",
                "templated": true
            }
        ],
        "payments:cardOnFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoiazNhYjYzMiIs"
        },
        "payments:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiIs"
        }
    }
}
{
    "outcome": "refused",
    "description": "CARD EXPIRED",
    "code": "33",
    "refusalAdvice": {
        "code": "01"
    },
    "riskFactors": [{
            "risk": "not_supplied",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "verificationFailed",
            "type": "riskProfile"
        }
    ]
}

您可以使用payments:settle操作链接来立即结算支付。您还可以将响应进行缓存，并在以后再使用该链接来结算支付。

您必须存储并使用payments:migrateCardOnFileAuthorize操作链接中返回的链接，以便授权您的下一次预存卡号支付。

注释：如果出现错误，您可以在我们的错误参考中获取更多信息。

riskFactors

exemption

软拒绝

如果支付中未应用豁免，则发卡机构会以软拒绝（拒绝代码 65）来回应。该操作的下一个符合逻辑的步骤是继续进行3DS 身份验证。


后续步骤

结算或取消支付