Recurring payments
You can save some of the payment methods (with all the payment details) and use them for recurring payments. In this case, the user will only need to confirm the first payment, and all subsequent debits will be automatic. Users can revoke their permission for recurring payments at any time.
Recurring payments are only enabled by default in the demo store. If you want to enable them in your real store, contact the YooMoney manager.
Specifics
The procedure is slightly different from default for partners who use an OAuth token for authenticating requests. Learn more in the For partners section
Recurring payments are supported by all integration scenarios.
Payment methods that can be used for recurring payments:
- YooMoney for Shopping wallet (except for bank cards linked to wallet);
- arbitrary bank card;
- Mir Pay;
- SberPay;
- T-Pay;
- FPS (there are exceptions).
The user can revoke their permission for recurring payments at any time.
The frequency of debits and the process of disabling the autopayment is set up on your side without the participation of YooMoney.
If you're adding money to wallet, account, or the mobile phone balance, read the information about the specifics of transferring data.
For partners
If you're a partner and you use an OAuth token for authenticating requests, you can process recurring payments on behalf of YooMoney users. It's only available for the YooMoney widget and Smart payment integration scenarios. Only YooMoney wallets and bank cards (not necessarily YooMoney cards) can be saved for recurring payments.
To process recurring payments on behalf of the store:
- notify the store that its representatives need to contact their YooMoney manager to enable recurring payments;
- request store's permission to save and use payment methods for recurring payments.
Procedure
Step 1. Save the payment method by saving the user’s means of payment in your store. You can do that after a successful payment. After the user allows the means of payment to be saved in your store and confirms the debit, YooMoney will save the data used for the payment. The payment’s ID will be used as the saved payment method’s ID.
Step 2. Make an autopayment (recurring payment) by initiating the automatic debit from the means of payment saved in the store.
Saving the payment method
If you accept payments using the YooMoney Checkout Widget, refer to the corresponding instruction for saving the payment method.
To save a payment method, create a payment in accordance with the selected integration scenario and specify the
save_payment_method parameter with the true value in the request. Then you can make the payment as usual.Example of a request for the Smart payment integration scenario
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": "2.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "capture": true, "description": "Order No. 72", "save_payment_method": "true" }'
To get the ID of the saved payment method:
Step 1. Wait until the user confirms the payment, and its status changes to
succeeded (or waiting_for_capture if it’s a two-stage payment). You can check the payment status in a notification sent by YooMoney, or you can send periodic requests for payment information .Step 2. Make sure the payment method is saved: the
payment_method.saved value in the payment object has changed to true.Example of a successful payment
JSON
{ "id": "22e18a2f-000f-5000-a000-1db6312b7767", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2018-07-18T17:20:50.825Z", "created_at": "2018-07-18T17:18:39.345Z", "description": "Order No. 72", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22e18a2f-000f-5000-a000-1db6312b7767", "saved": true, "card": { "first6": "555555", "last4": "4444", "expiry_month": "07", "expiry_year": "2022", "card_type": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "issuer_country": "RU", "issuer_name": "Sberbank" }, "title": "Bank card *4444" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "test": false }
Step 3. Save the
payment_method.id. You’ll need to use it as the identifier of the saved payment method for subsequent payments.Done!
Now you can make recurring payments. You can also use the identifier of the saved payment method to make payouts (only for bank cards).
Processing
Using the saved payment method, you can initiate recurring payments, for example, as a regular charge for a subscription or an instant payment for purchases in your store, without the need to enter payment details.
To make an autopayment, create a payment with a specified amount, transaction description, and the
payment_method_id parameter with the saved payment method ID. Such payments don’t require additional confirmation from the user.Example of a request
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": "2.00", "currency": "RUB" }, "capture": true, "payment_method_id": "<Saved payment method's ID>", "description": "Order No. 37" }'
After a successful payment, the
payment_method object will contain information about the payment details of the saved method used for the payment.If you use the solution for 54-FZ from YooMoney and the Payment after receipt scenario, the payment could return with the
pending status. It means YooMoney is waiting for the result of generating a receipt from the online sales register. To find out the payment status and whether the receipt was registered successfully, wait for a notification from YooMoney or send periodic requests for payment information .Example of a successful payment
JSON
{ "id": "255350c9-000f-5000-a000-1f211b3ea0a7", "status": "succeeded", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "authorization_details": { "rrn": "10000000000", "auth_code": "000000", "three_d_secure": { "applied": true } }, "captured_at": "2018-07-18T17:20:50.825Z", "created_at": "2018-07-18T17:18:39.345Z", "description": "Order No. 72", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22e18a2f-000f-5000-a000-1db6312b7767", "saved": true, "card": { "first6": "555555", "last4": "4444", "expiry_month": "07", "expiry_year": "2022", "card_type": "Mir", "card_product": { "code": "MCP", "name": "MIR Privilege" }, "issuer_country": "RU", "issuer_name": "Sberbank" }, "title": "Bank card *4444" }, "refundable": true, "refunded_amount": { "value": "0.00", "currency": "RUB" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "test": false }
If the user revoked their permission for recurring payments from the YooMoney wallet, the payment won’t be processed. The
cancellation_details object will contain the reason behind the cancellation, permission_revoked.Example of an unsuccessful payment
JSON
{ "id": "24a40656-000f-5000-9000-134108dd5325", "status": "canceled", "paid": false, "amount": { "value": "10.00", "currency": "RUB" }, "created_at": "2019-06-25T10:08:22.531Z", "metadata": {}, "payment_method": { "type": "yoo_money", "id": "249ea698-000f-5000-9000-1200128b882c", "saved": true }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false, "cancellation_details": { "party": "yoo_money", "reason": "permission_revoked" } }
See also