Electronic certificate: payments with data collection on your side

This article explains how to accept payments made by electronic certificates on your payment page.

In order to use this integration option, you should prove compliance with a certain level of PCI DSS (Payment Card Industry Data Security Standard). To do this, fill out the Self-Assessment Questionnaire (SAQ D). Learn more about PCI DSS self-assessment

How it works

In this scenario, you independently implement the feature of selecting the payment method. You recieve the user's card details linked to the certificate on your side. Authorize the use of the certificate in the NSPK's FES. After that, you create a payment in YooMoney and wait when the user confirms the payment.

In order to complete integration, add a button that redirects users to payment to your website, as well as the payment form where users can enter their bank card details. When the user enters the details, authorize the use of the certificate in the NSPK's FES. After that, get a link to the 3-D Secure authentication page from YooMoney and redirect the user to it. When the user returns to your website, request the payment results from YooMoney.

General payment and refund scenarios

Payment processing
Payment refund

Payment processing

Payment processing (payments with data collection on your side)

The payment process is as follows:

The user proceeds to payment.
You ask the user for the details of their "Mir" card linked to the electronic certificate.
The user enters the card details.
You request the NSPK's FES to pre-authorize the use of the certificate. To do this, you need to provide the NSPK's FES with a POST request with bank card details and a list of products that can be paid using electronic certificate.
The NSPK's FES returns to you the shopping cart's ID, the payment amount that can be spent using certificate, and authorized products.
You create a payment: send a POST request with "Mir" card details, shopping cart's ID, and payment amount that can be spent using the certificate.
YooMoney returns the created payment object to you in the status pending, as well as the link to the 3-D Secure authentication page.
You redirect the user to this page.
Then the user completes authentication.
YooMoney requests the NSPK to debit the required amount from the card.
The NSPK returns the debiting results.
YooMoney requests the NSPK to debit the required amount from the certificate.
The NSPK returns the debiting results.
If you've enabled notifications, YooMoney sends a notification when the payment status changes to succeeded.
You request information about the payment by sending a GET request with the payment ID to YooMoney.
YooMoney returns the created payment object in its current status to you.
You provide the user with the payment results.
If you create receipts independently (not via YooMoney), you register the receipt in the online sales register, then submit its details in the Merchant Profile.
YooMoney sends the receipt details to the NSPK.
The NSPK informs you of the result.
You check the status of the receipt delivery to the NSPK in your Merchant Profile. Resubmit the details as needed.

Learn more about payment processing

Payment refund

This scenario is used to return products paid by electronic certificate. In other cases, the refund process is standard.

Payment refund

Payment refund (payments with data collection on your side)

Refunds processing is as follows:

You request the NSPK's FES to pre-authorize the refund. To do this, you need to provide the NSPK's FES with a POST request with shopping cart's ID, bank card details, and other data.
The NSPK's FES returns to you the refund shopping cart's ID.
You create a refund by sending a POST request with the refund shopping cart's ID to YooMoney.
YooMoney requests the NSPK to refund the required amount to the certificate.
The NSPK returns the refund results.
YooMoney requests the NSPK to refund the required amount to the card, if necessary.
The NSPK returns the refund results.
YooMoney returns the created refund object in the current status to you.
You provide the user with the refund results.
If you create receipts independently (not via YooMoney), you register the receipt in the online sales register, then submit its details in the Merchant Profile.
YooMoney sends the receipt details to the NSPK.
The NSPK informs you of the result.
You check the status of the receipt delivery to the NSPK in your Merchant Profile. Resubmit the details as needed.

Learn more about refund processing

Payment processing

Step 1. Receive card details linked to the electronic certificate from the user.

Step 2. Send a request to pre-authorize the use of the certificate (Pre-Auth) in the NSPK's FES. The request should contain details of the "Mir" card linked to the electronic certificate, shopping cart, and other data. Learn more in the FES's API documentation

The shopping cart's ID purchaseBasketId and payment amount totalCertAmount that can be spent using certificate will be returned in response. These details are needed to make a payment via YooMoney.

The shopping cart's ID (purchaseBasketId) is valid for 30 minutes.

Step 3. Create a payment by sending a request with request authentication details, idempotence key, and payment details to YooMoney:

set the total amount in the amount object;
set the following details in the payment_method_data object:
- type parameter with a payment method code electronic_certificate;
- cardobject with details of the "Mir" card linked to the electronic certificate;
- electronic_certificate object with a shopping cart's ID (purchaseBasketId parameter value from the previous step) and the certificate amount (totalCertAmount value from the previous step);
in the confirmation object, set the redirect type and the return_url parameter with the page address on your side that will be open to the user when they've completed the payment;
set the payment description in the description parameter;
in the capture parameter, set the true value so the payment status will automatically change to succeeded after the payment.

