3D-Secure¶

3D-Secure (Three-Domain Secure) is a customer authentication protocol that ensures secure online payment for goods and services. The 3D-Secure technology (hereinafter referred to as 3DS) involves an additional authentication step when making a purchase at an online store:

1. During the first step, the bank card details, including the card number, expiration date, cardholder’s name, and authentication code (e.g., CVC2), are entered on the payment page;
2. On the second step, an additional security code is entered on the issuer bank’s web form.

Authentication when using QIWI Payment Form¶

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

Authentication when using Partner Payment Form¶

The client must be authenticated using 3DS if the response to the payment creation request contains the requirements.threeDS object with the following fields:

• acsUrl — Server’s URL to which the client is redirected for authentication.
• pareq — Encrypted authentication request.

To authenticate the client using 3D-Secure, the partner must make a POST request to acsUrl with the following request body parameters:

• TermUrl — URL of the partner’s page to which the client is redirected after successful authentication.
• MD — Unique identifier of the authentication transaction in the partner’s system.
• PaReq — Value of the pareq parameter from the response to the payment creation request.

After sending the POST request to acsUrl, the client’s data is passed to the payment system that services the bank card and the issuer bank. The issuer bank decides on the need for authentication:

• If authentication is not required, the client’s funds are debited from the card.
• If authentication is required, the client receives an OTP and enters it on the issuer bank’s form.

After successful authentication, the client is redirected to TermUrl with the encrypted verification result in the PaRes parameter.

To complete the authentication process, the partner must make an authentication completion request and pass the PaRes value in it.

<form name="form" action="{ACSUrl}" method="post" >
        <input type="hidden" name="TermUrl" value="{TermUrl}" >
        <input type="hidden" name="MD" value="{MD}" >
        <input type="hidden" name="PaReq" value="{PaReq}" >
</form>

POST /partner/payin/v1/sites/test-01/payments/1811/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  }
}

An example of successful authentication is shown in the diagram below.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        60 }}}%%
sequenceDiagram
    participant С as Client
    participant P as Partner
    participant Q as QIWI
    participant B as Issuing Bank
    P->>+Q: Payment creation request
    Q->>-P: Payment creation response
    Note left of Q: status:WAITING, requirements.threeDS.pareq, requirements.threeDS.acsUrl
    P->>С: Redirection to the acsUrl
    Note left of P: TermUrl, MD, PaReq
    rect rgb(230, 230, 230)
    Note over С, B: Issuer bank's form
    С->>B: Code execution (API call using a form)
    Note right of С: TermUrl, MD, PaReq
    B->>С: OTP
    С->>С: Entering OTP on the form
    С->>B: Code execution (API call using a form)
    B->>С: Redirecting to the partner's TermUrl
    С->>P: 
    Note right of С: PaRes
    end
    P->>+Q:  Authentication completion request
    Note right of P: threeDS.pares
    Q->>+B: Funds hold and/or capture
    B->>-Q: 
    Q->>Q: Changing the payment transaction status
    Q->>P: Payment transaction status