Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Introduction

With Payment Service Directive 2 (PSD2) it's required that all credit card payments have to be authenticated by the customer using strong customer authentication (SCA). See 3-D Secure.

Of course, this is only possible if the end customer is also present at the time of payment and can carry out an SCA (like 3-D Secure 1.0 or 3-D Secure 2.x).

This is precisely not the case with subscription models and micropayments (virtual account / billing), since these are carried out in the absence of the customer. For this purpose, the model "cards on file" or "credentials on file" (CoF for in short) is offered, with which such payments are specially marked and then excluded from the SCA. Likewise, the first, initial payment must be authenticated using SCA to meet the PSD2 guidelines. Subsequent payment transactions can be initiated with reference to the initial payment transaction. The reference to the initial transaction will then be handled by the PAYONE platform.

CoF can also be used to speed checkout by first depositing a credit card for a customer and then referencing it for follow-up payments. This function has already been offered for a long time by the pseudo card number of the PAYONE Platform - but now CoF also makes it PSD2-compliant.

With CoF you may re-use a credit card number for recurring transactions where the customer can not proceed to the SCA process. To do so the first initial payment process has to be authenticated via SCA and the customer has to be informed that his their credit card number will be stored for subsequent payments, the purpose of payment and the amount that is expected. the CoF consent token will be stored referencing to the combination of merchantid (MID) and creditcardnumber (PPAN).

UI Text Box
typeinfo

All online merchants who initiate recurring transactions in the form of CoF payments and have their customers' card data stored by themselves or their PSP storing the data must obtain the explicit consent of the cardholder / customer. This approval must include the following elements:

  • The confirmation of the stored card number (PCI compliant, e.g., as a masked card number indicating the last four digits of the card number)
  • The purpose for which the card data is used and the duration of the agreement
  • Confirmation from the merchant that the cardholder will be notified of any changes in an agreed way

CoF and PAYONE Platform

With the support for CoF Payments we want to make the transition for our merchants as smooth as possible. To do this, we need to take care of the many different implementation ways our merchants are using today. We decided to deliver the CoF integration in different steps.

The first steps will be based on the already known parameters recurrence und customer_is_present. With this parameters, the merchant is able to set the use-case that needs to be processed.

After this step, we take care of our current integrations. We want to make sure , that integrations based on ecommercemode=internet will still work in the beginning of 2021. With this step the merchants are able to plan the implementation of recurrence and customer_is_present while still being able to process with ecommercemode=internet.

For every transaction with ecommercemode=internet, we will internally set recurrence=recurring and customer_is_present=no, to flag that transaction as a subsequent recurring transaction.

The last step will be a more detailed way of integrating the CoF use cases. That will give our merchants every possible way of setting up exact recurring cycles and define for themselves, if a transaction is an initial transaction or not. We will deliver new parameters, that the merchant can use for a more detailed definition of CoF use cases. For this last step we already made some preparations in our api and you can take a closer look on the parameters, but the functionality in the PAYONE Platform is not finished yet.

So if you want to update your integration right now, you're fine with using the parameters recurrence and customer_is_present. An updated documentation with more details to the upcoming extensions will be coming soon.

While the solution for our merchants with ecommercemode=internet is based on our internal interpretation of recurrence and customer_is_present, this documentation will describe the definition of the use cases and how to set the 2 parameters.

Using recurrence and customer_is_present for CoF use cases

The PAYONE Platform already supports parameters for:

These parameters will be used for credit card payments to indicate CoF payments.

Here's an overview of different use cases with credit card payments and recurring transactions.

Initial transaction, followed by recurring payment

Description: The customer wants to save his their credit card for future payments. the first initial transaction will be handled with 3d3-secureD Secure. The following transactions will be without 3d3-secureD Secure.

How it should be done
StepUse caseServer-API requestParams Parameters to setComments
1a

a) Get customer agreement for CoF - only get agreement, amount is sent with 1.

preauthorization
  • amount=1
  • recurrence=recurring
  • customer_is_present=yes
  • In this case, the amount that will be authorized later is not known yet.
  • Merchant must obtain consent that data will be stored and be used for subsequent payments
  • Customer has to agree to CoF
  • Initial payment will be handled with 3-D secure
1b

b) OR get customer agreement for CoF - with amount is sent

preauthorization/authorization
  • amount=<amount>
  • recurrence=recurring
  • customer_is_present=yes
  • Merchant must obtain consent that data will be stored and be used for subsequent payments
  • Customer has to agree to CoF
  • Initial payment will be handled with 3-D secure

