diff --git a/website/assets/css/docs.css b/website/assets/css/docs.css index 9b66d64..293eb6a 100644 --- a/website/assets/css/docs.css +++ b/website/assets/css/docs.css @@ -940,6 +940,19 @@ div.docs.scrollpage section.content .wrapper { padding: 0 30px; } +div.docs .deprecated-badge { + align-self: flex-start; + margin-left: 10px; + padding: 2px 6px; + border-radius: 4px; + color: var(--color-brand-orange-60); + background-color: var(--color-brand-orange-10); + font-size: 13px; + font-weight: 600; + text-transform: uppercase; + transform: translateY(4px); +} + .mobile-navigation-content { display: none; } diff --git a/website/content/gateway/api_reference/changes/changes.md b/website/content/gateway/api_reference/changes/changes.md index 92659fd..fc132d0 100644 --- a/website/content/gateway/api_reference/changes/changes.md +++ b/website/content/gateway/api_reference/changes/changes.md @@ -10,6 +10,16 @@ Follow coming changes on the [source code repository](https://github.com/clearha Sorted by descending timestamp. +#### Updates to Click to Pay +Starting 2026-xx-xx, we will expand the Click to Pay payment method: + +- The payment method allows for both cards and tokens. +- Transactions can be created using a payload interface in addition to the raw interface. +- The raw interface supports `[onbehalf][...]` fields to be used when 3-D Secure authentication was performed `ONBEHALF`. +- The raw interface accepts `clicktopay[can]` for the card or token number. `clicktopay[tan]` is deprecated but can still be provided. Exactly one of `clicktopay[can]` and `clicktopay[tan]` must be present. + +Please see [Method: clicktopay](#method-clicktopay) for details. + #### Additional SCA exemtions added Starting 2025-12-12, we will start accepting new parameters for `sca_exemption`. The two new parameters are `low_value_payment` and `secure_corporate_payment` @@ -29,7 +39,7 @@ As Bulgaria is moving from BGN to EUR we will be deprecating the BGN currency as #### Add support for Click to Pay Starting 2025-10-01, we support Click to Pay as a token framework. Please see -[Method: token](#method-token) for details. +[Method: clicktopay](#method-clicktopay) for details. #### Add minimum amount for Visa captures and refunds Starting 2025-05-19, we will enforce a minimum amount of USD 0.005 for captures diff --git a/website/content/gateway/api_resources/authorizations/authorizations.md b/website/content/gateway/api_resources/authorizations/authorizations.md index 4801daa..f7d7732 100644 --- a/website/content/gateway/api_resources/authorizations/authorizations.md +++ b/website/content/gateway/api_resources/authorizations/authorizations.md @@ -9,7 +9,7 @@ To reserve money on a cardholder’s bank account you make a new authorization r ```shell POST https://gateway.clearhaus.com/authorizations ``` -Authorizations can be created using different payment methods: [`card`](#method-card), [`applepay`](#method-applepay), [`googlepay`](#method-googlepay), [`mobilepayonline`](#method-mobilepayonline), [`moto`](#method-moto), [`token`](#method-token) and [`vipps`](#method-vipps). Exactly one payment method must be used. +Authorizations can be created using different payment methods: [`card`](#method-card), [`applepay`](#method-applepay), [`googlepay`](#method-googlepay), [`mobilepayonline`](#method-mobilepayonline), [`moto`](#method-moto), [`token`](#method-token), [`clicktopay`](#method-clicktopay) and [`vipps`](#method-vipps). Exactly one payment method must be used. ##### Parameters {{% description_list %}} diff --git a/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md new file mode 100644 index 0000000..f7d371b --- /dev/null +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md @@ -0,0 +1,100 @@ +--- +title: "clicktopay" +date: 2025-07-06T10:23:00+02:00 +anchor: "method-clicktopay" +weight: 239 +--- +### Method: clicktopay + +Click to Pay payment method for both Visa and Mastercard CITs. + +A Click to Pay authorization can be created using one of the two mutually exclusive interfaces. One by providing payloads and the other by providing raw values. + +#### Click to Pay payload interface: + +{{% description_list %}} +{{% description_term %}}clicktopay[payload] {{% regex %}}[\:json\:] {{% /regex %}} {{% /description_term %}} +{{% description_details %}} Full decrypted payload serialized as JSON, supplied as a string. The encrypted payload can be found in the `encryptedPayload` field in the Click to Pay checkout response. + +Example: `{"token":{"paymentToken":"",...}, "dynamicData":[{...}],...}` +{{% /description_details %}} + +{{% description_term %}}clicktopay[assurance_data] {{% regex %}}[\:json\:] {{% /regex %}} {{% /description_term %}} +{{% description_details %}} Full assurance data serialized as JSON, supplied as a string. The assurance data can be found in the `assuranceData` field in the Click to Pay checkout response. + +Example: `{"verificationData":[{"verificationType":"", "verificationMethod":"", "methodResults":{...},...},...], "eci":"",...}` + +{{% regex_optional %}}Required when 3‑D Secure authentication was performed `ONBEHALF`. Required for Visa tokens if no `[3dsecure]` with an `eci` is provided.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[3dsecure] {{% regex %}}dictionary{{% /regex %}}{{% /description_term %}} +{{% description_details %}}See [Authentication: [3dsecure]](#authentication-3dsecure). +{{% regex_optional %}}Optional.{{% /regex_optional %}} +{{% /description_details %}} +{{% /description_list %}} + +#### Click to Pay raw interface + +{{% description_list %}} + +{{% description_term %}}clicktopay[can] {{% regex %}}[0-9]{12,19}{{% /regex %}}{{% /description_term %}} +{{% description_details %}}Cardholder Account Number (CAN) of the card or token to charge. +{{% regex_optional %}} Required if `tan` is not present. Cannot be present if `tan` is present.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[tan] {{% regex %}}[0-9]{12,19}{{% /regex %}} Deprecated {{% /description_term %}} +{{% description_details %}} Token Account Number (TAN) of the token to charge. +{{% regex_optional %}} Required if `can` is not present. Cannot be present if `can` is present.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[expire_month] {{% regex %}}[0-9]{2}{{% /regex %}}{{% /description_term %}} +{{% description_details %}}Expiry month of the card or token to charge. +{{% /description_details %}} + +{{% description_term %}}clicktopay[expire_year] {{% regex %}}20[0-9]{2}{{% /regex %}}{{% /description_term %}} +{{% description_details %}}Expiry year of the card or token to charge. +{{% /description_details %}} + +{{% description_term %}}clicktopay[tav] {{% regex %}}[:base64:]{28}{{% /regex %}}{{% /description_term %}} +{{% description_details %}}Token authentication value, also known as cryptogram. +{{% regex_optional %}}Required when `can` is a token or when `tan` is provided.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[eci] {{% regex %}}0[0-9]{{% /regex %}}{{% /description_term %}} +{{% description_details %}}Zero-padded e-commerce indicator from Click to Pay flow. +{{% regex_optional %}}Required for Visa tokens if no `eci` from a 3-D Secure flow is present in `[onbehalf][eci]` or `[3dsecure]`.{{% /regex_optional %}} +{{% /description_details %}} + +If 3-D Secure authentication was performed `ONBEHALF` as part of the Click to Pay checkout flow, provide the authentication data in the `[onbehalf][...]` field: + +{{% description_term %}}clicktopay[onbehalf][trans_status] {{% regex %}}[A-Z]{{% /regex %}}{{% /description_term %}} +{{% description_details %}} 3-D Secure trans status from a 3-D Secure `ONBEHALF` flow. +{{% regex_optional %}} Optional. Provide it whenever the 3-D Secure result includes a trans status. {{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[onbehalf][eci] {{% regex %}}0[0-9]{{% /regex %}}{{% /description_term %}} +{{% description_details %}} 3-D Secure eci from a 3-D Secure `ONBEHALF` flow. +{{% regex_optional %}} Required when 3-D Secure was performed `ONBEHALF`. {{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[onbehalf][av] {{% regex %}}[:base64:]{28}{{% /regex %}}{{% /description_term %}} +{{% description_details %}} 3-D Secure authentication value from a 3-D Secure `ONBEHALF` flow. +{{% regex_optional %}} Required when `[onbehalf][trans_status]` is `Y` or `A`. Required for Visa when `[onbehalf][eci]` is `05` or `06`. Provide it whenever the 3-D Secure result includes an authentication value. {{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[onbehalf][ds_trans_id] {{% regex %}}[:UUID:]{{% /regex %}}{{% /description_term %}} +{{% description_details %}} 3-D Secure ds trans id from a 3-D Secure `ONBEHALF` flow. +{{% regex_optional %}}Required for Mastercard when 3-D Secure was performed `ONBEHALF`.{{% /regex_optional %}} +{{% /description_details %}} + +If 3-D Secure authentication was performed outside of the Click to Pay checkout flow, provide the authentication data in the `[3dsecure]` field: + +{{% description_term %}}clicktopay[3dsecure] {{% regex %}}dictionary{{% /regex %}}{{% /description_term %}} +{{% description_details %}} +See [Authentication: [3dsecure]](#authentication-3dsecure). +{{% /description_details %}} +{{% /description_list %}} + +{{% notice %}} +**Notice**: Signing is required to use the `clicktopay` payment method. +{{% /notice %}} diff --git a/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md b/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md index 85a8c26..65057c8 100644 --- a/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md @@ -6,11 +6,6 @@ weight: 240 --- ### Method: token -Token frameworks supported: - -* `clicktopay`: Click to Pay -* `token`: Visa and Mastercard - [token[m4m]](#deprecated) and [token[vts]](#deprecated) is deprecated, but still works. Requirement of some parameters depends on the initiator of the transaction; a parameter might be required for cardholder-initiated transactions (CITs) and otherwise optional. See the details for each parameter. @@ -19,41 +14,7 @@ Requirement of some parameters depends on the initiator of the transaction; a pa **Notice**: Signing is required to use the `token` payment method. {{% /notice %}} -#### Method: Click to Pay - -Click to Pay token payment method for both Visa and Mastercard CITs. - -{{% description_list %}} -{{% description_term %}}clicktopay[tan] {{% regex %}}[0-9]{12,19}{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Token Account Number (TAN) of the token to charge. -{{% /description_details %}} - -{{% description_term %}}clicktopay[expire_month] {{% regex %}}[0-9]{2}{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Expiry month of token to charge. -{{% /description_details %}} - -{{% description_term %}}clicktopay[expire_year] {{% regex %}}20[0-9]{2}{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Expiry year of token to charge. -{{% /description_details %}} - -{{% description_term %}}clicktopay[tav] {{% regex %}}[:base64:]{28}{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Token authentication value, also known as cryptogram. -{{% /description_details %}} - -{{% description_term %}}clicktopay[eci] {{% regex %}}0[57]{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Zero-padded e-commerce indicator from token flow. -{{% regex_optional %}}Required for Visa CITs.{{% /regex_optional %}} -{{% /description_details %}} - -{{% description_term %}}clicktopay[3dsecure] {{% regex %}}dictionary{{% /regex %}}{{% /description_term %}} -{{% description_details %}}See [Authentication: [3dsecure]](#authentication-3dsecure-v2). -{{% regex_optional %}}Optional{{% /regex_optional %}} -{{% /description_details %}} -{{% /description_list %}} - -#### Method: token - -Token payment method for both For both Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES) +Token payment method for both Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES) The required values are found in: - the VTS provision token response. @@ -105,7 +66,7 @@ The required values are found in: {{% description_term %}}token[tav] {{% regex %}}[:base64:]{28}{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Token Authentication Value (TAV) also know as token cryptogram. +{{% description_details %}}Token Authentication Value (TAV) also known as token cryptogram. Visa specific name: Token Authentication Verification Value (TAVV). diff --git a/website/content/gateway/examples/series_of_transactions/repeatedly_reserve_money/repeatedly_reserve_money.md b/website/content/gateway/examples/series_of_transactions/repeatedly_reserve_money/repeatedly_reserve_money.md index 43b1d8b..db0848e 100644 --- a/website/content/gateway/examples/series_of_transactions/repeatedly_reserve_money/repeatedly_reserve_money.md +++ b/website/content/gateway/examples/series_of_transactions/repeatedly_reserve_money/repeatedly_reserve_money.md @@ -47,7 +47,7 @@ curl -X POST \ -d "card[expire_year]=2026" \ -H "Signature: RS256-hex " ``` -A first-in-series authorization or debit can also be made using the {{% highlight_text %}}applepay{{% /highlight_text %}}, {{% highlight_text %}}googlepay{{% /highlight_text %}}, {{% highlight_text %}}mobilepayonline{{% /highlight_text %}}, {{% highlight_text %}}token{{% /highlight_text %}} or {{% highlight_text %}}vipps{{% /highlight_text %}} payment methods. +A first-in-series authorization or debit can also be made using the {{% highlight_text %}}applepay{{% /highlight_text %}}, {{% highlight_text %}}googlepay{{% /highlight_text %}}, {{% highlight_text %}}mobilepayonline{{% /highlight_text %}}, {{% highlight_text %}}token{{% /highlight_text %}}, {{% highlight_text %}}clicktopay{{% /highlight_text %}} or {{% highlight_text %}}vipps{{% /highlight_text %}} payment methods. A subsequent-in-series authorization or debit on a token must be made using the {{% highlight_text %}}token{{% /highlight_text %}} payment method. In case it is made using a PAN the {{% highlight_text %}}card{{% /highlight_text %}} payment method must be used.