PAYONE Documentation Platform | PAYONE Secured Invoice

Payone Secured invoice

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	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 expect 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 Invoice

Structure of financingPaymentMethodSpecificInput:

Parameter	Description
paymentProductId	3390
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

Parameter

Description

paymentProductId

3390

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

Example

Simple example for a PAYONE Secured Direct Debit 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)
Create a Deliver to capture of order amount (partial deliver also possible)

Process flow

Create CommerceCase with Checkout

Creating a CommerceCase with the initial Checkout including reference, information about the customer and the items in the shopping cart.

POST Commerce Case

Request
/v1/{merchantId}/commerce-cases

{
    "merchantReference": "commerce-case-bnpl-2",
    "customer": {
        "billingAddress": {
            "city": "Musterstadt",
            "countryCode": "DE",
            "houseNumber": "1",
            "street": "Musterstraße",
            "zip": "12345"
        },
        "merchantCustomerId": "Kunde2345",
        "contactDetails": {
            "emailAddress": "max@mustermann.de",
            "phoneNumber": "+1234567890"
        },
        "businessRelation": "B2C",
        "personalInformation": {
            "dateOfBirth": "19800101",
            "gender": "MALE",
            "name": {
                "firstName": "Max",
                "surname": "Mustermann"
            }
        }
    },
    "checkout": {
        "references": {
            "merchantReference": "bnpl-002"
        },
        "shoppingCart": {
            "items": [
                {
                    "invoiceData": {
                        "description": "bnpl boots"
                    },
                    "orderLineDetails": {
                        "productCode": "BNPL2",
                        "productPrice": 1599,
                        "productType": "GOODS",
                        "quantity": 6,
                        "taxAmount": 19
                    }
                }
            ]
        }
    }
}

Response

{
    "commerceCaseId": "10cb61dd-a80c-460d-8ec3-cdd8ffcaa010",
    "checkoutId": "d6d0552c-b82f-43d7-992a-1bfd5a265fa7",
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "bnpl boots"
                },
                "orderLineDetails": {
                    "id": "9c81fae8-a71e-42a7-bff3-59a75df814a5",
                    "productCode": "BNPL2",
                    "productPrice": 1599,
                    "productType": "GOODS",
                    "quantity": 6,
                    "taxAmount": 19
                }
            }
        ]
    }
}

Order with PAYONE Secured Invoice payment

Creating an order for the complete checkout with data for a PAYONE Secured Invoice payment.

POST Order

Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/order

{{
    "orderType": "FULL",
    "orderReferences": {
        "descriptor": "secured invoice payment",
        "merchantReference": "Order-5234533255"
    },
    "paymentMethodSpecificInput": {
        "financingPaymentMethodSpecificInput": {
            "paymentProductId": 3390,
            "requiresApproval": true
        },
        "customerDevice": {
            "ipAddress": "192.158.1.38",
            "deviceToken": "abcdefghijklmn123456789 (your customer device token)"
        },
        "paymentChannel": "ECOMMERCE"
    }
}

Response

{
    "createPaymentResponse": {
        "payment": {
            "paymentOutput": {
                "amountOfMoney": {
                    "amount": 9594,
                    "currencyCode": "EUR"
                },
                "references": {
                    "merchantReference": "Order-5234533255"
                },
                "paymentMethod": "financing",
                "financingPaymentMethodSpecificOutput": {
                    "paymentProductId": 3390
                }
            },
            "status": "PENDING_CAPTURE",
            "statusOutput": {
                "isCancellable": true,
                "statusCategory": "PENDING_MERCHANT",
                "isAuthorized": true,
                "isRefundable": false
            },
            "id": "PP2AAD9DL0PNNEH2"
        }
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "bnpl boots"
                },
                "orderLineDetails": {
                    "id": "9c81fae8-a71e-42a7-bff3-59a75df814a5",
                    "productCode": "BNPL2",
                    "productPrice": 1599,
                    "productType": "GOODS",
                    "quantity": 6,
                    "taxAmount": 19
                }
            }
        ]
    }
}

Webhook after successful confirmation of the Order (guarantee granted)

You can identify the corresponding transaction by the field createPaymentResponse.payment.id in the order response. The status PENDING_CAPTURE shows that the amount is authorized and the payment gateway is waiting for a capture.

Webhook

{
    "apiVersion": "v1",
    "created": "2023-11-23T16:38:52.350354576+00:00",
    "id": "91e344df-fcd5-4f48-9167-728e2202a991",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 9594,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-5234533255"
            },
            "financingPaymentMethodSpecificOutput": {
                "paymentProductId": 3390
            },
            "paymentMethod": "financing"
        },
        "status": "PENDING_CAPTURE",
        "statusOutput": {
            "isCancellable": true,
            "statusCategory": "PENDING_MERCHANT",
            "isAuthorized": true,
            "isRefundable": false
        },
        "id": "PP2AAD9DL0PNNEH2"
    },
    "type": "payment.pending_capture"
}

Delivery

Full Deliver to capture the complete order amount.

POST Deliver

Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/deliver

{
    "deliverType": "FULL",
    "isFinal": true
}

Response

{
    "capturePaymentResponse": {
        "captureOutput": {
            "amountOfMoney": {
                "amount": 9594,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-5234533255"
            },
            "paymentMethod": "redirect"
        },
        "status": "CAPTURED",
        "id": "PP2AAD9DL0PNNEH2"
    },
     "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "bnpl boots"
                },
                "orderLineDetails": {
                    "id": "9c81fae8-a71e-42a7-bff3-59a75df814a5",
                    "productCode": "BNPL1",
                    "productPrice": 1599,
                    "productType": "GOODS",
                    "quantity": 2,
                    "taxAmount": 19
                }
            }
        ]
    }
}

Webhook after successful Deliver

The payment gateway informs you via webhook about the successful capture.

Webhook

{
    "apiVersion": "v1",  "created": "2023-11-23T16:39:31.353454576+00:00",
    "id": "74e4fe0e-ee75-4c02-9b80-a3e3df8140d4",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 9594,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-5234533255"
            },

            "financingPaymentMethodSpecificOutput": {
                "paymentProductId": 3390
            },
            "paymentMethod": "financing"
        },
        "status": "CAPTURED",
        "statusOutput": {
            "isCancellable": false,
            "statusCategory": "COMPLETED",
            "isAuthorized": true,
            "isRefundable": true
        },
        "id": "PP2AAD9DL0PNNEH2"
    },
    "type": "payment.captured"
}