diff --git a/website/content/gateway/api_reference/changes/changes.md b/website/content/gateway/api_reference/changes/changes.md index a3998ea..0639cc5 100644 --- a/website/content/gateway/api_reference/changes/changes.md +++ b/website/content/gateway/api_reference/changes/changes.md @@ -10,6 +10,15 @@ Follow coming changes on the [source code repository](https://github.com/clearha Sorted by descending timestamp. +#### Add recipient and sender parameters for individual name parts +Starting 2025-XX-XX, the new name-related parameters `recipient[first_name]`, +`recipient[middle_name]`, `recipient[last_name]`, `sender[first_name]`, +`sender[middle_name]` and `sender[last_name]` are supported. +This will in time push for the deprecation of `card[name]`, `recipient[name]` +and `sender[name]`. Both old and new parameters will be supported +in a grace period, however, it is recommended that you plan the switch as we +cannot guarantee how long our upstream provider supports the old fields. + #### Add minimum amount for Visa captures and refunds Starting 2025-05-19, we will enforce a minimum amount of USD 0.005 for captures and refunds made with Visa. This is due to USD 0.005 being half a minor, and diff --git a/website/content/gateway/api_reference/resources/credits/credits.md b/website/content/gateway/api_reference/resources/credits/credits.md index c6c308d..0fda740 100644 --- a/website/content/gateway/api_reference/resources/credits/credits.md +++ b/website/content/gateway/api_reference/resources/credits/credits.md @@ -9,6 +9,9 @@ To payout (e.g. winnings and not refunds) money to a cardholder’s bank account ```shell POST https://gateway.clearhaus.com/credits ``` + +Information about the recipient is required for credits under certain circumstances to be compliant with card scheme rules. See [Recipient information](#credit_recipient_information). + ##### Parameters {{% description_list %}} {{% description_term %}}amount{{% regex %}}[1-9][0-9]{,8}{{% /regex %}}{{% /description_term %}} @@ -49,9 +52,10 @@ POST https://gateway.clearhaus.com/credits {{% regex_optional %}}Optional.{{% /regex_optional %}} {{% /description_details %}} -{{% description_term %}}card[name] {{% regex %}}[A-Za-z0-9 ]{1,30}{{% /regex %}}{{% /description_term %}} -{{% description_details %}}Name on card. -{{% regex_optional %}}Required for Mastercard Payment of Winnings (PoW) and for Mastercard cross-border non-PoW.{{% /regex_optional %}} +{{% description_term %}}{{% strike %}}card[name]{{% /strike %}} {{% regex %}}[A-Za-z0-9 ]{1,30}{{% /regex %}}{{% /description_term %}} +{{% description_details %}} +{{% regex_optional %}}Deprecated, see [Recipient information](#credit_recipient_information) instead.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient`.{{% /regex_optional %}} {{% /description_details %}} {{% /description_list %}} diff --git a/website/content/gateway/api_reference/resources/credits/recipient_information.md b/website/content/gateway/api_reference/resources/credits/recipient_information.md new file mode 100644 index 0000000..c19f7d7 --- /dev/null +++ b/website/content/gateway/api_reference/resources/credits/recipient_information.md @@ -0,0 +1,35 @@ +--- +title: "recipient_information" +date: 2023-07-20T13:01:49+01:00 +anchor: "credit_recipient_information" +weight: 181 +--- +##### Recipient information +See the partner guideline for more details. + +{{% description_list %}} + +{{% description_term %}}recipient[first_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The recipient's legal first name. + +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} +{{% regex_optional %}}Required for Mastercard Payment of Winnings (PoW) and for Mastercard cross-border non-PoW, i.e. it is only optional for Visa and for Mastercard domestic non-PoW.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient[name]`.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}recipient[middle_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The recipient's legal middle name in case of any. +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} +{{% regex_optional %}}If set, it requires `recipient[first_name]` and `recipient[last_name]` to be set.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient[name]`.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}recipient[last_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The recipient's legal last name. + +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} +{{% regex_optional %}}Required for Mastercard Payment of Winnings (PoW) and for Mastercard cross-border non-PoW, i.e. it is only optional for Visa and for Mastercard domestic non-PoW.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient[name]`.{{% /regex_optional %}} +{{% /description_details %}} + +{{% /description_list %}} diff --git a/website/content/gateway/api_reference/resources/debits/debits.md b/website/content/gateway/api_reference/resources/debits/debits.md index d45d773..6a53c87 100644 --- a/website/content/gateway/api_reference/resources/debits/debits.md +++ b/website/content/gateway/api_reference/resources/debits/debits.md @@ -11,7 +11,7 @@ POST https://gateway.clearhaus.com/debits ``` Debits support the same parameters and payment methods as [Authorizations](#authorizations), with the exception that amount must be greater than zero. -Information about sender and recipient is required for debits under certain circumstances to be compliant with card scheme rules. See [Sender information](#sender_information) and [Recipient information](#recipient_information). +Information about sender and recipient is required for debits under certain circumstances to be compliant with card scheme rules. See [Sender information](#sender_information) and [Recipient information](#debit_recipient_information). {{% notice %}} **Notice:** Only merchants with selected Merchant Category Codes (MCCs) and assigned Business Application Identifiers (BAIs) (Visa) or Transaction Type Indicators (TTIs) (Mastercard) are able to process a debit; namely exactly those that will result in the debit being a Visa Account Funding Transaction (AFT) or Mastercard Funding Transaction (FT). diff --git a/website/content/gateway/api_reference/resources/debits/recipient_information.md b/website/content/gateway/api_reference/resources/debits/recipient_information.md index 65b9a15..1d2ddc0 100644 --- a/website/content/gateway/api_reference/resources/debits/recipient_information.md +++ b/website/content/gateway/api_reference/resources/debits/recipient_information.md @@ -1,7 +1,7 @@ --- title: "recipient_information" date: 2023-07-20T13:01:49+01:00 -anchor: "recipient_information" +anchor: "debit_recipient_information" weight: 178 --- ##### Recipient information @@ -9,13 +9,33 @@ See the partner guideline for more details. {{% description_list %}} -{{% description_term %}}recipient[name] {{% regex %}}[\x20-\x7E]{2,30} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} -{{% description_details %}}The recipient's legal name. +{{% description_term %}}{{% strike %}}recipient[name]{{% /strike %}} {{% regex %}}[\x20-\x7E]{2,30} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}} +{{% regex_optional %}}Deprecated, see `recipient[first_name]`, `recipient[middle_name]` and `recipient[last_name]` instead.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient[first_name]`, `recipient[middle_name]` and `recipient[last_name]`.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}recipient[first_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The recipient's legal first name. + +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} +{{% regex_optional %}}Required.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient[name]`.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}recipient[middle_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The recipient's legal middle name in case of any. +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} +{{% regex_optional %}}If set, it requires `recipient[first_name]` and `recipient[last_name]` to be set.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient[name]`.{{% /regex_optional %}} +{{% /description_details %}} -Example: "Doe Jane A." (last name, first name, optional middle initial). +{{% description_term %}}recipient[last_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The recipient's legal last name. -{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete (only first or last name).{{% /regex_optional %}} +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} {{% regex_optional %}}Required.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `recipient[name]`.{{% /regex_optional %}} {{% /description_details %}} {{% description_term %}}recipient[account_number] {{% regex %}}[\x20-\x7E]{1,34} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} diff --git a/website/content/gateway/api_reference/resources/debits/sender_information.md b/website/content/gateway/api_reference/resources/debits/sender_information.md index 02890df..084e2b0 100644 --- a/website/content/gateway/api_reference/resources/debits/sender_information.md +++ b/website/content/gateway/api_reference/resources/debits/sender_information.md @@ -11,13 +11,34 @@ Intra-EEA, mentioned below, includes the United Kingdom and Gibraltar. {{% description_list %}} -{{% description_term %}}sender[name] {{% regex %}}[\x20-\x7E]{2,30} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} -{{% description_details %}}The sender's legal name. +{{% description_term %}}{{% strike %}}sender[name]{{% /strike %}} {{% regex %}}[\x20-\x7E]{2,30} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}} +{{% regex_optional %}}Deprecated, see `sender[first_name]`, `sender[middle_name]` and `sender[last_name]` instead.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `sender[first_name]`, `sender[middle_name]` and `sender[last_name]`.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}sender[first_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The sender's legal first name. + +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} +{{% regex_optional %}}Required for intra-EEA and international debits. Also required if any of the address-related parameters are supplied.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `sender[name]`.{{% /regex_optional %}} +{{% /description_details %}} + +{{% description_term %}}sender[middle_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The sender's legal middle name in case of any. + +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} +{{% regex_optional %}}If set, it requires `sender[first_name]` and `sender[last_name]` to be set.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `sender[name]`.{{% /regex_optional %}} +{{% /description_details %}} -Example: "Doe Jane A." (last name, first name, optional middle initial). +{{% description_term %}}sender[last_name] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} +{{% description_details %}}The sender's legal last name. -{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete (only first or last name).{{% /regex_optional %}} +{{% regex_optional %}}It must not contain special characters (?, @, #, $, &, \*, etc.), be all numeric, be fictious, be a nickname or be incomplete.{{% /regex_optional %}} {{% regex_optional %}}Required for intra-EEA and international debits. Also required if any of the address-related parameters are supplied.{{% /regex_optional %}} +{{% regex_optional %}}Mutually exclusive with `sender[name]`.{{% /regex_optional %}} {{% /description_details %}} {{% description_term %}}sender[address] {{% regex %}}[\x20-\x7E]{1,35} [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters){{% /regex %}}{{% /description_term %}} diff --git a/website/content/gateway/examples/payout_to_cardholder/payout_to_cardholder.md b/website/content/gateway/examples/payout_to_cardholder/payout_to_cardholder.md index 6cbe4e9..b946890 100644 --- a/website/content/gateway/examples/payout_to_cardholder/payout_to_cardholder.md +++ b/website/content/gateway/examples/payout_to_cardholder/payout_to_cardholder.md @@ -33,5 +33,5 @@ Example response (snippet): } ``` -The field {{% highlight_text %}}card[name]{{% /highlight_text %}} is mandatory for Mastercard Payment of winnings (gaming/gambling merchants). +The fields {{% highlight_text %}}recipient[first_name]{{% /highlight_text %}} and {{% highlight_text %}}recipient[last_name]{{% /highlight_text %}} are required for Mastercard Payment of Winnings (PoW, i.e. gaming/gambling merchants) and for Mastercard cross-border non-PoW. Depending on card scheme and merchant category, the name on the card might be necessary for approval of credits.