Mir Pay Payment¶

General Information¶

The partner can implement payment with its own payment form using Mir Pay. In this case, the client can pay for an order without entering their bank card details.

A simplified payment process looks like this:

1. Selection of the Mir Pay payment method on the partner’s payment form.

2. Selection of a card previously saved in Mir Pay.

3. Confirmation of payment in the Mir Pay application.

Implementing payment for payment aggregator differs from implementing payment for payment provider. Throughout the text, the term «partner» may be used to refer to either an aggregator or a provider.

Payment for Payment Aggregator¶

The payment aggregator should sign an agreement regulating legal relations with QIWI and perform the following actions:

1. Join NSPK.

2. Add the Mir Pay payment method to the payment form.

3. Process the payment.

Participation in NSPK¶

National System of Payment Cards (NSPK) is the operator of the Mir Payment System.

The payment aggregator needs to connect to the Mir Pay In-Application Service. To do that the payment aggregator needs to contact NSPK to request access. The simplified steps for connecting to the service are described below.

Aggregator Registration¶

To register with NSPK, the payment aggregator should:

1. Gain access to the NSPK Participant Hub support.nspk.ru. This means submitting a request to NSPK for access to the hub, including a confidentiality and non-disclosure agreement.

2. Create a task on support.nspk.ru to connect to the Mir Pay In-Application Service.

   Once the task is completed, the partner will receive a unique identifier in the service, as well as the NSPK public key certificate PK.NSPK, and all the necessary documentation for implementing the service.

3. Choose the technology for interacting with NSPK, which can include Deep Link/Universal Link and/or SDK.

4. Generate a pair of keys using the RSA-2048 algorithm:

   • SK.APPREG — secret key;
   • PK.APPREG — public key.

5. Create and submit a request to NSPK to issue a certificate based on the keys created in step 4, a Certificate Signing Request (CSR).

   • The Organizational Unit Name (OU) field of the Subject element should contain the value P{participant identifier obtained in step 2}.
   • The keyUsage field must specify the dataEncipherment purpose, which is data encryption.

6. Create a task on support.nspk.ru to access Crypto.Mir.

   Once the task is completed, the partner will receive instructions for connecting Crypto.Mir to inform security specialists.

7. Initiate the issuance of a certificate for the intermediate certification authority (Concentrator SubCA) in the personal account of Crypto.Mir.

As a result of successfully completing the «Aggregator Registration» stage, you will have:

• the aggregator and its public key component PK.APPREG are registered in the Mir Pay In-Application Service;
• certificate for the intermediate certification authority is issued.

TSP Registration¶

After aggregator registration, the aggregator should connect trading service providers (TSP) to the Mir Pay In-Application Service.

The process of connecting TSPs is described and illustrated below.

1. The participant creates a key pair using the RSA-2048 algorithm:

   • SK.MERCH_ID — secret key;
   • PK.MERCH_ID — public key.

2. The participant creates a request to issue an electronic signature certificate based on the keys created in step 1 - CSR, Certificate Signing Request.

   • In the Organizational Unit Name (OU) field of the Subject element, the value must be specified as M{merchantId}.
     • merchantId - MID, the merchant’s (TSP’s) identification number in the aggregator’s system.
     • The merchantId value must consist of 15 characters. If the value is less than 15 characters, it is padded with zeros on the left side: M000...00<merchantId>.
   • The keyUsage field must specify the digitalSignature purpose, which is digital signature of messages.

3. The participant submits the CSR request to the aggregator.

4. The aggregator signs a certificate by contacting the NSPK intermediate certification authority.

   In the certificate:

   • The Organizational Unit Name (OU) field of the Subject element should contain the value M{merchantId};
   • The Organizational Unit Name (OU) field of the Issuer element should contain the value P{participant identifier} (see step 2 of the «Aggregator Registration» section).

5. The aggregator saves a certificate in the JSON Web Key Set format (JWKS), publishes it on its own web resource, and returns to the TSP:

   • a certificate;
   • a link to the JWKS.
   Sample JWKS Link

   {host}/jwks/{merchantId}-jwks.json
   

6. The aggregator registers the TSP in Mir Pay In-Application Service using the API provided by NSPK.

As a result of successfully completing the «TSP Registration» stage, you will have:

• The TSP is registered in the Mir Pay In-Application Service.
• The aggregator stores certificates in the JWKS format for payment processing using Mir Pay.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":14,
        "actorMargin":150 }}}%%
