Versions Compared

Old Version 10

changes.mady.by.user Peter Posse

Saved on

compared with

New Version Current

changes.mady.by.user Admin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space ENWORK and version Documentation

Introduction

Acquirers and connection

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
support supports many different credit card connections to various acquirers / processors with different protocols.

...

Additional features (e.g. AVS (Address Verification Service), refund, 3-D Secure, ...) may depend on the specific integration and acquirer.

Integration with 
Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording

In general we offer two different ways of integration:

...

  • integration via payment page (payment form)
    • with common parameters to integrate
      Multiexcerpt include
      SpaceWithExcerptEN
      MultiExcerptNamePlatform-Name
      PageWithExcerptWording
      payment form
    • with parameters to customize the payment form
    • with specific parameters for the desired acquirer / processor
  • integration via Server-2-Server (direct) integration
    • with common parameters to integrate
      Multiexcerpt include
      SpaceWithExcerptEN
      MultiExcerptNamePlatform-Name
      PageWithExcerptWording
      payment form
    • with specific parameters for the desired acquirer / processor

Implementation of 3-D Secure (2.x)

Common notes to 3-D Secure

3-D Secure is a process that authenticates the card holder to ensure that the consumer using the credit card data really is the card holder.

...

  • enable strong customer authentication (SCA) by authenticate the card holder with 2 independent factors of these 3 factors:
    • something the card holder knows, e.g. a password
    • something the card holder owns, e.g. a device (like phone to receive a token via SMS or using other OTP, token generator, ...)
    • something the card holder is, e.g. biometrics (like finger print, face-id, ...)
  • enable seemless authentication where the consumer is not authenticated and not asked to authenticate himself.

3-D Secure with
Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording

Prepare yourself / your integration to be 3-D Secure 2.x ready - here a short overview with some technical details.


3-D Secure 1.x3-D Secure 2.x3-D Secure 2.x Sample
Depend on your integration: Payment Form ./. Server-2-Server
Payment Page / Payment Form

Your existing integration.

Just add API parameter "MsgVer=2.0", the rest is handled automatically by 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording

Add parameter "MsgVer=2.0" to your existing API call to start Payment Form.
URL-processingURLFailure and URLSuccess work with http-GETURLFailure and URLSuccess work with http-POST (due to amount of data). So pls. prepare to handle both (GET + POST)

Server-2-Server integration

Use KVP:

CCNrCredit card number (PAN)
CCExpiryExpiry date of the credit card
CCCVCCard verification number
CCBrandCredit card brand.

Use "card"-JSON to provide card data to API



e.g.:

Code Block
languagexml
{
    "securityCode": "569",
    "expiryDate": "202508",
    "cardholderName": "William Thomas",
    "number": "4111111111111111",
    "brand": "VISA"
}

card=ewogICAgInNlY3VyaXR5Q29kZSI6ICI1NjkiLAogICAgImV4cGlyeURhdGUiOiAiMjAyNTA4IiwKICAgICJjYXJkaG9sZGVyTmFtZSI6ICJXaWxsaWFtIFRob21hcyIsCiAgICAibnVtYmVyIjogIjQxMTExMTExMTExMTExMTEiLAogICAgImJyYW5kIjogIlZJU0EiCn0=

For specific use cases, find other use cases here: 3DS 2.0 Merchant Use-Cases
Use case3-D Secure 1.x3-D Secure 2.x3-D Secure 2.x Sample
Recurring payments (initial)

Use parameter "RTF=I"

you may receive TransactionID as Card scheme specific transaction ID

Change "RTF" to parameter "credentialOnFile"-JSON with "recurring" and "initial=true"

you may receive schemeReferenceID as Card scheme specific transaction ID

e.g.:

Code Block
languagejsonxml
titleRecurring with initial=true
collapsetrue
{
    "type": {
        "recurring": {
            "recurringFrequency": 30,
            "recurringStartDate": "2021-09-14",
            "recurringExpiryDate": "2022-09-14"
        }
    },
    "initialPayment": true
}

The JSON needs to be base64-encoded and then used as value for parameter credentialOnFile (pls. be aware to use the full base64-encoded string, including "=" at the end)

credentialOnFile=ewogICAgInR5cGUiOiB7CiAgICAgICAgInJlY3VycmluZyI6IHsKICAgICAgICAgICAgInJlY3VycmluZ0ZyZXF1ZW5jeSI6IDMwLAogICAgICAgICAgICAicmVjdXJyaW5nU3RhcnREYXRlIjogIjIwMjEtMDktMTQiLAogICAgICAgICAgICAicmVjdXJyaW5nRXhwaXJ5RGF0ZSI6ICIyMDIyLTA5LTE0IgogICAgICAgIH0KICAgIH0sCiAgICAiaW5pdGlhbFBheW1lbnQiOiB0cnVlCn0=

