Eight reasons to switch to the new Yandex.Kassi API

    In October 2017, Yandex.Kassi 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 we recall the key reasons to switch to it for those who have not yet done so.

    1. Connecting payments 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 in five, as it was before. This, of course, is about that part of the work, when everything is agreed, applications are approved and access keys are received. But a day is enough for that too.

    And for those who sell in social networks, invoicing works by mail, SMS or just a link that can be sent in private messages.

    2. Save 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 once a year. And in the old version there is no support for the HTTPS SNI mode, which is now free (or almost free) included in the service "hosting with HTTPS" for many hosting providers.

    For refunds, confirmation, cancellation or retry of card payments, the MWS protocol is used (Merchant Web Services ) With the help of MWS, the store can make refunds , confirm and cancel deferred payments, as well as repeat payments by credit card(if the payer 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 authority, with which the store generated requests to Yandex.Money. Now all this comes out of the box - you just get access keys and implement the necessary payment methods.

    In general, many unnecessary things disappeared from the integration process, which we had to deal with on our own and spend time on it for developers and admins.

    3. Only REST and nothing more


    We rewrote everything in a REST-style - now the protocol is clearly built and behaves predictably. To the treasury of past difficulties - almost every payment method had its own syntax, script, and process that we had to go through when installing, configuring, and making payments. The new protocol got rid of "childhood diseases", meets the standards - which, inter alia, are set by international payment leaders.

    For comparison, let's look at the old and new methods of refund.

    Previously, it was necessary to create an order document for the execution of the operation according to the XML 1.0 standard, to create a cryptographic package of PKCS # 7 format with a digital signature, but without chains of certification, data compression and encryption. After that, a POST request was generated over HTTP / 1.1 with the body of the cryptographic package or in an attachment through the application / pkcs-mime MIME type. Then it’s the small business - to pass 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 itself:

    In the new version of the API, a refund in Python looks like this:
    refund = Refund.create({
        "amount": {
            "value": "2.00",
            "currency": "RUB"
        },
        "payment_id": "21741269-000d-50be-b000-0486ffbf45b0"
    })
    

    A clear JSON will return, which can be parsed with anything in a minimum amount of 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"
      }

    The 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 in very exotic cases), payments through the Cashier are connected quickly. If a person has been actively writing in Python for longer than a couple of months, he will cope with the integration.

    Last year, we released a library for mobile applications on iOS and Android. With its help, payment forms are embedded in the application and look like part of it (and no WebView). Users can pay by credit card, from a Yandex.Money wallet, through Google Pay, Apple Pay, or Sberbank Online.

    It is also implemented simply - give the instruction to your developer and soon you will see how wonderful it has become. We have already written more about how the mobile SDK increases the level of happiness for you and users of your mobile applications in our hublog .

    5. Regular payments without shamanism


    Immediately after installation and configuration, card payments with pre-authorization of funds will earn - they are built into the API by default.
    There are recurrent payments (both with a card and from the wallet): you need to coordinate them with the security service, but it was the same in the old protocol. If a recurring payment uses a card with mandatory 3D-Secure, then the new API will first return a link to it.
    In general, everything has become simpler - here, too, you do not need to perform long rituals with MWS, obtaining certificates and all other cryptocurrencies.

    6. Automatic notification of a change in payment status


    Previously, you had to manually check the status of each payment, and now, if it has changed, the developer will automatically receive a notification.
    There are four types of automatic notification of payment status built into API v3:
    1. “Awaiting confirmation by the merchant after payment”,
    2. "Paid"
    3. “Canceled or error occurred during payment”,
    4. "Payment returned."

    On the old protocol, we 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 failed, then instead of “something went wrong”, the new API will make it clear why it happened - for example, the card ran out of money or the user wanted to pay via Sberbank Online, but it was not connected.
    Occasionally there may be short-term “something went wrong” - we, of course, fight with them (the lead editor Natasha nods at me and shows my thumb), but to predict differences in error mapping between different banks or unexpected software behavior sometimes impossible. Even to us.
    In general, if the payment is canceled, then from the response of the API it will immediately be clear, because of which:
    {
      "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. Everything can be checked before you begin


    To get test keys and see how everything works, you need to register in your Yandex.Cash account - for this you need a username on Yandex and the company TIN. In the questionnaire, choose self-registration - in a minute a test circuit will be created and you can check how the payments go.

    Before we started this feature, a test environment was available in which you can try the API v3 using the Insomnia REST client. There are examples for payment by credit card, while it clearly shows which request is sent, what 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 Englishlanguages, and an even more detailed API reference .

    In general, switch to the new API, if not already, or connect to Yandex.Checkout - everything is ready for your visit there.

    Also popular now: