En octobre 2017, Yandex.Kassa a un nouveau protocole de paiement et une troisième version de l'API. Nous avons déjà
évoqué comment et pourquoi nous en sommes arrivés là, et nous rappelons maintenant les principales raisons de passer à cela pour ceux qui ne l'ont pas encore fait.
1. Connecter les paiements est devenu très rapide
Sur la nouvelle API, cela se produit 5 à 10 fois plus rapidement qu'auparavant, et maintenant le développeur moyen peut connecter les paiements à son site Web ou à son application (enfin, ou pas tout à fait) en un jour ouvrable, et non en cinq jours, comme c'était le cas auparavant. Il s'agit bien sûr de cette partie du travail lorsque tout est convenu, que les demandes sont approuvées et que les clés d'accès sont reçues. Mais une journée suffit aussi.
Et pour ceux qui vendent sur les réseaux sociaux, la facturation fonctionne par mail, SMS ou tout simplement un lien qui peut être envoyé dans des messages privés.
2. Économisez la puissance des développeurs et des administrateurs
Pour conserver l'ancienne version, vous devez prendre soin de diverses petites choses - allouer une adresse IP statique pour travailler avec l'API, changer les certificats une fois par an. Et dans l'ancienne version, il n'y a pas de support pour le mode SNT HTTPS, qui est maintenant inclus gratuitement (ou presque gratuitement) dans le service «hébergement avec HTTPS» de nombreux fournisseurs d'hébergement
Pour les remboursements, la confirmation, l'annulation ou la nouvelle tentative de paiement par carte, le protocole MWS (Merchant Web Services) est utilisé. Avec l'aide de MWS, un magasin peut
effectuer des remboursements ,
confirmer et
annuler des paiements différés, ainsi que
des paiements répétés par carte de crédit (si le payeur a accepté cela). Dans l'ancienne version de l'API pour travailler avec MWS, le magasin devait recevoir un certificat X.509 de l'autorité de certification Yandex.Money, avec lequel le magasin générait des demandes à Yandex.Money. Maintenant, tout cela sort de la boîte - vous obtenez simplement des clés d'accès et implémentez les méthodes de paiement nécessaires.
En général, de nombreuses choses inutiles ont disparu du processus d'intégration, que nous avons dû gérer nous-mêmes et consacrer du temps aux développeurs et aux administrateurs.
3. Seulement REST et rien de plus
Nous avons tout
réécrit dans un style REST - maintenant le protocole est clairement construit et se comporte de manière prévisible. Au trésor des difficultés passées - presque chaque méthode de paiement avait sa propre syntaxe, script et
processus que nous devions suivre lors de l'installation, de la configuration et des paiements. Le nouveau protocole s'est débarrassé des "maladies infantiles", répond aux normes - qui, entre autres, sont fixées par les leaders internationaux du paiement.
À titre de comparaison, regardons les
anciennes et les
nouvelles méthodes de remboursement.
Auparavant, il était nécessaire de former un document de commande pour exécuter une opération selon la norme XML 1.0, de créer un package cryptographique au format PKCS # 7 avec une signature numérique, mais sans chaînes de certification, compression de données et cryptage. Après cela, une requête POST a été générée sur HTTP / 1.1 avec le corps du package cryptographique ou dans la pièce jointe via le type MIME application / pkcs-mime. Ensuite, c'est la petite entreprise - passer huit paramètres d'entrée et, en principe, tout est prêt.
Requête HTTP totale:
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——-
Et la demande de remboursement elle-même:
<returnPaymentRequest clientOrderId="46890" requestDT="2011-07-02T20:38:00.000Z" invoiceId="2000000433" shopId="6689" amount="10.00" currency="643" cause=" " />
Dans la nouvelle version de l'API, un remboursement en Python ressemble à ceci:
refund = Refund.create({ "amount": { "value": "2.00", "currency": "RUB" }, "payment_id": "21741269-000d-50be-b000-0486ffbf45b0" })
Un JSON clair sera renvoyé, qui peut être analysé avec n'importe quoi dans le minimum de temps:
{ "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" }
La beauté
4. Prise en charge de différentes langues et technologies
La nouvelle API dispose également d'un
SDK pour les appareils mobiles , PHP, Python et Node.js. Quoi que fassent vos gars backend (enfin, sauf dans des cas très exotiques), les paiements via le caissier sont connectés rapidement. Si une personne écrit activement en Python depuis plus de quelques mois, elle fera face à l'intégration.
L'année dernière, nous avons publié une bibliothèque d'applications mobiles sur iOS et Android. Avec son aide, les formulaires de paiement sont intégrés dans l'application et en font partie (et pas WebView). Les utilisateurs pourront payer la commande avec une carte de crédit, à partir d'un portefeuille Yandex.Money, via Google Pay, Apple Pay ou Sberbank Online.
Il est également mis en œuvre simplement - donnez les instructions à votre développeur et bientôt vous verrez à quel point il est devenu merveilleux. Nous avons déjà écrit plus en détail sur la façon dont le SDK mobile augmente le niveau de bonheur pour vous et les utilisateurs de vos applications mobiles dans notre
blog hub .
5. Paiements réguliers sans chamanisme
Immédiatement après l'installation et la configuration, les paiements par carte avec pré-autorisation des fonds gagneront - ils sont intégrés dans l'API par défaut.
Il y a des paiements récurrents (à la fois avec une carte et depuis le portefeuille): vous devez les coordonner avec le service de sécurité, mais c'était également le cas dans l'ancien protocole. Si un paiement récurrent utilise une carte avec 3D-Secure obligatoire, la nouvelle API y renverra d'abord un lien.
En général, tout est devenu plus simple - ici aussi, vous n'avez pas besoin d'effectuer de longs rituels avec MWS, d'obtenir des certificats et toutes les autres crypto-monnaies.
6. Notifications automatiques des changements de statut de paiement
Auparavant, vous deviez vérifier manuellement l'état de chaque paiement, et maintenant, s'il a changé, le développeur recevra automatiquement une notification.
Il existe quatre types de notification automatique de l'état du paiement intégrés à l'API v3:
- «En attente de confirmation par le commerçant après paiement»,
- "Payé"
- "Annulé ou une erreur s'est produite lors du paiement",
- "Paiement retourné."
Sur l'ancien protocole, nous devions écrire une listOrders de méthode MWS complexe, qui montrait la liste et les propriétés des commandes. 12 paramètres, logique complexe d'envoi d'une demande et opportunité intéressante de recevoir une réponse au format CSV:
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
Dans la nouvelle version donc. Demande:
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. Il est immédiatement clair à quel moment l'erreur s'est produite
Si le paiement a échoué, au lieu de «quelque chose s'est mal passé», la nouvelle API expliquera clairement pourquoi cela s'est produit - par exemple, la carte a manqué d'argent ou l'utilisateur a voulu payer via Sberbank Online, mais il n'était pas connecté.
Parfois, il peut y avoir à court terme «quelque chose s'est mal passé» - nous nous battons bien sûr avec eux (l'éditeur en chef Natasha me fait un signe de tête et montre mon pouce), mais pour prévoir les différences de mappage d'erreurs entre les différentes banques ou le comportement inattendu des logiciels parfois impossible. Même pour nous.
En général, si le paiement est annulé, la réponse de l'API sera immédiatement claire, à cause de laquelle:
{ "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. Tout peut être vérifié avant de commencer
Pour obtenir des clés de test et voir comment tout fonctionne, vous devez vous inscrire dans votre compte Yandex.Cash - pour cela, vous avez besoin d'un nom d'utilisateur sur Yandex et la société TIN. Dans le questionnaire, choisissez l'auto-inscription - dans une minute un circuit de test sera créé et vous pourrez vérifier comment les paiements se déroulent.
Avant de commencer cette fonctionnalité, un
environnement de test était disponible dans lequel vous pouvez essayer l'API v3 à l'aide du client Insomnia REST. Il existe des exemples de paiement par carte de crédit, qui montrent clairement quelle demande est envoyée, quelle réponse est retournée et ce qui se passe à toutes les étapes du processus d'échange de données.
Pour toutes les étapes d'intégration et de maintenance, nous avons un guide étape par étape en
russe et en
anglais , ainsi qu'une
référence API encore plus détaillée.
En général, passez à la nouvelle API, si ce n'est pas déjà fait, ou
connectez-vous à Yandex.Checkout - tout est prêt pour votre visite là-bas.