Eight reasons to switch to the new Yandex.Cash API
In October 2017, Yandex.Cashi has a new payment protocol and a third version of the API. We have already talked about how and why we came to this, and now let us recall the key reasons for switching to it for those who have not yet done so.
On the new API, it happens 5-10 times faster than before, and now the average developer can connect payments to his (well, or not quite) website or application in one working day, and not five, as it was before. This, of course, is about that part of the work, when everything is agreed, applications have been approved and access keys have been received. But this is also enough day.
And for those who sell in social networks, billing works by mail, text message or just a link that can be sent to private messages.
To maintain the old version, you need to take care of various small things — allocate a static IP address for working with the API, change certificates every year. And in the old version there is no support for the SNI mode of HTTPS, which is now free of charge (or almost free of charge) included in the “HTTPS hosting” service for many hosting providers
')
For returns, confirmation, cancellation or recurring payments using the card, the MWS (Merchant Web Services) protocol is used. With the help of MWS, a store can make refunds , confirm and cancel deferred payments, as well as repeat payments by credit card (if the payer has agreed to this). In the old version of the API for working with MWS, the store needed to receive an X.509 certificate from the Yandex.Money certification center, with which the store made requests to Yandex.Money. Now it all comes out of the box - you just get access keys and implement the necessary payment methods.
In general, a lot of unnecessary things have disappeared from the integration process, which we had to deal with on our own and spend time on developers and admins.
We rewrote everything in REST-style - now the protocol is clearly constructed and behaves predictably. In the piggy bank of past difficulties - almost every payment method had its own syntax, script, and process that you had to go through when installing, setting up, and conducting payments. The new protocol got rid of "childhood diseases", meets the standards - which, among other things, are set by international payment leaders.
Let's take a look at the old and new payment refund methods for comparison.
Previously, it was necessary to create an order document for executing an operation according to the XML 1.0 standard, to form a PKCS # 7 crypto package with a digital signature, but without certification chains, data compression and encryption. After that, a POST request was formed over HTTP / 1.1 with the body of the crypto package or as an attachment through the application / pkcs-mime MIME type. Then things are easy - to transfer eight input parameters and, in principle, everything is ready.
Total HTTP request:
And the request for a refund:
In the new version of the API, the refund to Python looks like this:
Returns clear JSON, which can be parsed with anything in minimum time:
Beauty.
The new API also has an SDK for mobile devices , PHP, Python, and Node.js. Whatever your backend guys do (well, except for very exotic cases), payments via Cashier connect quickly. If a person has been actively writing in Python for more than a couple of months - he will cope with the integration.
Last year, we released a library for iOS and Android mobile apps. With its help, payment forms are embedded in the application and look like its part (and no WebView). Users will be able to pay by credit card, from a Yandex.Money wallet, via Google Pay, Apple Pay or Sberbank Online.
Being implemented is also easy - give instructions to your developer and soon you will see how beautiful it is. More information about how mobile SDK increases the level of happiness you and the users of your mobile applications, we have already written in our Hrabrablog .
Immediately after installation and configuration, card payments with pre-authorization of funds will be earned - they are built into the default API.
Recurrent payments (from the card and from the wallet) are also there: you need to coordinate them with the security service, but it was the same in the old protocol. If a recurrent payment card is used with a mandatory 3D-Secure, then the new API will first return a link to it.
In general, everything has become simpler - here, too, there is no need to perform long rituals with MWS, obtaining certificates and all other cryptographies.
Previously, you had to manually check the status of each payment, and now, if it has changed, the developer will automatically drop a notification.
Four types of automatic payment status notifications are built into the API v3:
The old protocol had to write a complex MWS method listOrders, which showed the list and properties of orders. 12 parameters, complex logic of sending a request and an intriguing opportunity to receive a response in CSV format:
In the new version so. Request:
If the payment did not go through, then instead of “something went wrong”, the new API will explicitly make it clear why this happened - for example, the card ran out of money or the user wanted to pay through Sberbank Online, but it is not connected.
Occasionally there may be short-term “something went wrong” - we, of course, fight with them (lead editor Natasha nods in this place and shows thumb), but sometimes predictions of differences in the error mapping of different banks or unexpected behavior of the software is impossible. Even us.
In general, if the payment is canceled, then the API response will immediately be clear, because of what:
In order to receive test keys and see how everything works, you need to register in your Yandex.Cashbox personal account - you need a login on Yandex and the company's TIN. In the questionnaire, select self-registration - a test loop will be created in a minute and you will be able to check how the payments go.
When we had not yet launched this feature, a test environment was available in which you can try API v3 with the help of the Insomnia REST client. There are examples for paying with a bank card, which clearly shows which request is sent, which response is returned and what happens at all stages of the data exchange process.
For all stages of integration and maintenance, we have a step-by-step guide in Russian and English , and an even more detailed reference book on API .
In general, go to the new API, if not yet, or connect to Yandex.Kassa - everything is ready for your visit.
1. Payment connection has become really fast
On the new API, it happens 5-10 times faster than before, and now the average developer can connect payments to his (well, or not quite) website or application in one working day, and not five, as it was before. This, of course, is about that part of the work, when everything is agreed, applications have been approved and access keys have been received. But this is also enough day.
And for those who sell in social networks, billing works by mail, text message or just a link that can be sent to private messages.
2. Saves the power of developers and admins
To maintain the old version, you need to take care of various small things — allocate a static IP address for working with the API, change certificates every year. And in the old version there is no support for the SNI mode of HTTPS, which is now free of charge (or almost free of charge) included in the “HTTPS hosting” service for many hosting providers
')
For returns, confirmation, cancellation or recurring payments using the card, the MWS (Merchant Web Services) protocol is used. With the help of MWS, a store can make refunds , confirm and cancel deferred payments, as well as repeat payments by credit card (if the payer has agreed to this). In the old version of the API for working with MWS, the store needed to receive an X.509 certificate from the Yandex.Money certification center, with which the store made requests to Yandex.Money. Now it all comes out of the box - you just get access keys and implement the necessary payment methods.
In general, a lot of unnecessary things have disappeared from the integration process, which we had to deal with on our own and spend time on developers and admins.
3. Only REST and nothing more
We rewrote everything in REST-style - now the protocol is clearly constructed and behaves predictably. In the piggy bank of past difficulties - almost every payment method had its own syntax, script, and process that you had to go through when installing, setting up, and conducting payments. The new protocol got rid of "childhood diseases", meets the standards - which, among other things, are set by international payment leaders.
Let's take a look at the old and new payment refund methods for comparison.
Previously, it was necessary to create an order document for executing an operation according to the XML 1.0 standard, to form a PKCS # 7 crypto package with a digital signature, but without certification chains, data compression and encryption. After that, a POST request was formed over HTTP / 1.1 with the body of the crypto package or as an attachment through the application / pkcs-mime MIME type. Then things are easy - to transfer eight input parameters and, in principle, everything is ready.
Total HTTP request:
POST /webservice/mws/api/returnPayment HTTP/1.1 Content-Type: application/pkcs7-mime Content-Length: 906 ——-BEGIN PKCS7——- MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCA JIAEgbE8P3htbCB2ZXJzaW9uPSIxLjAiIGVuY29kaW5nPSJVVEYtOCI/Pg0KPG1h a2VEZXBvc2l0aW9uUmVzcG9uc2UgY2xpZW50T3JkZXJJZD0iMTI5MTExNjIzNDUy OCIgc3RhdHVzPSIwIi6789Jvcj0iMCIgcHJvY2Vzc2VkRFQ9IjIwMTAtMTEtMzBU MTE6MjM6NTQuNjI0WiIgYmFsYW5jZT0iNTQxNDYuNzMiIC8+DQoAAAAAAAAxggF8 MIIBeAIBATB3MGoxCzAJBgNVBAYTAlJVMQ8wDQYDVQQIEwZSdXNzaWExFjAUBgNV BAcTDVN0LlBldGVyc2J1cmcxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMgUHR5 IEx0ZDEPMA0GA1UEAxMGc2VydmVyAgkAy2xbdQckXjIwCQYFKw4DAhoFAKBdMBgG CSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTEwMTEzMDEx MjM1NVowIwYJKoZIhvcNAQkEMRYEFEYNh8glwqIXGR/n6oYrApa8DaO5MA0GCSqG SIb3DQEBAQUABIGAHlgGsYK30RXWBvuQao0V73KIPQE1A6BCg7Y6Iag/xlmZ3rBB kFpszF/O2fB+t84pCHfV15ErZQEkAqIotkEYEgA3hAddEW5+RWUzp+3npHpW5OY7 h3niP5Pj+r0P8EDgHe2j0Zb3dzj2mbwOshZD+FP1IcR8AmiTV3u35C6KAEsAAAAA AAA= ——-END PKCS7——- And the request for a refund:
<returnPaymentRequest clientOrderId="46890" requestDT="2011-07-02T20:38:00.000Z" invoiceId="2000000433" shopId="6689" amount="10.00" currency="643" cause=" " /> In the new version of the API, the refund to Python looks like this:
refund = Refund.create({ "amount": { "value": "2.00", "currency": "RUB" }, "payment_id": "21741269-000d-50be-b000-0486ffbf45b0" }) Returns clear JSON, which can be parsed with anything in minimum time:
{ "id": "216742f7-0016-50be-b000-078a43a63ae4", "status": "succeeded", "amount": { "value": "2.00", "currency": "RUB" }, "created_at": "2017-10-04T19:27:51.407Z", "payment_id": "21746789-000f-50be-b000-0486ffbf45b0" } Beauty.
4. Support for different languages ​​and technologies
The new API also has an SDK for mobile devices , PHP, Python, and Node.js. Whatever your backend guys do (well, except for very exotic cases), payments via Cashier connect quickly. If a person has been actively writing in Python for more than a couple of months - he will cope with the integration.
Last year, we released a library for iOS and Android mobile apps. With its help, payment forms are embedded in the application and look like its part (and no WebView). Users will be able to pay by credit card, from a Yandex.Money wallet, via Google Pay, Apple Pay or Sberbank Online.
Being implemented is also easy - give instructions to your developer and soon you will see how beautiful it is. More information about how mobile SDK increases the level of happiness you and the users of your mobile applications, we have already written in our Hrabrablog .
5. Regular payments without shamanism
Immediately after installation and configuration, card payments with pre-authorization of funds will be earned - they are built into the default API.
Recurrent payments (from the card and from the wallet) are also there: you need to coordinate them with the security service, but it was the same in the old protocol. If a recurrent payment card is used with a mandatory 3D-Secure, then the new API will first return a link to it.
In general, everything has become simpler - here, too, there is no need to perform long rituals with MWS, obtaining certificates and all other cryptographies.
6. Automatic notifications about changing payment status
Previously, you had to manually check the status of each payment, and now, if it has changed, the developer will automatically drop a notification.
Four types of automatic payment status notifications are built into the API v3:
- "Waiting for confirmation by the merchant after payment",
- "Paid",
- “Canceled or an error occurred while paying”,
- "Payment refunded."
The old protocol had to write a complex MWS method listOrders, which showed the list and properties of orders. 12 parameters, complex logic of sending a request and an intriguing opportunity to receive a response in CSV format:
status=0;error=0;processedDT=2011-08-02T14:46:58.096+03:00;orderCount=2 shopId;shopName;articleId;articleName;invoiceId;orderNumber;paymentSystemOrderNumber;customerNumber;createdDatetime;paid;orderSumAmount; orderSumCurrencyPaycash;orderSumBankPaycash;paidSumAmount;paidSumCurrencyPaycash;paidSumBankPaycash;receivedSumAmount;receivedSumCurrencyPaycash; receivedSumBankPaycash;shopSumAmount;shopSumCurrencyPaycash;shopSumBankPaycash;paymentDatetime;paymentAuthorizationTime;payerCode;payerAddress;payeeCode; paymentSystemDatetime;avisoReceivedDatetime;avisoStatus;paymentType;agentId;uniLabel;environment 1;" ";2;"-";2000024717776;"2011.08.02 09:07:32";483512879684006008;97881;2011-08-02T08:07:59.148+03:00;true;10.15;643;1003;10.15;643; 1003;10.15;643;1003;10.15;643;1003;2011-08-02T08:07:59.684+03:00;483512879684006008;41003476047679;192.168.1.127;41003131475668;2011-08-02T08:07:59.684+03:00; 2011-08-02T08:07:59.660+03:00;1000;AC;200002;1cd12967-0001-5000-8000-000000034fd8;Live 1;" ";2;"-";2000024717780;2000024717780;483512937773006008;770367;2011-08-02T08:08:57.175+03:00;true;10.00;643;1003;10.00;643; 1003;10.00;643;1003;10.00;643;1003;2011-08-02T08:08:57.773+03:00;483512937773006008;41003494819180;192.168.1.127;41003131475668;2011-08-02T08:08:57.773+03:00; 2011-08-02T08:08:57.730+03:00;1000;AC;200002;1cd129a4-0001-5000-8000-000000034fe1;Live In the new version so. Request:
curl https://payment.yandex.net/api/v3/payments/{payment_id} \ -u < >:< > : { "id": "22312f66-000f-5100-8000-18db351245c7", "status": "waiting_for_capture", "paid": true, "amount": { "value": "2.00", "currency": "RUB" }, "created_at": "2018-07-18T10:51:18.139Z", "description": " â„–72", "expires_at": "2018-07-25T10:52:00.233Z", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22ebbf66-000f-5000-8000-18db351245c7", "saved": false, "card": { "first6": "555555", "last4": "4444", "card_type": "MasterCard" }, "title": "Bank card *4444" }, "test": false } 7. It is immediately clear at what point the error occurred.
If the payment did not go through, then instead of “something went wrong”, the new API will explicitly make it clear why this happened - for example, the card ran out of money or the user wanted to pay through Sberbank Online, but it is not connected.
Occasionally there may be short-term “something went wrong” - we, of course, fight with them (lead editor Natasha nods in this place and shows thumb), but sometimes predictions of differences in the error mapping of different banks or unexpected behavior of the software is impossible. Even us.
In general, if the payment is canceled, then the API response will immediately be clear, because of what:
{ "id": "22379b7b-000f-5000-9030-1a603a795739", "status": "canceled", "paid": false, "amount": { "value": "2.00", "currency": "RUB" }, "created_at": "2018-05-23T15:24:43.812Z", "metadata": {}, "payment_method": { "type": "bank_card", "id": "22977a7b-000f-5000-9000-1a603a795129", "saved": false }, "recipient": { "account_id": "100001", "gateway_id": "1000001" }, "test": false, "cancellation_details": { "party": "payment_network", "reason": "payment_method_restricted" } } 8. You can check everything before you start.
In order to receive test keys and see how everything works, you need to register in your Yandex.Cashbox personal account - you need a login on Yandex and the company's TIN. In the questionnaire, select self-registration - a test loop will be created in a minute and you will be able to check how the payments go.
When we had not yet launched this feature, a test environment was available in which you can try API v3 with the help of the Insomnia REST client. There are examples for paying with a bank card, which clearly shows which request is sent, which response is returned and what happens at all stages of the data exchange process.
For all stages of integration and maintenance, we have a step-by-step guide in Russian and English , and an even more detailed reference book on API .
In general, go to the new API, if not yet, or connect to Yandex.Kassa - everything is ready for your visit.
Source: https://habr.com/ru/post/453174/
All Articles