Recurring payments (subsequent)

Use parameter "RTF=R"

and send TransactionID as Card scheme specific transaction ID

Change "RTF" to parameter "credentialOnFile"-JSON with "recurring" and "initial=false"

and send schemeReferenceID as Card scheme specific transaction ID

e.g.

Code Block
languagejsonxml
titleRecurring with initial=false
collapsetrue
{
    "type": {
        "recurring": {
            "recurringFrequency": 30,
            "recurringStartDate": "2021-09-14",
            "recurringExpiryDate": "2022-09-14"
        }
    },
    "initialPayment": false
}

After base64-encoding:

credentialOnFile=ewogICAgInR5cGUiOiB7CiAgICAgICAgInJlY3VycmluZyI6IHsKICAgICAgICAgICAgInJlY3VycmluZ0ZyZXF1ZW5jeSI6IDMwLAogICAgICAgICAgICAicmVjdXJyaW5nU3RhcnREYXRlIjogIjIwMjEtMDktMTQiLAogICAgICAgICAgICAicmVjdXJyaW5nRXhwaXJ5RGF0ZSI6ICIyMDIyLTA5LTE0IgogICAgICAgIH0KICAgIH0sCiAgICAiaW5pdGlhbFBheW1lbnQiOiBmYWxzZQp9

Customer Initiated (initial)

Use parameter "RTF=E"

you may receive TransactionID as Card scheme specific transaction ID

Change "RTF" to parameter "credentialOnFile"-JSON with "CIT" and "initial=true"

you may receive schemeReferenceID as Card scheme specific transaction ID

e.g.

Code Block
languagejsonxml
titleCIT (CustomerInitiated) with initial=true
collapsetrue
{
    "type": {
        "unscheduled": "CIT"
    },
    "initialPayment": true
}

After base64-encoding (again: don't miss "=" at the end; it has to be part of the value):

credentialOnFile=ewogICAgInR5cGUiOiB7CiAgICAgICAgInVuc2NoZWR1bGVkIjogIkNJVCIKICAgIH0sCiAgICAiaW5pdGlhbFBheW1lbnQiOiB0cnVlCn0=

Merchant Initiated (subsequent)

Use parameter "RTF=M"

and send TransactionID as Card scheme specific transaction ID

Change "RTF" to parameter "credentialOnFile"-JSON with "MIT" and "initial=false"

and send schemeReferenceID as Card scheme specific transaction ID

e.g.

Code Block
languagejsonxml
titleMIT (MerchantInitiated) with initial=false
collapsetrue
{
    "type": {
        "unscheduled": "MIT"
    },
    "initialPayment": false
}

After base64-encoding:

credentialOnFile=ewogICAgInR5cGUiOiB7CiAgICAgICAgInVuc2NoZWR1bGVkIjogIk1JVCIKICAgIH0sCiAgICAiaW5pdGlhbFBheW1lbnQiOiBmYWxzZQp9

Address Verification Service (AVS)

(depending on acquirer / processor)

Use parameter

  • AddrStreet
  • AddrStreetNr
  • AddrZip
  • AddrCity
  • ....
Change address data to "address"-JSON

e.g.

Code Block
languagejsonxml
titlePut address data into JSON structure
collapsetrue
{
    "city": "New York",
    "country": {
        "countryA3": "USA"
    },
    "addressLine1": {
        "street": "Park Avenue",
        "streetNumber": "270"
    },
    "postalCode": "10017-2070",
    "state": "NY"
}

billingAddress=ewogICAgImNpdHkiOiAiTmV3IFlvcmsiLAogICAgImNvdW50cnkiOiB7CiAgICAgICAgImNvdW50cnlBMyI6ICJVU0EiCiAgICB9LAogICAgImFkZHJlc3NMaW5lMSI6IHsKICAgICAgICAic3RyZWV0IjogIlBhcmsgQXZlbnVlIiwKICAgICAgICAic3RyZWV0TnVtYmVyIjogIjI3MCIKICAgIH0sCiAgICAicG9zdGFsQ29kZSI6ICIxMDAxNy0yMDcwIiwKICAgICJzdGF0ZSI6ICJOWSIKfQ==

Apply for frictionless payment processing
  • not supported with 3-D Secure 1.x
  • each payment will be authenticated

Provide additional data as JSON-KVP: JSON Objects

e.g.:

Code Block
languagejsonxml
titleExplicitly apply for customer challenge
collapsetrue
{
    "challengePreference ": "mandateChallenge"
}

After base64-encoding (again: don't miss "=" at the end; it has to be part of the value):

threeDSPolicy=ewogICAgImNoYWxsZW5nZVByZWZlcmVuY2UgIjogIm1hbmRhdGVDaGFsbGVuZ2UiCn0=

...