Payment with card details entering on the merchant side api avia

1. Basics
2. Operations

• 2.1 Order registration
• 2.2 Card data transfer - authorisation request
• 2.3 Authorisation request status check
• 2.4 3DS authentication of customer

3. References

• 3.1 3ds policy settings

1. Basics

The document contains technical description of credit card data transfer from Online Store (OS) system to payment gateway (PG) services with the aim to perform the authorisation of money - store-system-side card data input scheme, host-to-host two-calls functional of card data transfer.

Basic requirements: - basic API knowledge - certificate of PCI DSS SAQ D compliance

2. Operations

The following steps must be organised on the OS system side, to ensure the correct data exchange between OS and PG system.

1. web order registration in PG system - basic request, for ex. register request of orderv2 service. Extended description can be found in Basic API.
2. session retrieve from step 1;
3. card data collection and transfer in form of json request on the address, received on the step 2;
4. 3ds verification of cardholder;
5. card data transfer status retrieve;
6. web order status retrieve;

Note: the number of steps depends on chosen type of integration.

2.1 Order registration

To organise the input of credit card data inside the web-site of OS, OS has to register an order in PG system to receive the JSON authorisation web service address. The request must contain the identifier of chosen card data entry type. This identifier is value rest in Showcase parameter of order registration request.

Request example:

<soap-env:Envelope
    xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:Body>
        <register>
            <order>
                <shop_id>123</shop_id>
                <number>123456789</number>
            </order>
            <cost>
                <currency>RUB</currency>
                <amount>100</amount>
            </cost>
            <customer>
                <phone>+79859998877</phone>
                <name>Пупкин Вася</name>
                <email>vasya@mail.ru</email>
            </customer>
            <description>
                <timelimit>2016-04-23T10:42:00.000Z</timelimit>
            </description>
            <postdata>
                <PostEntry>
                    <name>Showcase</name>
                    <value>rest</value>
                </PostEntry>
            </postdata>
        </register>
    </soap-env:Body>
</soap-env:Envelope>

In case of successful request processing by PG, OS system will receive redirect_url and session - the JSON authorisation web service address (service_url = redirect_url + session). Session value is unique, and can be used only once.

Response example:

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:Body>
        <registerResponse>
            <retval>
                <session>6b221924756b46a4bdf323763900baaa</session>
                <paycode></paycode>
                <redirect_url>https://sandbox.egopay.ru/rest/v2/</redirect_url>
            </retval>
        </registerResponse>
    </soap-env:Body>
</soap-env:Envelope>

2.2 Card data transfer - authorisation request

After the card data is collected on the OS side, OS system transfers it for PG system.

Note: in case of store-system-side card data input scheme, it is assumed that the primary check of entered card data will be carried out by the OS system.

Primary check functional recommendations:

• entered PAN (Primary Account Number) check with Luhn algorithm;
• entered holder data should contains Latin letters;
• entered expiration date must not be expired;
• cvv/cvc2 code must not be longer then 3 or 4 digits.

Note: authorisation request send requires basic HTTP authorisation.

Request type: POST

Authorisation request parameters:

Online payment card request example:

{
    "ver": 2,
    "txns": [
        {
            "pan": "5100000000000008",
            "exp": "201512",
            "cvv": "222",
            "amt": 28500,
            "cy": "RUB",
            "holder": "Vasya Pupkin",
            "phone": "89119111213",
            "email": "pupkin@vasya.ru"
        }
    ],
    "device": {
        "ip": "127.0.0.1",
        "agent": "Mozilla"
    }
}

POS payment request example:

{
  "ver": 2,
  "txns": [
    {
      "masked_pan": "************4444",
      "exp": "202512",
      "amt": 28500,
      "cy": "RUB",
      "holder": "Vasya Pupkin",
      "phone": "89119111213",
      "email": "pupkin@vasya.ru",
      "rrn": "225456441682",
      "response _code": "00",
      "auth_code": "53494D",
      "tsi": "5657657658575657",
      "tvr": "0480800001",
      "datetime": "20190621075857",
      "aid": "A0000006581010"
    }
  ],
  "device": {
    "serial_number": "0000000000521",
    "vendor": "aqsi"
  }
}

Note: Authorisation request can be send only once on the received web service address. If an additional attempt to pay is required within the same order, OS must receive new web service address.

Note: In case of timeout on authorisation request, OS should check status of web service address session. If the status is active - OS can repeat authorisation request within the same web service address session.

The general timeout for response is 30 seconds.

Response example:

{
  "ver": 2,
  "status": "success"
}

2.3 Authorisation request status check

Authorisation request status check is used:

• to check status of web service address session in case of PG timeout;
• to check status the status of authorisation request processing;
• to get data for performing 3ds procedure of customer verification.

The general timeout for response is 10 seconds.

OS should send GET request on the same web service address (as it was used for authorisation request sending).

The format of the response is the same as the response on authorisation request.

Request type: GET

Authorisation request processing status can be:

2.4 3DS authentication of customer

In case if authorisation request status is ready, response will contain the following additional fields with data for 3ds verification of customer:

• url - authentication service address
• txns - block of information that contains: - md - identifier of authentication session - pareq - ACS request - acs_url - ACS address - wtimeout - authentication timeout data

OS can hold 3ds verification of customer in 2 ways:

• by using PG MPI functional: open address from url response parameter;
• by using its own MPI functional.

Note: the choice to use its of own MPI functional assumes that OS specialist have enough working experience in 3D Secure protocol, PaReq/PaRes operations. This document doesn’t contain any information about MPI functional.

Response example:

{
  "ver": 2,
  "status": "ready",
  "url": "https://sandbox.egopay.ru/mpi",
  "txns": [
    {
      "id": "12345",
      "pareq": "dsfastewKJHsdf==",
      "acs_url": "https://acs.bank.hz"
    }
  ]
}

In case if OS specialists decide to use its own MPI functional, the following steps should be performed:

1. OS system forms and sends a 3DS authentication request;
2. OS system transfers the result of 3DS authentication to PG services using POST request.

POST request should be sent on the same web service address (as it was used for authorisation request sending).

Request type: POST

3DS results data transfer request parameters:

Request example:

{
  "ver": 2,
  "md": "12345",
  "pares": "dsfastewKJHsdf=="
}

The general timeout for response is 10 seconds.

The format of the response is the same as the response on authorisation request.

OS system should send GET request to get the status of PARes data transfer (see 2.3). The response will also include the ReturnURLOk/ReturnURLFault address, depending on order status.

Response example:

{
    "ver": 2,
    "status": "success",
    "url": "http://abc.ru"
}

3. References

3.1 3ds policy settings