sequenceDiagram
    participant M as TSP
    participant A as Aggregator
    participant N as NSPK
    M->>M: Create SK/PK and CSR
    M->>A: Transfer CSR
    A->>N: Sign a certificate using Concentrator SubCA
    N->>A: 
    A->>A: Generate and publish JWKS
    A->>M: Certificate and JWKS link
    Note over A,M: mirpay.qiwi.com/jwks/{merchantId}-jwks.json
    A->>N: TSP registration in Mir Pay In-Application Service
    N->>A: 
    Note right of A: API

Adding Mir Pay Payment Method¶

When adding the Mir Pay payment method to the own payment form, partner should follow the branding guidelines.

The Mir Pay payment button should be displayed on mobile versions of websites and on mobile devices running the Android operating system.

Payment Processing¶

To process a payment, the owner of the payment form with the Mir Pay payment method needs to:

• Implement the call to the Mir Pay application from the user interface.
• Implement the server-side reception of encrypted data from Mir Pay In-Application Service.

To process the payment, the aggregator should:

• Implement decryption of the data received from Mir Pay In-Application Service.

  If steps 1-3 of the «TSP Registration» scenario are performed by the TSP of the aggregator, the aggregator receives this data directly from the TSP.

• Implement the transfer of decrypted data to QIWI - calling the payment creation method using Mir Pay option.

• Test the functionality together with QIWI and NSPK.

An example of payment processing is described and illustrated below. In the example, payment is made with the aggregator’s payment form, and the interaction technology with NSPK is Deep Link/Universal Link.

1. The client selects a product or service on the TSP’s trading platform, proceeds to payment - goes to the aggregator’s payment form, and clicks the Mir Pay payment button.

2. The aggregator’s payment form initiates the call and data transfer to the Mir Pay application using Deep Link/Universal Link.

   The message is signed with SK.MERCH_ID.

3. The Mir Pay application generates a request to check the signature, and NSPK verifies the signature using PK.MERCH_ID (obtained during the «TSP Registration» scenario.

4. The client selects one of the previously saved cards for payment and confirms the payment in the Mir Pay application.
5. The Mir Pay application generates an encrypted data package with a token and payment data and returns it to the aggregator’s server. The data is encrypted using the aggregator’s public key PK.APPREG and signed with NSPK’s secret key SK.NSPK.
6. The aggregator decrypts the data package with the token and payment data using SK.APPREG and verifies the signature of the decrypted message using PK.NSPK (obtained during the «TSP Registration» scenario).

7. The aggregator generates a request to create a Mir Pay payment based on the decrypted data and sends it to QIWI.

   The request is provided as an example: for the actual format, list, and description of parameters, see the Payment API documentation.

   Request Example

   PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
   Accept: application/json
   Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
   Content-type: application/json
   Host: api.qiwi.com
   
   {
     "amount": {
       "currency": "RUB",
       "value": 1.00
     },
     "paymentMethod" : {
         "type": "CARD",
         "pan": "4444443616621049",
         "expiryDate": "12/19",
         "external3dSec": {
             "type": "MIR_PAY",
             "cav": "3D6FC826A08C82B89780029F69670FDDCF299B",
             "transId": "5ab52487-177f-464b-b695-2954ffc44a13",
             "mid": "000000000000001",
             "media": "DL",
         },
     "flags": [ "SALE" ]
     }
   

The subsequent process follows the description of the single-step payment scenario (see step 4).

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        60 }}}%%
sequenceDiagram
    participant С as Client
    participant P as Aggregator
    participant M as Mir Pay
    participant Q as QIWI
    С->>P: Purchase of goods or services
    Note right of С: Mir Pay
    P->>M: Call to the Mir Pay app and data transfer
    Note right of P: Deep Link / Universal Link
    M->>С: Display of saved cards
    С->>С: Card selection, payment confirmation
    С->>M: Payment confirmation
    M->>M: Token and payment data package generation
    M->>P: Encrypted data package with JWE token and payment data
    P->>P: Decryption
    P->>Q: Request to create a Mir Pay payment
    Note right of P: siteId, paymentId, pan, cav, transId, mid, media
    Q->>P: Response to the payment creation request
    Note left of Q: siteId, paymentId, amount, status:COMPLETED

Testing¶

General testing rules are described in the «Testing» article. Here, we will write about the specifics of testing the payment processing scenario using Mir Pay.

The aggregator can test payment processing together with NSPK and QIWI. Details of testing the interaction with NSPK should be clarified directly with NSPK.

To test the request for creating a Mir Pay payment, the aggregator uses specific values in request parameters:

• Test card number is specified as the pan.
• Any suitable values are specified as values for the other parameters (see requirements in the PaymentAPI documentation).

The result of the operation is determined by the card expiration date (expiryDate).

Payment for Payment Service Provider¶

Sorry, this section has not been translated yet, but we are working on it.