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

  1. Snippet for device fingerprinting token
  2. Mandatory checkout information
  3. 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)

Process flow