# General and special cases This chapter covers general and special cases, that do not apply to one payment method, but also do not apply in every case, for example special behaviors in case of certain acquirers and special features, across multiple payment methods, that need a special integration. This chapter covers these cases. ## Pre-Authorizations In case of many payment methods, they go through a two step process, we call Authorization and [Capture](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/capture-and-daily-closing). This can be used to charge the customer at a later date to the time of the transaction, while still having a guarantee, that the money will arrive, in contrast to authorizing and capturing at a later date, e.g. by using [Recurring Payments](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments). Usually, the Capture has to happen within 10 days, depending on the payment method and the card hodlers bank -this is just a rule of thumb-. After this time-frame has passed, there won't be a guarantee, that the money can still be deducted from the payers bank-account. Some businesses however require the authorization to be valid for a longer time. This is, where pre-authorizations come into play. This feature can extend the window to a guaranteed 30 days, giving the merchant more time to deliver their service(s). {% hint style="warning" %} Please note, that pre-authorizations can introduce additional fees. Please contact your account manager, or [our sales directly](https://docs.saferpay.com/home/support#worldline-sales-team), for more information. {% endhint %} ### Supported payment methods The following payment methods do support pre-authorizations: * [VISA/Vpay](https://docs.saferpay.com/home/integration-guide/payment-methods/visa-and-vpay) * [Mastercard](https://docs.saferpay.com/home/integration-guide/payment-methods/mastercard) * [Maestro](https://docs.saferpay.com/home/integration-guide/payment-methods/maestro) ### Technical and contractual requirements In order to be applicable for pre-authorizations, the following requirements need to be met: * Pre-Authorizations are only applicable for certain Merchant Category Codes (MCC). The MCC is basically an ID, that defines the general area of business the merchant is in. For example, if they are dealing with electronics, are in the hospitality business, a flight agency etc.\ Please contact your account manager, [or our sales](https://docs.saferpay.com/home/support#worldline-sales-team), if you have questions about this detail. * Pre-Authorizations need to be flagged through the Saferpay API, with the initial request, during a transaction. For example the [Payment Page-](https://docs.saferpay.com/home/licences-and-interfaces/payment-page#id-1-paymentpage-initialize-request), or [Transaction](https://docs.saferpay.com/home/licences-and-interfaces/transaction-interface#id-1-transaction-initialize) Initialize, or Authorize Direct, in case of [Recurring Payments](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments). To do so, you must set the **`Payment.Options.PreAuth`** parameter to **`true`**. ### What to do, if more time is needed Pre-Authorizations only work within that 30 day time-frame. If your business-case requires more time, then you have to re-authorize the card, effectively doing a new transaction. You can do so, by first saving the card inside our [Secure Card Data storage](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/secure-card-data) and then use our [Recurring Payments flow](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments) to authorize the card at a later date. This has the upside, that you can go way beyond the 30 days of pre-authorizations. However the downside is, that the solvency of the payer can change during that time, leading to the card being rejected. So you need to evaluate, which flow is best for you in a given situation. ## Partial approvals A partial approval is best explained with an example: A customer comes to your shop and orders goods worth 100 Euros. He/she enters the card details, and Saferpay authorizes the card. During authorization, the cardholder's bank checks the solvency of the cardholder and concludes that only a maximum of 80 Euros can be authorized. Usually, such a transaction would be declined. However, if the merchant requests a partial approval, the card can be authorized for 80 Euros. This sort of authorization type is best suited for goods that are sold in bulk, like for example screws, certain food items, or petrol at a gas station. {% hint style="warning" %} Not all Issuers may support this feature. If partial approvals are not supported, either the full amount will be authorized, or the transaction will be declined. {% endhint %} ### Requirements * Partial approvals can only be requested with **SpecVersion 1.29**, or higher. * Partial approvals are only available for [Visa/VPay](https://docs.saferpay.com/home/integration-guide/payment-methods/visa-and-vpay), [Mastercard](https://docs.saferpay.com/home/integration-guide/payment-methods/mastercard) and [Maestro](https://docs.saferpay.com/home/integration-guide/payment-methods/maestro). ### Integration A partial approval can only be requested when using either the [Authorize Direct Request](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_AuthorizeDirect), or [the Transaction Interface integration](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface) In the request, the parameter **Payment.Options.AllowPartialAuthorization** must be set to true. {% hint style="warning" %} Please make sure that you have read the [PSD2](https://docs.saferpay.com/home/integration-guide/general-information/psd2) chapter, since an [Authorize Direct](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_AuthorizeDirect) request is classified as a Merchant Initiated Transaction (MIT), if you intent to use this request! {% endhint %} {% hint style="warning" %} The merchant must make sure that his inventory is adjusted accordingly, since less will be payed than initially requested. {% endhint %} {% hint style="warning" %} If a partial approval is executed, [DCC](https://docs.saferpay.com/home/integration-guide/general-information/dynamic-currency-conversion) will not be performed! {% endhint %} ### Example of Authorize Direct {% tabs %} {% tab title="Request" %} ```json { "RequestHeader": { "SpecVersion": "[CURRENT SPEC_VERSION]", "CustomerId": "[your customer id]", "RequestId": "8cf6d15a041ba515d90ee191257d9f77", "RetryIndicator": 0, "ClientInfo": { "ShopInfo": "My Shop", "OsInfo": "Windows Server 2013" } }, "TerminalId": "[your Terminal id]", "Payment": { "Amount": { "Value": "10000", "CurrencyCode": "EUR" }, "OrderId": "Order_2", "Description": "Test Order #2", "Options": { "AllowPartialAuthorization": true } }, "Payer": { "IpAddress": "192.168.178.55", "LanguageCode": "en" }, "PaymentMeans": { "Alias": { "Id": "77b828c0975498e986e1663489ceacdc" } } } ``` {% endtab %} {% tab title="Response" %} ```json { "ResponseHeader": { "SpecVersion": "[CURRENT SPEC_VERSION]", "RequestId": "8cf6d15a041ba515d90ee191257d9f77" }, "Transaction": { "Type": "PAYMENT", "Status": "AUTHORIZED", "Id": "69W8jSbjbhA2vASMbxUUAl3Q4OKA", "Date": "2020-11-04T12:29:07.646+01:00", "Amount": { "Value": "5000", "CurrencyCode": "EUR" }, "OrderId": "Order_2", "AcquirerName": "VISA Saferpay Test", "AcquirerReference": "05718468252", "SixTransactionReference": "0:0:3:69W8jSbjbhA2vASMbxUUAl3Q4OKA", "ApprovalCode": "715453" }, "PaymentMeans": { "Brand": { "PaymentMethod": "VISA", "Name": "VISA" }, "DisplayText": "xxxx xxxx xxxx 0013", "Card": { "MaskedNumber": "xxxxxxxxxxxx0013", "ExpYear": 2022, "ExpMonth": 2, "HolderName": "test", "CountryCode": "DE", "HashValue": "E1DB6CE1CC017DCB651E7256650023698E58E158" } }, "Payer": { "IpAddress": "192.168.178.55" } } ``` {% endtab %} {% endtabs %} ### Example for the Transaction Interface Since the Transaction Interface consists of more, than just one request, you have to first request a partial approval with [Transaction Initialize](https://docs.saferpay.com/home/licences-and-interfaces/transaction-interface#1-transaction-initialize): ```json { "RequestHeader": { "SpecVersion": "[CURRENT SPEC_VERSION]", "CustomerId": "[your customer id]", "RequestId": "ea665434145edac8652a2aa310935f73", "RetryIndicator": 0 }, "TerminalId": "[your terminal id]", "Payment": { "Amount": { "Value": "10000", "CurrencyCode": "CHF" }, "Options": { "AllowPartialAuthorization": true } }, "Payer": { "LanguageCode": "en" }, "ReturnUrls": { "Success": "[your shop payment success url]", "Fail": "[your shop payment fail url]" }, "Styling": { "CssUrl": "[your shop css url]" } } ``` [Transaction Authorize](https://docs.saferpay.com/home/licences-and-interfaces/transaction-interface#4-transaction-authorize) will then return the authorized amount: ```json { "ResponseHeader": { "SpecVersion": "[CURRENT SPEC_VERSION]", "RequestId": "47f456c9d051e58d7c046068cc0537c1" }, "Transaction": { "Type": "PAYMENT", "Status": "AUTHORIZED", "Id": "78TrOlbjbhA2vASMbxUUAliO3gPk", "Date": "2022-25-07T11:43:07.646+01:00", "Amount": { "Value": "5000", "CurrencyCode": "EUR" }, "OrderId": "Order_3", "AcquirerName": "VISA Saferpay Test", "AcquirerReference": "05718468253", "SixTransactionReference": "0:0:3:78TrOlbjbhA2vASMbxUUAliO3gPk", "ApprovalCode": "715453" }, "PaymentMeans": { "Brand": { "PaymentMethod": "VISA", "Name": "VISA" }, "DisplayText": "xxxx xxxx xxxx 0013", "Card": { "MaskedNumber": "xxxxxxxxxxxx0013", "ExpYear": 2022, "ExpMonth": 2, "HolderName": "test", "CountryCode": "DE", "HashValue": "E1DB6CE1CC017DCB651E7256650023698E58E158" } }, "Payer": { "IpAddress": "192.168.178.55" } } ``` ## Decrypted Scheme tokens Saferpay also supports the direct insertion of decrypted Scheme-tokens, provided by any external provider (For example, Apple Pay). This way, it is possible to provide a more seamless and integrated solution. However, in this case, the integration is realized via the [Transaction Interface](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface). The overall transaction-flow will stay the same. The only thing you must take care of is, that you provide the necessary data, within the **PaymentMeans.SchemeToken** container, through the [Initialization request](https://docs.saferpay.com/home/licences-and-interfaces/transaction-interface#1-transaction-initialize). {% hint style="danger" %} Since the Tokens are decrypted in those cases, this integration is only allowed with a [full PCI certification.](https://docs.saferpay.com/home/integration-guide/general-information/data-security-and-pci-dss) {% endhint %} ```json { "RequestHeader": { "SpecVersion": "[current Spec-Version]", "CustomerId": "[your customer id]", "RequestId": "[unique request id]", "RetryIndicator": 0 }, "TerminalId": "[your terminal id]", "Payment": { "Amount": { "Value": "100", "CurrencyCode": "CHF" } }, "PaymentMeans": { "SchemeToken": { "Number": [DECRYPTED TOKEN NUMBER], "ExpMonth": "03", "ExpYear:" "2021", "AuthValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA=", "TokenType": [TYPE OF TOKEN see Spec] } }, "Payer": { "LanguageCode": "en" }, "ReturnUrls": { "Success": "[your shop payment success url]", "Fail": "[your shop payment fail url]" }, "Styling": { "CssUrl": "[your shop css url]" } } ``` ## Dual branded cards Many credit cards are also dual-branded, meaning, that they do have a second brand attached to their main brand, for example a Bancontact card also having Visa functionality. This means, that this card can be processed as both, [Bancontact](https://docs.saferpay.com/home/integration-guide/payment-methods/bancontact) and [Visa](https://docs.saferpay.com/home/integration-guide/payment-methods/visa-and-vpay). Saferpay generally does support dual branded cards and is able to detect these cards. These cards have a primary and a secondary branding, meaning, that one brand is preferred over the other. Saferpay will automatically detect these brands and attempt to perform the transaction through the primary brand. If that is not possible, Saferpay will attempt to process via the secondary brand. So in case of the example above, Saferpay will first attempt to perform a [Bancontact](https://docs.saferpay.com/home/integration-guide/payment-methods/bancontact) transaction and if that brand is not available for processing, we will proceed with [Visa](https://docs.saferpay.com/home/integration-guide/payment-methods/visa-and-vpay). In order for this to work, one, or both, of these brands must be activated on your [terminal](https://docs.saferpay.com/home/master/common-saferpay-terms-glossary#terminalid). In case of the example above, you either need [Bancontact](https://docs.saferpay.com/home/integration-guide/payment-methods/bancontact) or [Visa](https://docs.saferpay.com/home/integration-guide/payment-methods/visa-and-vpay) to be active. {% hint style="warning" %} If the primary brand rejects the transaction, Saferpay will not attempt to perform a transaction through the secondary brand, as this is deemed a valid rejection. The secondary brand will only be used, if the processing via the primary is not available (e.g. the brand not being activated on the [terminal](https://docs.saferpay.com/home/master/common-saferpay-terms-glossary#terminalid)). {% endhint %} ## Special Cases Though we at Worldline do offer the possibility to process credit cards, it is sometimes necessary to involve third parties in order to process credit cards in certain countries and regions. This chapter will cover the special characteristics you need to consider, if you want to use Saferpay with these processors. ### Credit Cards #### Chase Paymentech Chase Paymentech is a US credit card processor with office in Dallas, Texas. Worldline offers the possibility to process credit cards over this processor, directly in the US. Please take note to the following restrictions and characteristics. * **OrderId:** Due to technical restrictions, the **OrderId** will not be forwarded to Chase to be shown on your reconciliation files from chase. Saferpay will instead fill it with a unique, increasing, numeric value, to meet Chase Paymentechs requirements. Therefore, a later identification through the **OrderId** will not be possible.