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

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

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)

The payment process is as follows:

The user proceeds to payment.
You create a payment by sending a POST request with a list of products to be paid by electronic certificate to YooMoney.
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).
You redirect the user to the payment page.
The user enters details of the "Mir" card linked to the electronic certificate.
YooMoney requests the NSPK's FES to authorize the shopping cart and the use of the certificate.
The NSPK's FES returns an authorized cart.
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.
The user confirms the payment.
YooMoney requests the NSPK to send details required to complete the 3-D Secure authentication.
The NPSK returns the required details.
YooMoney redirects the user to the authentication 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 was made on the YooMoney's ready-made page)

Refund process is as follows:

You create a refund by sending a POST request to YooMoney with a list of products paid by electronic certificate that should be returned.
YooMoney requests the NSPK's FES to authorize the refund.
The NSPK's FES returns the refund shopping cart's ID.
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. 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:

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 6. 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. 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:

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 3. 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 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"
}