PAYONE Documentation Platform | PAYONE Secured Installment

payone secured installment

General notes

For every PAYONE Buy Now Pay Later payment method there are general requirements that should be considered for a successful integration:

Countries	Currency	Special Parameters	Limitations
Germany Austria	Euro	Snippet for device fingerprinting token Mandatory checkout information Cancellation reason has to be provided if a capture = 0 is done	B2B transactions (Payone Secured Invoice only) Delivery addresses cannot deviate from billing address

Mandatory parameters

The following parameters are mandatory for every PAYONE Buy Now Pay Later payment method:

Parameter	Description
Customer
customer.businessRelation	Business relation to the customer. Possible values: B2C or B2B. Currently B2B is only available for PAYONE Secured Invoice. If B2B is provided, company customer.companyInformation is a mandatory field.
customer.personalInformation.name.firstName	Given name(s) or first name(s) of the customer
customer.personalInformation.name.surname	Surname(s) or last name(s) of the customer
customer.personalInformation.dateOfBirth	The date of birth of the customer
Contact Information
customer.contactDetails.emailAddress	Email address of the customer
customer.contactDetails.phoneNumber	Phone number of the customer
Billing address
customer.billingAddress.street	Street name
customer.billingAddress.zip	Zip code
customer.billingAddress.city	City
customer.billingAddress.countryCode	ISO 3166-1 alpha-2 country code
Information about customer's device
paymentMethodSpecificInput.customerDevice.ipAddress	The IP address of the customer
paymentMethodSpecificInput.customerDevice.deviceToken	Tokenized representation of the customer's device (details see below)
Shopping cart
shoppingCart.items.invoiceData.description	Shopping cart item description. The description will also be displayed in the portal as the product name.
shoppingCart.items.orderLineDetails.productCode	Product Code
shoppingCart.items.orderLineDetails.productPrice	The price of one unit of the product
shoppingCart.items.orderLineDetails.quantity	Quantity of the units being purchased
shoppingCart.items.orderLineDetails.productType	Enum to classify items that are purchased GOODS - Goods SHIPMENT - Shipping charges HANDLING_FEE - Handling fee DISCOUNT - Voucher / discount

Device fingerprinting token

In order to detect and prevent fraud at an early stage for the secured payment methods, a device fingerprinting snippet has to be integrated during the checkout process. This snippet will generate a token in the format <partner_id>_<merchant_id>_<session_id>, which has to be sent via the API parameter paymentMethodSpecificInput.customerDevice.deviceToken.

Example Fingerprinting Code in Java

<div>
<?php
  $environment = "t"; // "t" for TEST, "p" for PROD
  $payla_partner_id = "e7yeryF2of8X";
  $partner_merchant_id = "test-1"; // REPLACE individually per Merchant by Payone Merchant-ID
  $snippet_token = $payla_partner_id . "_" . $partner_merchant_id . "_" . guidv4(); // REPLACE guidv4() by a session_id (which should be unique per checkout experience) or an appropriate GUIDv4 function
?>

<script id="paylaDcs" type="text/javascript" src="https://d.payla.io/dcs/<?php echo $payla_partner_id; ?>/<?php echo $partner_merchant_id; ?>/dcs.js"></script>
<script>
  var paylaDcsT = paylaDcs.init("<?php echo $environment; ?>", "<?php echo $snippet_token; ?>");
</script>

<link id="paylaDcsCss" type="text/css" rel="stylesheet"
href="https://d.payla.io/dcs/dcs.css?st=<?php echo $snippet_token; ?>
&pi=<?php echo $payla_partner_id; ?>
&psi=<?php echo $partner_merchant_id; ?>&e=<?php echo $environment; ?>">

</div>

Snippet parameter explained:

Parameter	Description	Content
environment	Defines which environment the snippet is called for. During integration, t has to be used to point towards our test environment. Once the integration is finished and for every live processing merchant p has to be used to point towards our production environment.	Set "t" for Test and "p" for Production
payla_partner_id	12-digit alphanumeric Identifier provided by Payla. It is fixed. The once assigned ID will not change and is identical for test and production environment.	Set "e7yeryF2of8X"
partner_merchant_id	Identifier chosen and provided by PAYONE. It identifies the merchant and allows Payla to distinguish which merchant/shop the fingerprinting is done for. The ID is requested as part of Payla's onboarding. For testing without having a Merchant-ID, you can use "test-1"	Set your PAYONE Merchant-ID
snippet_token	For Payla, the most important requirement is the snippet - token being unique per API call. If a consumer calls the snippet multiple times during the checkout process but is in the same session, this token can be used. Once an actual order or risk check has been performed with the snippet_token, Payla expects a new snippet_token for a new API call. The main reason for this is customers switching devices between orders.	e.g. xyz123abc456_test-1_randomOrSessionadh9029381923

Mandatory checkout implementation

Terms of payment and data protection information must be implemented in the relevant language in the checkout for regulatory reasons.

Checkout note:

Language	Text
German	Mit Abschluss dieser Bestellung erkläre ich mich mit den ergänzenden Zahlungsbedingungen (Link) und der Durchführung einer Risikoprüfung für die ausgewählte Zahlungsart einverstanden. Den ergänzenden Datenschutzhinweis (Link) habe ich zur Kenntnis genommen.
English	By placing this order, I agree to the supplementary payment terms (link) and the performance of a risk assessment for the selected payment method. I am aware of the supplementary data protection notice (link).

Links:

Document	Language	Description	URL
Terms of payment	German	Framework for the use of the mentioned payment methods	https://legal.paylater.payone.com/de/terms-of-payment.html
Data protection notice	German	Describes, among other things, the use of the personal data	https://legal.paylater.payone.com/de/data-protection-payments.html
Terms of payment	English	Framework for the use of the mentioned payment methods	https://legal.paylater.payone.com/en/terms-of-payment.html
Data protection notice	English	Describes, among other things, the use of the personal data	https://legal.paylater.payone.com/en/data-protection-payments.html

Specific Parameters for PAYONE Secured Installment Payments

PAYONE Secured Installment requires a two-step approach for a successful payment:

With the initial order request the available installment options will be returned in the response (Note: no personal data of your customer will be provided to the external BNPL provider in this step)
With the complete-order request the selected installment option has to be provided to finalize the order and to request the guarantee

Structure of financingPaymentMethodSpecificInput for order request:

Parameter	Description
paymentProductId	3391

Structure of financingPaymentMethodSpecificInput for complete-order request:

Parameter	Description
paymentProductId	3391
requiresApproval	boolean true = the payment requires approval before the funds will be captured using the Approve payment or Capture payment API false = the payment does not require approval, and the funds will be captured automatically
paymentProduct3391SpecificInput.installmentOptionId	ID of the selected installment option
paymentProduct3391SpecificInput.bankAccountInformation.iban	IBAN of the customer's bank account.
paymentProduct3391SpecificInput.bankAccountInformation.accountHolder	Account holder of the bank account with the given IBAN. Does not necessarily have to be the customer (e.g. joint accounts).

Example

Simple example for a PAYONE Secured Installment payment via Commerce Platform:

Creating a Checkout (in the example in one step, the creation is also possible in multiple steps)
Creating an Order for the entire checkout (partial orders are also possible)
The response will contain the available installment options
Complete the order with the selected installment option
Create a Deliver to capture of order amount (partial deliver also possible)