Payone secured direct debit

---end

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

---end

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

---end

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.

---end

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>

---end

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

---end

Mandatory checkout implementation

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

---end

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).

---end

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

---end

Specific parameters for PAYONE Secured Direct Debit Payments

Structure of financingPaymentMethodSpecificInput:

Parameter Description

paymentProductId

3392

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

paymentProduct3392SpecificInput.bankAccountInformation.iban

IBAN of the end customer's bank account.

paymentProduct3392SpecificInput.bankAccountInformation.accountHolder

Account holder of the bank account with the given IBAN. Does not necessarily have to be the end customer (e.g. joint accounts).

---end

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

---end

Request
/v1/{merchantId}/commerce-cases
    "merchantReference": "commerce-case-bnpl-1",
    "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-001"
        },
        "shoppingCart": {
            "items": [
                {
                    "invoiceData": {
                        "description": "bnpl shirt"
                    },
                    "orderLineDetails": {
                        "productCode": "BNPL1",
                        "productPrice": 1999,
                        "productType": "GOODS",
                        "quantity": 2,
                        "taxAmount": 19
                    }
                }
            ]
        }
    }
}

---end

Response
{
    "commerceCaseId": "1167479f-cea0-460f-8992-5c31c573f9bc",
    "checkoutId": "fcc5ac2e-507e-4de8-95e8-fe37fb225d76",
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "bnpl shirt"
                },
                "orderLineDetails": {
                    "id": "d83c868c-4cee-4409-8226-4ff58fdd8491",
                    "productCode": "BNPL1",
                    "productPrice": 1999,
                    "productType": "GOODS",
                    "quantity": 2,
                    "taxAmount": 19
                }
            }
        ]
    }
}

---end

Order with PAYONE Secured Direct Debit payment

Creating an order for the entire checkout with data for a PAYONE Secured Direct Debit payment. 

POST Order

---end

Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/order
{
    "orderType": "FULL",
    "orderReferences": {
        "descriptor": "secured direct debit payment",
        "merchantReference": "Order-5234533251"
    },
    "paymentMethodSpecificInput": {
        "financingPaymentMethodSpecificInput": {
            "paymentProductId": 3392,
            "requiresApproval": true,
            "paymentProduct3392SpecificInput": {
                "bankAccountInformation": {
                    "iban": "DE02370502990000684712",
                    "accountHolder": "Max Mustermann"
                }
            }
        },
        "customerDevice": {
            "ipAddress": "192.158.1.38",
            "deviceToken": "abcdefghijklmn123456789 (your customer device token)"
        },
        "paymentChannel": "ECOMMERCE"
    }
}

---end

Response
{
    "createPaymentResponse": {
        "payment": {
            "paymentOutput": {
                "amountOfMoney": {
                    "amount": 3998,
                    "currencyCode": "EUR"
                },
                "references": {
                    "merchantReference": "Order-5234533247"
                },
                "paymentMethod": "financing",
                "financingPaymentMethodSpecificOutput": {
                    "paymentProductId": 3392
                }
            },
            "status": "PENDING_CAPTURE",
            "statusOutput": {
                "isCancellable": true,
                "statusCategory": "PENDING_MERCHANT",
                "isAuthorized": true,
                "isRefundable": false
            },
            "id": "PP2AAD9DU1WE2PFQ"
        }
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "bnpl shirt"
                },
                "orderLineDetails": {
                    "id": "d83c868c-4cee-4409-8226-4ff58fdd8491",
                    "productCode": "BNPL1",
                    "productPrice": 1999,
                    "productType": "GOODS",
                    "quantity": 2,
                    "taxAmount": 19
                }
            }
        ]
    }
}

---end

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.

---end

Webhook
{
    "apiVersion": "v1",
    "created": "2023-11-23T13:19:17.956149901+00:00",
    "id": "a129e0d9-f743-47bb-b7ad-c7d5f4d7c2fe",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 3998,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-5234533247"
            },
            "financingPaymentMethodSpecificOutput": {
                "paymentProductId": 3392
            },
            "paymentMethod": "financing"
        },
        "status": "PENDING_CAPTURE",
        "statusOutput": {
            "isCancellable": true,
            "statusCategory": "PENDING_MERCHANT",
            "isAuthorized": true,
            "isRefundable": false
        },
        "id": "PP2AAD9DU1WE2PFQ"
    },
    "type": "payment.pending_capture"
}

---end

Deliver

Full Deliver to capture the complete order amount.

POST Deliver

---end

Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/deliver
{
    "deliverType": "FULL",
    "isFinal": true
}

---end

Response
{
    "capturePaymentResponse": {
        "captureOutput": {
            "amountOfMoney": {
                "amount": 3998,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-5234533247"
            },
            "paymentMethod": "redirect"
        },
        "status": "CAPTURED",
        "id": "PP2AAD9DU1WE2PFQ"
    },
     "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "bnpl shirt"
                },
                "orderLineDetails": {
                    "id": "d83c868c-4cee-4409-8226-4ff58fdd8491",
                    "productCode": "BNPL1",
                    "productPrice": 1999,
                    "productType": "GOODS",
                    "quantity": 2,
                    "taxAmount": 19
                }
            }
        ]
    }
}

---end

Webhook after successful Deliver

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

---end

Webhook
{
    "apiVersion": "v1",  "created": "2023-11-23T13:19:59.856149901+00:00",
    "id": "74e4fe0e-ee75-4c02-9b80-a3e3df8140d4",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 3998,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-5234533247"
            },

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

---end