Amount has to be captured by request "capture" if preauthorization is used.

2

Subsequent payments

preauthorization/authorization
  • amount=<amount>
  • recurrence=recurring
  • customer_is_present=noSubsequential payment
  • userid or pseudocardpan
  • Subsequent payments will be handled with CoF if customer agreed to the initial payment process

Amount has to be captured by request "capture" . Amount has to be captured by request "capture" if if preauthorization is used.

How it's done now

Payment transaction trail period

authorization
  • So by default these payment transactions may be enforced to be challanged by 3-D Secure

Payment transaction subsequent period

authorization
  • Subsequential payments may be declined by the issuer as they can not be authenticated by the customer



mid=
UI Expand
titleSample Initial Request
Code Block
titleInitial Request
UI Expand
titleSample Initial Request


Code Block
titleInitial Request
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=preauthorization
recurrence=recurring
customer_is_present=yes
encoding=UTF-8
aid=12345 (your aid)
clearingtype=cc
cardtype=M
cardexpiredate=2110
pseudocardpan=9911192220202920292
cardholder=Testperson Approved
amount=3000 (or 1 for initial authentication, without knowing the recurring amount)
currency=EUR
lastname=Approved
firstname=Testperson
salutation=Herr
country=DE
language=de
gender=m
birthday=19600707
street=Hellersbergstraße 14
city=Musterstadt
zip=12345
email=youremail@email.com
telephonenumber=01512345678



UI Expand
titleSample Subsequent Request


Code Block
titleInitial Request
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=preauthorization
recurrence=recurring
customer_is_present=no
encoding=UTF-8
aid=12345 (your aid)
clearingtype=cc
cardtype=M
cardexpiredate=2110
pseudocardpan=9911192220202920292
cardholder=Testperson Approved
amount=3000
currency=EUR
lastname=Approved
firstname=Testperson
salutation=Herr
country=DE
language=de
gender=m
birthday=19600707
street=Hellersbergstraße 14
city=Musterstadt
zip=12345
email=youremail@email.com
telephonenumber=01512345678


Subscription / contract / abo (recurring) - PAYONE contract module

Description: This use case applies if you want to use our Contract module to handle subscriptions where the amount for a trail period and subsequential periods are fixed and known when starting the contract.

Code Block
titleInitial Request
mid=23456 (your mid) portalid=12345123 (your portalid) key=abcdefghijklmn123456789 (your key) api_version=3.10 mode=test (set to „live“ for live-requests) request=preauthorization recurrence=recurring customer_is_present=yes encoding=UTF-8 aid=12345 (your aid) clearingtype=cc cardtype=M cardexpiredate=2110 pseudocardpan=9911192220202920292 cardholder=Testperson Approved amount=3000 (or 1 for initial authentication, without knowing the recurring amount) currency=EUR lastname=Approved firstname=Testperson salutation=Herr country=DE language=de gender=m birthday=19600707 street=Hellersbergstraße 14 city=Musterstadt zip=12345 email=youremail@email.com telephonenumber=01512345678
StepUse caseServer-API requestParams to setComments
How it should be done1a

a) Get customer agreement for CoF - only get agreement, amount=1 is sent

