From 106fd4642521cd42b43ef6472e198859698ebb49 Mon Sep 17 00:00:00 2001 From: Mikkel Thingholm Date: Tue, 2 Jun 2026 14:11:17 +0200 Subject: [PATCH 1/6] Add payload and assurance data parameters for click to pay payment method --- .../authorizations_methods/token.md | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) 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..26716a2 100644 --- a/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md @@ -24,6 +24,23 @@ Requirement of some parameters depends on the initiator of the transaction; a pa Click to Pay token payment method for both Visa and Mastercard CITs. {{% description_list %}} + +If 3-D Secure authentication was performed `ONBEHALF` as part of the Click to Pay flow, the following parameters can be provided: + +{{% 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":"",...}` +{{% /description_details %}} + +If 3-D Secure authentication was performed separately, the following parameters can be sent: + {{% 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 %}} @@ -53,7 +70,7 @@ Click to Pay token payment method for both Visa and Mastercard CITs. #### 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 +122,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). From 76c3063304fd6c1f70a1ab23dda4acae279d0162 Mon Sep 17 00:00:00 2001 From: Mikkel Thingholm Date: Thu, 4 Jun 2026 09:08:58 +0200 Subject: [PATCH 2/6] Enhance Click to Pay documentation by adding details for two interfaces --- .../authorizations_methods/token.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) 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 26716a2..80e2415 100644 --- a/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/token.md @@ -23,10 +23,11 @@ Requirement of some parameters depends on the initiator of the transaction; a pa Click to Pay token payment method for both Visa and Mastercard CITs. -{{% description_list %}} -If 3-D Secure authentication was performed `ONBEHALF` as part of the Click to Pay flow, the following parameters can be provided: +Click to Pay can be used through two interfaces. +The first interface uses the payloads from the checkout response: +{{% 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. @@ -37,9 +38,19 @@ Example: `{"token":{"paymentToken":"",...}, "dynamicData":[{...}],...}` {{% 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 for all Visa transactions. For Mastercard, required only when 3‑D Secure authentication was performed `ONBEHALF` {{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[3dsecure] {{% regex %}}dictionary{{% /regex %}}{{% /description_term %}} +{{% description_details %}}See [Authentication: [3dsecure]](#authentication-3dsecure-v2). +{{% regex_optional %}}Optional. Should be sent if 3D-Secure authentication was done separately{{% /regex_optional %}} {{% /description_details %}} +{{% /description_list %}} -If 3-D Secure authentication was performed separately, the following parameters can be sent: +The second interface uses raw values: + +{{% 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. From cd0b865f74b8d8931f5108f33d225ea65592a9fe Mon Sep 17 00:00:00 2001 From: Mikkel Thingholm Date: Tue, 7 Jul 2026 10:48:01 +0200 Subject: [PATCH 3/6] Separate click to pay documentation from token and add 3ds onbehalf --- .../authorizations_methods/clicktopay.md | 87 +++++++++++++++++++ .../authorizations_methods/token.md | 67 -------------- 2 files changed, 87 insertions(+), 67 deletions(-) create mode 100644 website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md 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..419058e --- /dev/null +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md @@ -0,0 +1,87 @@ +--- +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 by providing payloads: + +{{% 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 for all Visa transactions. For Mastercard, required only when 3‑D Secure authentication was performed `ONBEHALF` {{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[3dsecure] {{% regex %}}dictionary{{% /regex %}}{{% /description_term %}} +{{% description_details %}}See [Authentication: [3dsecure]](#authentication-3dsecure). +{{% regex_optional %}}Optional. Should be sent if 3D-Secure authentication was performed on the side.{{% /regex_optional %}} +{{% /description_details %}} +{{% /description_list %}} + +Alternatively, a Click to Pay authorization can be created by providing raw values: + +{{% description_list %}} + +{{% description_term %}}clicktopay[pan] {{% regex %}}[0-9]{12,19}{{% /regex %}}{{% /description_term %}} +{{% description_details %}}Primary Account Number (PAN) of the card or token to charge. +{{% /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 for tokens.{{% /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 token CITs and required if 3-D Secure was performed `ONBEHALF`.{{% /regex_optional %}} +{{% /description_details %}} + +If 3-D Secure was performed `ONBEHALF` provide the authentication data in `onbehalf_*` fields: + +{{% 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 %}} Required when 3-D Secure was performed `ONBEHALF`. {{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}clicktopay[onbehalf_cav] {{% regex %}}[:base64:]{28}{{% /regex %}}{{% /description_term %}} +{{% description_details %}} 3-D Secure authentication value 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_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 was performed on the side 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 80e2415..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,68 +14,6 @@ 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. - - -Click to Pay can be used through two interfaces. -The first interface uses the payloads from the checkout response: - -{{% 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 for all Visa transactions. For Mastercard, required only when 3‑D Secure authentication was performed `ONBEHALF` {{% /regex_optional %}} -{{% /description_details %}} - -{{% description_term %}}clicktopay[3dsecure] {{% regex %}}dictionary{{% /regex %}}{{% /description_term %}} -{{% description_details %}}See [Authentication: [3dsecure]](#authentication-3dsecure-v2). -{{% regex_optional %}}Optional. Should be sent if 3D-Secure authentication was done separately{{% /regex_optional %}} -{{% /description_details %}} -{{% /description_list %}} - -The second interface uses raw values: - -{{% 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 Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES) The required values are found in: From d4815a27680cb17b17448d950638ef981680165a Mon Sep 17 00:00:00 2001 From: Mikkel Thingholm Date: Mon, 13 Jul 2026 12:28:06 +0200 Subject: [PATCH 4/6] Change onbehalf fields to be sub-dicted in [onbehalf] --- .../authorizations_methods/clicktopay.md | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md index 419058e..f5ab082 100644 --- a/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md @@ -8,7 +8,9 @@ weight: 239 Click to Pay payment method for both Visa and Mastercard CITs. -A Click to Pay authorization can be created by providing payloads: +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. + +The Click to Pay payload interface: {{% description_list %}} {{% description_term %}}clicktopay[payload] {{% regex %}}[\:json\:] {{% /regex %}} {{% /description_term %}} @@ -27,16 +29,16 @@ Example: `{"verificationData":[{"verificationType":"", "verificationMethod":"", {{% description_term %}}clicktopay[3dsecure] {{% regex %}}dictionary{{% /regex %}}{{% /description_term %}} {{% description_details %}}See [Authentication: [3dsecure]](#authentication-3dsecure). -{{% regex_optional %}}Optional. Should be sent if 3D-Secure authentication was performed on the side.{{% /regex_optional %}} +{{% regex_optional %}}Optional. Should be sent if 3-D Secure authentication was performed on the side.{{% /regex_optional %}} {{% /description_details %}} {{% /description_list %}} -Alternatively, a Click to Pay authorization can be created by providing raw values: +The Click to Pay raw interface: {{% description_list %}} -{{% description_term %}}clicktopay[pan] {{% regex %}}[0-9]{12,19}{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Primary Account Number (PAN) of the card or token to charge. +{{% 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. {{% /description_details %}} {{% description_term %}}clicktopay[expire_month] {{% regex %}}[0-9]{2}{{% /regex %}}{{% /description_term %}} @@ -54,22 +56,27 @@ Alternatively, a Click to Pay authorization can be created by providing raw valu {{% 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 token CITs and required if 3-D Secure was performed `ONBEHALF`.{{% /regex_optional %}} +{{% regex_optional %}}Required for Visa token CITs if no eci from a 3-D Secure flow is present in `[onbehalf][eci]` or `[3dsecure]`.{{% /regex_optional %}} {{% /description_details %}} -If 3-D Secure was performed `ONBEHALF` provide the authentication data in `onbehalf_*` fields: +If 3-D Secure was performed `ONBEHALF` provide the authentication data in `[onbehalf][...]` fields: -{{% description_term %}}clicktopay[onbehalf_trans_status] {{% regex %}}[A-Z]{{% /regex %}}{{% /description_term %}} +{{% 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 %}} Required when 3-D Secure was performed `ONBEHALF`. {{% /regex_optional %}} {{% /description_details %}} -{{% description_term %}}clicktopay[onbehalf_cav] {{% regex %}}[:base64:]{28}{{% /regex %}}{{% /description_term %}} +{{% description_term %}}clicktopay[onbehalf][eci] {{% regex %}}[A-Z]{{% /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 3-D Secure was performed `ONBEHALF`. {{% /regex_optional %}} {{% /description_details %}} -{{% description_term %}}clicktopay[onbehalf_ds_trans_id] {{% regex %}}[:UUID:]{{% /regex %}}{{% /description_term %}} +{{% 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 %}} From 978f960891cb1728c19773a5bfbe7ca6f836f1e7 Mon Sep 17 00:00:00 2001 From: Mikkel Thingholm Date: Thu, 16 Jul 2026 13:08:02 +0200 Subject: [PATCH 5/6] Add Click to Pay updates and new CSS for deprecated badge - Introduced a new CSS class for the deprecated badge to enhance visual representation. - Updated API reference documentation to include details on the Click to Pay payment method, including support for both cards and tokens, and the introduction of a payload interface. - Revised existing documentation to reflect changes in Click to Pay parameters and interfaces, ensuring clarity on usage and requirements. --- website/assets/css/docs.css | 13 +++++++++++++ .../gateway/api_reference/changes/changes.md | 8 +++++++- .../authorizations_methods/clicktopay.md | 18 +++++++++++------- .../repeatedly_reserve_money.md | 2 +- 4 files changed, 32 insertions(+), 9 deletions(-) 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..aec4f4f 100644 --- a/website/content/gateway/api_reference/changes/changes.md +++ b/website/content/gateway/api_reference/changes/changes.md @@ -10,6 +10,12 @@ 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`. + #### 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 +35,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_methods/clicktopay.md b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md index f5ab082..4a828cb 100644 --- a/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md @@ -10,7 +10,7 @@ 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. -The Click to Pay payload interface: +#### Click to Pay payload interface: {{% description_list %}} {{% description_term %}}clicktopay[payload] {{% regex %}}[\:json\:] {{% /regex %}} {{% /description_term %}} @@ -24,16 +24,16 @@ Example: `{"token":{"paymentToken":"",...}, "dynamicData":[{...}],...}` Example: `{"verificationData":[{"verificationType":"", "verificationMethod":"", "methodResults":{...},...},...], "eci":"",...}` -{{% regex_optional %}}Required for all Visa transactions. For Mastercard, required only when 3‑D Secure authentication was performed `ONBEHALF` {{% /regex_optional %}} +{{% 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. Should be sent if 3-D Secure authentication was performed on the side.{{% /regex_optional %}} +{{% regex_optional %}}Optional.{{% /regex_optional %}} {{% /description_details %}} {{% /description_list %}} -The Click to Pay raw interface: +#### Click to Pay raw interface {{% description_list %}} @@ -41,6 +41,10 @@ The Click to Pay raw interface: {{% description_details %}}Cardholder Account Number (CAN) of the card or token to charge. {{% /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. This field remains supported and is handled identically to `clicktopay[can]`. +{{% /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 %}} @@ -51,12 +55,12 @@ The Click to Pay raw interface: {{% description_term %}}clicktopay[tav] {{% regex %}}[:base64:]{28}{{% /regex %}}{{% /description_term %}} {{% description_details %}}Token authentication value, also known as cryptogram. -{{% regex_optional %}}Required for tokens.{{% /regex_optional %}} +{{% regex_optional %}}Required when `can` is a token.{{% /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 token CITs if no eci from a 3-D Secure flow is present in `[onbehalf][eci]` or `[3dsecure]`.{{% /regex_optional %}} +{{% 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 was performed `ONBEHALF` provide the authentication data in `[onbehalf][...]` fields: @@ -66,7 +70,7 @@ If 3-D Secure was performed `ONBEHALF` provide the authentication data in `[onbe {{% regex_optional %}} Required when 3-D Secure was performed `ONBEHALF`. {{% /regex_optional %}} {{% /description_details %}} -{{% description_term %}}clicktopay[onbehalf][eci] {{% regex %}}[A-Z]{{% /regex %}}{{% /description_term %}} +{{% 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 %}} 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. From 19b4c3081dc0013cafba4e26afa462073de51e3f Mon Sep 17 00:00:00 2001 From: Mikkel Thingholm Date: Thu, 20 Aug 2026 12:39:27 +0200 Subject: [PATCH 6/6] Improve clicktopay documentation --- .../gateway/api_reference/changes/changes.md | 4 ++++ .../api_resources/authorizations/authorizations.md | 2 +- .../authorizations_methods/clicktopay.md | 14 ++++++++------ 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/website/content/gateway/api_reference/changes/changes.md b/website/content/gateway/api_reference/changes/changes.md index aec4f4f..fc132d0 100644 --- a/website/content/gateway/api_reference/changes/changes.md +++ b/website/content/gateway/api_reference/changes/changes.md @@ -12,9 +12,13 @@ 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`. 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 index 4a828cb..f7d371b 100644 --- a/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md +++ b/website/content/gateway/api_resources/authorizations/authorizations_methods/clicktopay.md @@ -39,10 +39,12 @@ Example: `{"verificationData":[{"verificationType":"", "verificationMethod":"", {{% 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. This field remains supported and is handled identically to `clicktopay[can]`. +{{% 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 %}} @@ -55,7 +57,7 @@ Example: `{"verificationData":[{"verificationType":"", "verificationMethod":"", {{% 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.{{% /regex_optional %}} +{{% 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 %}} @@ -63,11 +65,11 @@ Example: `{"verificationData":[{"verificationType":"", "verificationMethod":"", {{% 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 was performed `ONBEHALF` provide the authentication data in `[onbehalf][...]` fields: +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 %}} Required when 3-D Secure was performed `ONBEHALF`. {{% /regex_optional %}} +{{% 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 %}} @@ -77,7 +79,7 @@ If 3-D Secure was performed `ONBEHALF` provide the authentication data in `[onbe {{% 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 3-D Secure was performed `ONBEHALF`. {{% /regex_optional %}} +{{% 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 %}} @@ -85,7 +87,7 @@ If 3-D Secure was performed `ONBEHALF` provide the authentication data in `[onbe {{% regex_optional %}}Required for Mastercard when 3-D Secure was performed `ONBEHALF`.{{% /regex_optional %}} {{% /description_details %}} -If 3-D Secure was performed on the side provide the authentication data in the `3dsecure` field: +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 %}}