Old versions of the API
Help
Sign up for YooMoney
Electronic certificate: payments on the YooMoney's ready-made page
This article describes how to accept payments made using electronic certificate on the YooMoney's ready-made page.
How it works
In this scenario, you independently implement the feature of selecting the payment method. After creating the payment, you redirect the user to the YooMoney page. On this page, the user will enter details of the "Mir card" linked to the electronic certificate.
Entering bank card details
Entering bank card details
The user will then see those products that are going to be paid by certificate and those ones paid by card. Here they may also pay for the purchase.
List of products paid by electronic certificate and by card
List of products paid by electronic certificate and by card
If the certificate linked to the card can't be used to pay for selected products, you won't be able to process the payment. In this case, the user needs to return to your website and select another payment method.
In order to complete integration, add a button that will redirect users to payment to your website. When the user clicks the button, you will receive the link to the ready-made payment page from YooMoney: redirect the user to it. When the user returns back to your website, request payment results from YooMoney and display them.
General payment and refund scenarios
  • Payment processing
  • Payment refund
Payment processing
Payment processing (payments on the YooMoney's ready-made page)
Payment processing (payments on the YooMoney's ready-made page)
The payment process is as follows:
  1. The user proceeds to payment.
  2. You create a payment by sending a POST request with a list of products to be paid by electronic certificate to YooMoney.
  3. YooMoney returns the created payment object with the pending status to you alongside the link to the payment form (the confirmation_url parameter in the payment object).
  4. You redirect the user to the payment page.
  5. The user enters details of the "Mir" card linked to the electronic certificate.
  6. YooMoney requests the NSPK's FES to authorize the shopping cart and the use of the certificate.
  7. The NSPK's FES returns an authorized cart.
  8. YooMoney displays to the user the products that will be paid by certificate, the ones paid by bank card, and displays the extra payment amount.
  9. The user confirms the payment.
  10. YooMoney requests the NSPK to send details required to complete the 3-D Secure authentication.
  11. The NPSK returns the required details.
  12. YooMoney redirects the user to the authentication page.
  13. Then the user completes authentication.
  14. YooMoney requests the NSPK to debit the required amount from the card.
  15. The NSPK returns the debiting results.
  16. YooMoney requests the NSPK to debit the required amount from the certificate.
  17. The NSPK returns the debiting results.
  18. If you've enabled notifications, YooMoney sends a notification when the payment status changes to succeeded.
  19. You request information about the payment by sending a GET request with the payment ID to YooMoney.
  20. YooMoney returns the created payment object in its current status to you.
  21. You provide the user with the payment results.
  22. 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.
  23. YooMoney sends the receipt details to the NSPK.
  24. The NSPK informs you of the result.
  25. You check the status of the receipt delivery to the NSPK in your Merchant Profile. Resubmit the details as needed.
Payment refund

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

Payment refund (payment was made on the YooMoney's ready-made page)
Payment refund (payment was made on the YooMoney's ready-made page)
Refund process is as follows:
  1. You create a refund by sending a POST request to YooMoney with a list of products paid by electronic certificate that should be returned.
  2. YooMoney requests the NSPK's FES to authorize the refund.
  3. The NSPK's FES returns the refund shopping cart's ID.
  4. YooMoney requests the NSPK to refund the required amount to the certificate.
  5. The NSPK returns the refund results.
  6. YooMoney requests the NSPK to refund the required amount to the card, if necessary.
  7. The NSPK returns the refund results.
  8. YooMoney returns the created refund object in the current status to you.
  9. You provide the user with the refund results.
  10. 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.
  11. YooMoney sends the receipt details to the NSPK.
  12. The NSPK informs you of the result.
  13. You check the status of the receipt delivery to the NSPK in your Merchant Profile. Resubmit the details as needed.
Payment processing
Step 1. When the user proceeds to payment, create a payment . To do this, send a request to YooMoney with request authentication details, idempotence key, and payment details:
  • set the total payment amount in the amount object;
  • in the payment_method_data object, set the code of the electronic_certificate payment method and the array articles with the list of products that can be paid using electronic certificate;
  • 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 that the user will see when they make a payment in the description parameter;
  • in the capture parameter, set the true value so the payment status will automatically change to succeeded after the payment.

You can specify any other parameters in the request except for save_payment_method, payment_method_id, payment_token, airline, transfers, deal.

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",
          "articles": [
            {
              "article_number": 1,
              "tru_code": "325022153.09000220200000000000",
              "article_code": "NXXXL",
              "article_name": "Universal non-adjustable anti-slip cane NXXXL",
              "quantity": 2,
              "price": {
                "value": "1500.00",
                "currency": "RUB"
              }
            },
            {
              "article_number": 2,
              "tru_code": "325022153.09000220300000000000",
              "article_code": "HQ819",
              "article_name": "Non-universal hight-adjustable anti-slip cane HQ819",
              "quantity": 1,
              "price": {
                "value": "1200.00",
                "currency": "RUB"
              }
            }
          ]
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "capture": true,
        "metadata": {
          "order_id": "37"
        },
        "description": "Order No. 37"
      }'
The payment object  in its current status will be returned in response to the request.
Step 2. Redirect the user to the YooMoney page which address will be sent in the confirmation_url. This is a link to the ready-made YooMoney page.
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 3. Wait for the payment to be successfully completed: you will 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"
    },
    "articles": [
      {
        "article_number": 1,
        "tru_code": "325022153.09000220200000000000",
        "article_code": "NXXXL",
        "certificates": [
          {
            "certificate_id": "907581400329309796796024853331",
            "tru_amount": 1,
            "max_compensation": {
              "value": "1500.00",
              "currency": "RUB"
            },
            "compensation": {
              "value": "1500.00",
              "currency": "RUB"
            }
          }
        ]
      },
      {
        "article_number": 2,
        "tru_code": "325022153.09000220300000000000",
        "article_code": "HQ819",
        "certificates": [
          {
            "certificate_id": "277321977384515300457417391374",
            "tru_amount": 1,
            "max_compensation": {
              "value": "1200.00",
              "currency": "RUB"
            },
            "compensation": {
              "value": "1200.00",
              "currency": "RUB"
            }
          }
        ]
      }
    ]
  },
  "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 4. When the user returns to return_url, display the payment process result (success or failure) depending on the payment status.
Step 5. Make sure to create a payment receipt:
Step 6. Make sure that receipt details are delivered to the NSPK:
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. 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 the electronic_certificate payment method and the array articles with the list of products paid by certificate (identical to the list of products specified in the payment object);
  • set a refund description in the description parameter, if necessary.

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

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",
        "description": "Refund for order No. 37",
        "amount": {
          "value": "5000.00",
          "currency": "RUB"
        },
        "refund_method_data": {
          "type": "electronic_certificate",
          "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
            }
          ]
        }
      }'
The refund object  in its current status will be returned in response to the request.
Example of the refund object with 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 2. Make sure to create a refund payment receipt:
Step 3. Make sure that receipt details are delivered to the NSPK:
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 difference: you should set the part of the accepted payment amount to be returned in the amount parameter and the returned products in the articles array.
Example of the request 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",
          "articles": [
            {
              "article_number": 1,
              "payment_article_number": 2,
              "tru_code": "325022153.09000220300000000000",
              "quantity": 1
            }
          ]
        }
      }'
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. The refunded amount (amount) can't be greater than the extra payment amount, otherwise the refund won't go through.
Example of the request for a partial refund (only extra payment)
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"
}
See also
Payment process
Legal information
Terms and Conditions of the YooMoney ServiceElectronic Document Flow Agreement
+7 (495) 974-35-86
Ask a questionHelp
© 2025, "YooMoney", NBCO LLC