preauthorization
  • amount=1 (question) Hier muss dann auch amount=1 sein, korrekt?
  • recurrence=recurring
  • customer_is_present=yes
    1

    Initial create access - customer is present

    createaccess
    • customer_is_present=yes
    • Success-URL
    • Back-URL
    • Optional: Error-URL
    • Merchant must obtain consent that data will be stored and be used for subsequent payments
    • Customer has to agree to CoF
    • Initial payment will be handled with 3-D secure
    1b

    b) OR get customer agreement for CoF -with amount is sent

    preauthorization
    • amount=<amount>
    • recurrence=recurring
    • customer_is_present=yes
    • Merchant must obtain consent that data will be stored and be used for subsequent payments
    • Customer has to agree to CoF
    • Initial payment will be handled with 3-D secure

    Amount has to be captured by request "capture".

    2a

    Initial create access - customer is present

    createaccess
    • recurrence=recurring
    • customer_is_present=no
    • As the customer already agreed for initial payment the access can simply be started
    • Parameter "customer_is_present=no" even if customer is present because customer agreement is already processed.
    2b

    Initial create access - customer is not present

    createaccess
    • recurrence=recurring
    • customer_is_present=no
    • As the customer already agreed for initial payment the access can simply be started
    3

    Subsequent payments

    handled automatically
    • Subsequential payment will be handled with CoF if customer agreed to the initial create access
    How it's done now

    Initial create access, no extra params given

    3dscheck &
    createaccess
    • The default value
      • for "recurrence" is "recurring" and
      • for "customer_is_present" is "yes". 
    • So by default these payment transactions may be enforced to be challanged by 3-D Secure

    Subsequent payments

    handled automatically
    • Subsequential payments may be declined by the issuer as they can not be authenticated by the customer
    UI Expand
    titleSample Initial Request
    • Important: If Success- and Back-URL are not provided in the request, 3-D secure will not be triggered and issuers might respond with a soft-decline (error 120)
    2

    Subsequent payments

    handled automatically
    • Subsequent payments will be handled with CoF if customer agreed to the initial create access


    UI Expand
    titleSample Subsequent Initial Createaccess


    Code Block
    titleSubsequent Initial Request
    mid=23456 (your mid)
    portalid=12345123 (your portalid)
    key=abcdefghijklmn123456789 (your key)
    api_version=3.10
    access_starttime=1608685709
    customerid=1234567
    mode=test (set to „live“ for live-requests)
    request=createaccess
    recurrence=recurring
    customer_is_present=no=yes
    successurl=https://example.com/success
    errorurl=https://example.com/error
    backurl=https://example.com/back
    encoding=UTF-8
    aid=12345 (your aid)
    clearingtype=cc
    cardtype=M
    cardexpiredate=2110
    pseudocardpan=9911192220202920292
    cardholder=Testperson Approved
    amount=3000
    currency=EUR
    lastname=Approved
    firstname=Testperson
    salutation=Herr
    country=DE
    language=de
    gender=m
    birthday=19600707
    street=Hellersbergstraße 14
    city=Musterstadt
    zip=12345
    email=youremail@email.com
    telephonenumber=01512345678
    


    Micropayment / Billing / vauthorization (recurring)

    Description: This use case applies if you want to use our Billing module for micro payments. The accumulated amount is then settled after a given period of time. Typically the amounts per settlement period are different.

    Create micropayment handled automatically
    StepUse caseServer-API requestParams to setCommentsHow it should be done
    1a

    a) Get customer agreement for CoF - only get agreement, amount=1 is sent

    preauthorization
    • amount=1 (question) 1 Cent , korrekt?
    • recurrence=recurring or recurrence=oneclick
    • customer_is_present=yes
    • Merchant must obtain consent that data will be stored and be used for subsequent payments
    • Customer has to agree to CoF
    • Initial payment will be handled with 3-D secure
    1b

    b) OR get customer agreement for CoF - with amount is sent

    preauthorization
    • amount=<amount>
    • recurrence=recurring or recurrence=oneclick
    • customer_is_present=yes
    • Merchant must obtain consent that data will be stored and be used for subsequent payments
    • Customer has to agree to CoF
    • Initial payment will be handled with 3-D secure

    Amount has to be captured by request "capture".

    2

    Create micropayment transactions

    vauthorization
    • recurrence=recurring or recurrence=oneclick
    • customer_is_present=no
    • userid or pseudocardpan
    • set recurring or oneclick depending on the recurrence value you set in the initial transaction
    3Settlement of micropayment transactionshandled automatically
    • Settlement of the open amount marked as CoF transactions
    How it's done now
    • transactions
    vauthorizationSettlement of micropayment transactions
    • Payments may be declined by the issuer


    UI Expand
    titleSample Initial Request


    Code Block
    titleInitial Request
    mid=23456 (your mid)
    portalid=12345123 (your portalid)
    key=abcdefghijklmn123456789 (your key)
    api_version=3.10
    mode=test (set to „live“ for live-requests)
    request=preauthorization
    recurrence=recurring
    customer_is_present=yes
    encoding=UTF-8
    aid=12345 (your aid)
    clearingtype=cc
    cardtype=M
    cardexpiredate=2110
    pseudocardpan=9911192220202920292
    cardholder=Testperson Approved
    amount=3000 (or 1 for initial authentication, without knowing the recurring amount)
    currency=EUR
    lastname=Approved
    firstname=Testperson
    salutation=Herr
    country=DE
    language=de
    gender=m
    birthday=19600707
    street=Hellersbergstraße 14
    city=Musterstadt
    zip=12345
    email=youremail@email.com
    telephonenumber=01512345678
    



    UI Expand
    titleSample Subsequent VAuthorization


    Code Block
    titleSubsequent Request
    mid=23456 (your mid)
    portalid=12345123 (your portalid)
    key=abcdefghijklmn123456789 (your key)
    api_version=3.10
    vreference=merchantreference
    vaccountname=newaccount
    settle_period_length=1
    settle_period_unit=M
    customerid=1234567
    mode=test (set to „live“ for live-requests)
    request=vauthorization
    recurrence=recurring
    customer_is_present=no
    encoding=UTF-8
    aid=12345 (your aid)
    clearingtype=cc
    cardtype=M
    cardexpiredate=2110
    pseudocardpan=9911192220202920292
    cardholder=Testperson Approved
    amount=3000
    currency=EUR
    lastname=Approved
    firstname=Testperson
    salutation=Herr
    country=DE
    language=de
    gender=m
    birthday=19600707
    street=Hellersbergstraße 14
    city=Musterstadt
    zip=12345
    email=youremail@email.com
    telephonenumber=01512345678
    


    Reservation / Sale with "oneclick" using CoF (one-click)

    Description: This use case applies if you want to store a credit card and use it for the following transactions in order to process them without 3-D Secure. These transaction are always customer initiated, so SCA could apply. You should always send customer_is_present=yes. The issuer of course can decide to authenticate this transaction, without a challengeThis can help prevent challenges for returning customers, depending on issuer.

    Payment transactions may be enforced to be challenged by 3-D Secure
    StepUse caseServer-API requestParams to setCommentsHow it should be done
    1Initial transaction and get customer agreement for CoFpreauthorization
    authorization
    • recurrence=oneclick
    • customer_is_present=yes
    • Merchant must obtain consent that data will be stored and be used for subsequent payments
    • Customer has to agree to CoF
    • Initial payment will be handled with 3-D secure

    Amount has to be captured by request "capture" if only reserved with "preauthorization".

    2Subsequent transaction, customer is present

    preauthorization
    authorization

    • recurrence=oneclick
    • customer_is_present=yes
    • userid or pseudocardpan
    • Customer selects and confirms stored credit card data
    • 3-D Secure may not be required
    • Subsequential payment will be handled with CoF

    Amount has to be captured by request "capture" if only reserved with "preauthorization".

    How it's done nowInitial transaction

    preauthorization
    authorization

    • Payment transactions may be enforced to be challenged by 3-D Secure
    Subsequent transaction

    preauthorization
    authorization


    UI Expand
    titleSample Initial Request


    Code Block
    titleInitial Request
    mid=23456 (your mid)
    portalid=12345123 (your portalid)
    key=abcdefghijklmn123456789 (your key)
    api_version=3.10
    mode=test (set to „live“ for live-requests)
    request=preauthorization
    recurrence=oneclick
    customer_is_present=yes
    encoding=UTF-8
    aid=12345 (your aid)
    clearingtype=cc
    cardtype=M
    cardexpiredate=2110
    pseudocardpan=9911192220202920292
    cardholder=Testperson Approved
    amount=3000
    currency=EUR
    lastname=Approved
    firstname=Testperson
    salutation=Herr
    country=DE
    language=de
    gender=m
    birthday=19600707
    street=Hellersbergstraße 14
    city=Musterstadt
    zip=12345
    email=youremail@email.com
    telephonenumber=01512345678
    



    UI Expand
    titleSample Subsequent Oneclick


    Code Block
    titleSubsequent Request
    mid=23456 (your mid)
    portalid=12345123 (your portalid)
    key=abcdefghijklmn123456789 (your key)
    api_version=3.10
    customerid=1234567
    mode=test (set to „live“ for live-requests)
    request=authorization
    recurrence=oneclick
    customer_is_present=yes
    encoding=UTF-8
    aid=12345 (your aid)
    clearingtype=cc
    cardtype=M
    cardexpiredate=2110
    pseudocardpan=9911192220202920292
    cardholder=Testperson Approved
    amount=3000
    currency=EUR
    lastname=Approved
    firstname=Testperson
    salutation=Herr
    country=DE
    language=de
    gender=m
    birthday=19600707
    street=Hellersbergstraße 14
    city=Musterstadt
    zip=12345
    email=youremail@email.com
    telephonenumber=01512345678
    



    Table of Contents