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 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 (theconfirmation_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.
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.
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 theelectronic_certificate
payment method and the arrayarticles
with the list of products that can be paid using electronic certificate; - in the
confirmation
object, set theredirect
type and thereturn_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 thetrue
value so the payment status will automatically change tosucceeded
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
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 theelectronic_certificate
payment method and the arrayarticles
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.
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 refundExample 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