Any other parameters except for save_payment_method, payment_method_id, payment_token, airline, transfers, and deal can be set in the request.

Create a payment within 30 minutes from the moment you receive shopping cart's ID. If you set an expired ID, the payment won't go through.

Request example

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
            "value": "5000.00",
            "currency": "RUB"
        },
        "payment_method_data": {
            "type": "electronic_certificate",
            "card": {
              "number": "5555555555554477",
              "expiry_year": "2025",
              "expiry_month": "07",
              "csc": "012",
              "cardholder": "Cardholder"
            },
            "electronic_certificate": {
              "basket_id": "445923711677676901483590",
              "amount": {
                "value": "2700.00",
                "currency": "RUB"
              }
            }
        },
        "confirmation": {
            "type": "redirect",
            "return_url": "https://example.com/return_url"
        },
        "capture": true,
        "description": "Order No. 37",
        "metadata": {
            "order_id": "37"
        }
      }'

The payment object in its current status will be returned in response to the request.

Step 4. If the payment object returns in the pending status, redirect the user to the YooMoney page which address will be sent in confirmation_url. This is the link to the 3-D Secure authentication. It is valid for 1 hour. If the user doesn't authenticate within this time, YooMoney will cancel the payment.

Example of a created payment object

JSON
{
  "id": "2d78da66-000f-5000-9000-1297ba86ffa5",
  "status": "pending",
  "amount": {
    "value": "5000.00",
    "currency": "RUB"
  },
  "description": "Order No. 37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "electronic_certificate",
    "id": "2d78da66-000f-5000-9000-1297ba86ffa5",
    "saved": false
  },
  "created_at": "2024-01-28T15:21:05.441Z",
  "confirmation": {
    "type": "redirect",
    "enforce": true,
    "return_url": "http://return.url",
    "confirmation_url": "https:// yoomoney.ru/checkout/payments/v2/contract/electronic-certificate?orderId=2d78da66-000f-5000-9000-1297ba86ffa5"
  },
  "test": false,
  "paid": false,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  }
}

Step 5. Wait for the payment to be successfully completed: you'll receive a notification from YooMoney, or you can send periodic requests for payment information .

Example of the payment with succeeded status

JSON
{
  "id": "2d78da66-000f-5000-9000-1297ba86ffa5",
  "status": "succeeded",
  "amount": {
    "value": "5000.00",
    "currency": "RUB"
  },
  "income_amount": {
    "value": "4825.00",
    "currency": "RUB"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "electronic_certificate",
    "id": "2d78da66-000f-5000-9000-1297ba86ffa5",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_year": "2030",
      "expiry_month": "01",
      "card_type": "Mir"
    },
    "electronic_certificate": {
      "amount": {
        "value": "2700.00",
        "currency": "RUB"
      },
      "basket_id": "445923711677676901483590"
    },
  "captured_at": "2024-01-28T15:21:38.320Z",
  "created_at": "2024-01-28T15:21:05.441Z",
  "test": false,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "paid": true,
  "refundable": true,
  "metadata": {
    "order_id": "37"
  },
  "description": "Order No. 37"
}

Step 6. When the user returns to return_url, display the result of payment process (success or failure) depending on the payment status.

Step 7. Make sure to create a payment receipt:

If you use YooMoney's solutions for sending receipts to the Tax Office, make sure that the receipt is successfully registered in the online sales register. This can be done in the Merchant Profile or via API.
If you send receipts independently (not via YooMoney), register the receipt in the online sales register.

Step 8. Make sure that receipt details are delivered to the NSPK:

If you send receipts via YooMoney, make sure that the details is delivered to the NSPK in the Merchant Profile. If something went wrong, resend details via your Merchant Profile and check the status of the delivery in the NSPK again. How to resend details
If you send receipts independently, submit receipt details via the Merchant Profile and make sure they are delivered. How to submit details to the NSPK via the Merchant Profile

Done!

Payment refund

Full and partial refunds are available.

If something goes wrong when you make a refund to the certificate, the whole transaction is canceled. You need to complete it again. Learn more about unsuccessful refunds

If the refund is successful, money will be credited to certificate and card within about 3 days. Learn more about refund processing time

Full refund

Step 1. Submit a refund Pre-Auth request to the NSPK's FES. In the request, set the shopping cart's ID (purchaseBasketId) that you've received when making the payment, details of the "Mir" card linked to the electronic certificate, refund shopping cart, and other details. Learn more in the FES's API documentation

In response, you'll receive the refund shopping cart's ID returnBasketId as well as amount totalCertAmount that will be returned to electronic certificate. This details are needed to process the refund via YooMoney.

The refund shopping cart's ID (returnBasketId) is valid for 30 minutes.

Step 2. Create a refund : send YooMoney a request with request authentication details, idempotence key, and details required to make a refund:

set the total refund amount in the amount object;
set the refunded payment's ID in the payment_id parameter;
In the refund_method_data object, set the code of electronic_certificate payment method, electronic_certificate object with the refund shopping cart's ID (value of the returnBasketId parameter from the previous step), and amount to be returned to the certificate;
set a refund description in the description parameter, if necessary.

In the request, you can set any other parameters except for sourcesand deal.

Create a refund within 30 minutes from the moment of receiving the refund shopping cart's ID. If you set an expired ID, the refund won't go through.

Example of the request for a full refund

cURL
PHP
Python
curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "payment_id": "2d78da66-000f-5000-9000-1297ba86ffa5",
        "amount": {
            "value": "5000.00",
            "currency": "RUB"
        },
        "refund_method_data": {
            "type": "electronic_certificate",
            "electronic_certificate": {
               "basket_id": "110200010001100000000001",
               "amount": {
                   "value": "2700.00",
                   "currency": "RUB"
                }
            }
        },
        "description": "Refund for order No. 37",
        "metadata": {
            "order_id": "37"
        }
      }'

The refund object in its current status will be returned in response to the request.

Example of a refund object with the succeeded status

JSON
{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "5000.00",
    "currency": "RUB"
  },
  "description": "Refund for order No. 37",
  "created_at": "2024-01-29T15:21:38.320Z",
  "payment_id": "2d78da66-000f-5000-9000-1297ba86ffa5",
  "refund_method": {
    "type": "electronic_certificate",
    "electronic_certificate": {
      "basket_id": "110200010001100000000001",
      "amount": {
        "value": "2700.00",
        "currency": "RUB"
      }
    },
    "articles": [
      {
        "article_number": 1,
        "payment_article_number": 1,
        "tru_code": "325022153.09000220200000000000",
        "quantity": 1
      },
      {
        "article_number": 2,
        "payment_article_number": 2,
        "tru_code": "325022153.09000220300000000000",
        "quantity": 1
      }
    ]
  }
}

Step 3. Make sure to create a refund payment receipt:

If you use YooMoney's solutions for sending receipts to the Tax Office, make sure that the receipt is successfully registered in the online sales register. This can be done in the Merchant Profile or via API.
If you send receipts independently (not via YooMoney), register the receipt in the online sales register.

Step 4. Make sure that receipt details are delivered to the NSPK:

If you send receipts via YooMoney, make sure that the details is delivered to the NSPK in the Merchant Profile. If something went wrong, resend details via your Merchant Profile and check the status of the delivery in the NSPK again. How to resend details
If you send receipts independently, submit receipt details via the Merchant Profile and make sure they are delivered. How to submit details to the NSPK via the Merchant Profile

Done!

Partial refund

If you make a refund for products paid by electronic certificate (full or partial), such a refund is created in the same way as a full one. The only differences: you need to authorize in the NSPK's FES only those products you need to return, while in the request to YooMoney you need to set only the refundable amount part in the amount parameter and in the electronic_certificate object.

Example of the request to YooMoney for a partial refund

cURL
PHP
Python
curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '
        "payment_id": "2d78da66-000f-5000-9000-1297ba86ffa5",
        "description": "Refund for order No. 37",
        "amount": {
          "value": "2000.00",
          "currency": "RUB"
        },
        "refund_method_data": {
            "type": "electronic_certificate",
            "electronic_certificate": {
               "basket_id": "110200010001100000000001",
               "amount": {
                   "value": "1200.00",
                   "currency": "RUB"
                }
            }
        }
      }'

If you return only those products from the shopping cart that were paid by bank card (extra payment), then the refund is created as a standard one. In this case, the refund_method_data object doesn't have to be set. Refunded amount (amount) can't be greater than extra payment amount, otherwise the refund won't go through.

Example of the request to YooMoney for a partial refund (extra payment only)

cURL
PHP
Python
curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "payment_id": "2d78da66-000f-5000-9000-1297ba86ffa5",
        "description": "Refund for order No. 37",
        "amount": {
          "value": "2300.00",
          "currency": "RUB"
        }
      }'

Unsuccessful refunds

If products were paid partly by certificate and partly by bank card, money is first returned to the certificate, and if everything was fine, the rest of the amount is returned to the card. If something goes wrong when you make a refund to the certificate, the whole transaction is canceled. You need to complete it again.

The reason for the cancellation will be specified in the cancellation_details object. Learn more about reasons for canceling a refund

Example of the refund object with canceled status

JSON
{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "payment_id": "2d78da66-000f-5000-9000-1297ba86ffa5",
  "status": "canceled",
  "cancellation_details": {
    "party": "refund_network",
    "reason": "payment_tru_code_not_found"
  },
  "created_at": "2024-01-29T15:21:38.320Z",
  "amount": {
    "value": "1200.00",
    "currency": "RUB"
  },
  "description": "Refund for order No. 37"
}