Stripe: сервис вашей мечты для автоматизации денежных переводов

⭐⭐⭐⭐⭐Stripe: сервис вашей мечты для автоматизации денежных переводов. Подробности читайте в статье на нашем сайте.

Stripe: сервис вашей мечты для автоматизации денежных переводов

Stripe: сервис вашей мечты для автоматизации денежных переводов

Stripe: сервис вашей мечты для автоматизации денежных переводов, фотография 1

Статья была впервые опубликована здесь.

В этой статье мы хотим рассказать, как интегрировать сервис Stripe в e-Commerce-проект. Имевшие с ним дело знают, что он отлично заточен под разработчиков: понятная документация, хороший тестовый режим — полная копия реального, и для перехода на live-режим нужно только заменить ключи, не трогая API и не получая никаких сюрпризов. Админка тестового режима — тоже полная копия боевого. В общем, Stripe — это хорошо. Надеемся, что наш опыт поможет всем, кто хочет попробовать сервис на своём проекте.

Однако перед тем, как использовать Stripe, задайте вопрос: «А где находится бизнес, который мы будем обслуживать?». Например, если бизнес российский, Stripe для нас бесполезен: принимать платежи можно из любой страны, но бизнес владельца аккаунта на Stripe должен быть юридически зарегистрирован в одной из доступных стран. Иначе создать и авторизовать аккаунт невозможно. Список стран можно посмотреть здесь. Если вы хотите выводить деньги на другие счета, например, поставщикам (как это делать, я расскажу ниже), то юридически поставщики тоже должны находиться в странах, с которыми работает Stripe. Бизнес клиента, с которым работала я, зарегистрирован в Америке, что позволяло проводить платежи через Stripe.

Также нужно быть готовым, что Stripe не поддерживает xml-протокол 3-D-secure, который требует от клиента вводить код подтверждения, полученный в SMS-сообщении. Stripe просто пытается провести платеж без этой опции, и если банк принимает платежи без 3-D Secure — хорошо, если нет — всё закончится отказом, и с этой карты платить не получится.

Проведение платежа

Чтобы перевести деньги с карточки клиента на наш Stripe-аккаунт, нам нужно сделать следующее. С помощью скрипта Stripe.js получим на фронтенде Stripe token. Дальше мы будем использовать token с серверной стороны, чтобы провести сам платёж.

Подключаем Stripe.js и указываем публичный ключ:


<script type=«tТеперь получим token:ext/javascript»>
Stripe.setPublishableKey(‘your_public_key’);
</script>

Делаем обычную HTML-форму, на input указываем атрибуты data-stripe для работы скрипта. Нам будет нужен номер карты клиента, год и месяц валидности карты и CVC. Имя и фамилию владельца Stripe не требует.

<form action="" method="POST" id="payment-form"> 
    <span class="payment-errors"></span> 
    <label>Card Number</label> 
    <input type="text" size="20" data-stripe="number"> 
    <label>Expiration (MM/YY)</label> 
         <input type="text" size="2" data-stripe="exp_month"> 
    <input type="text" size="2" data-stripe="exp_year"> 
    <label>CVC</label> 
    <input type="text" size="4" data-stripe="cvc"> 
    <input type="submit" class="submit" value="Submit"> 
</form>

Теперь получим token:

$(function() { 
  var $form = $('#payment-form'); 
  $form.submit(function(event) { 
    // Отключим кнопку, чтобы предотвратить повторные клики 
    $form.find('.submit').prop('disabled', true); 
     // Запрашиваем token у Stripe 
    Stripe.card.createToken($form, stripeResponseHandler); 
     // Запретим форме submit 
    return false; 
  }); 
}); 
 function stripeResponseHandler(status, response) { 
  // Получим форму: 
  var $form = $('#payment-form'); 
   if (response.error) { // Problem! 
     // Показываем ошибки в форме: 
    $form.find('.payment-errors').text(response.error.message); 
    $form.find('.submit').prop('disabled', false); 
// Разрешим submit 
   } else { // Token был создан 
     // Получаем token id: 
    var token = response.id; 
     // Вставим token в форму, чтобы при submit он пришел на сервер: 
    $form.append($('<input type="hidden" name="stripeToken">').val(token)); 
     // Сабмитим форму: 
    $form.get(0).submit(); 
  } 
};

На всякий случай: этот шаг описан в официальной документации.

Теперь мы можем списать деньги с клиента через сервер. Примеры кода на PHP.

// Устанавливаем секретный ключ 
\Stripe\Stripe::setApiKey("your_secret_key"); 
// Забираем token из формы 
$token = $_POST['stripeToken']; 
// Создаём оплату  
try { 
  $charge = \Stripe\Charge::create(array( 
    "amount" => 1000, // сумма в центах 
     "currency" => "usd", 
    "source" => $token, 
    "description" => "Example charge" 
    )); 
} catch(\Stripe\Error\Card $e) { 
  // Платёж не прошёл 
}

Это всё, что нужно сделать, чтобы перевести деньги с карты клиента на ваш Stripe-счёт.

Автоматические переводы денег вашим поставщикам

Теперь рассмотрим перевод на рабочем примере. Представим, что вы пишете платформу, которая продаёт редкие книги из маленьких издательств по всему миру. Вам нужно переводить деньги вашим поставщикам-издательствам, чтобы они выслали книгу клиенту, и брать себе комиссию 10 $ c каждой продажи. Вы не хотите париться с ежемесячными отчётами и выплатами, вы хотите просто переводить деньги каждый раз, когда платит клиент. Stripe это позволяет.

Как и прежде, обязательное условие для настройки автоматических переводов — это нахождение поставщика в одной из стран, поддерживаемых Stripe.

У Stripe есть замечательная штука Managed Acсounts. С помощью этой опции мы как бы создаем Stripe-аккаунт для нашего поставщика, но берём на себя все заботы по управлению аккаунтом, так что самому издательству не нужно будет регистрироваться в Stripe.

Сначала получим информацию о банковском счёте вашего издательства с помощью уже знакомого нам скрипта Stripe.js. Как и в случае списания денег с карты клиента, для операций над банковским счётом нам тоже нужен Stripe token.

Stripe.bankAccount.createToken({ 
  country: $('.country').val(), // 2-хсимвольный код страны (US) 
  currency: $('.currency').val(), // 3-хсимвольный код валюты (USD) 
  routing_number: $('.routing-number').val(), // идентификационый номер банка 
  account_number: $('.account-number').val(), // номер банковского счёта 
  account_holder_name: $('.name').val(), // имя владельца бизнеса (в нашем примере — издательства) 
  account_holder_type: $('.account-holder-type').val() // тип аккаунта — идивидуальный предприниматель или компания (individual, company) 
}, stripeResponseHandler);

Это тоже описано в документации.

Ремарка. Имейте в виду, что для каждой страны банковские данные (routing_number, account_number) заполняются по-разному. Например, для европейских стран нужно получать IBAN-номер. Он кладётся в поле account_number, а routing_number не отпраляется вообще. Также для некоторых стран внутренние номера счетов склеиваются в одну строку и записываются в поля. Например, чтобы получить корректный идентификационный номер банка routing_number для Канады, надо склеить transit number и institution number (transit number + institution number). Если transit number: 02345, а institution number: 987, то routing_number будет ‘02345987’. Account number варьируется в зависимости от банка. А для Германии нужен будет только IBAN номер, он заполняется в поле routing_number. Например, IBAN: DE89370400440532013000 (22 символа). Как заполнять эти поля для остальных стран, можно посмотреть тут.

Итак, теперь у нас есть token банковского счёта, куда мы можем выводить деньги поставщикам. Давайте создадим Managed Account. Пусть наше издательство находится в Америке, является компанией, а не ИП, и мы платим ему в американских долларах.

\Stripe\Stripe::setApiKey("your_secret_key"); 
$account = Account::create([ 
   "country" => 'US', 
   "managed" => true, ]); 
if (isset($account->id)) { 
   try { 
       $account->external_accounts->create( 
           ["external_account" => $token] // наш token банковского счета 
       ); 
   } catch (InvalidRequest $error) { 
       // произошла ошибка создания 
    } 
}

Казалось бы, теперь у нас есть Managed Account, и можно переводить деньги, но нет: аккаунт нужно верифицировать. Для этого нужно предоставить Stripe определённую юридическую информацию о компании. Какая именно информация нужна и в каких странах, описано здесь.

Итак, для издательства в Америке нам нужно предоставить:

НазваниеОписание
legal_entity.address.cityГород, в котором расположена компания
legal_entity.address.line1Адрес компании
legal_entity.address.postal_codeПочтовый индекс
legal_entity.address.stateШтат
legal_entity.business_nameНазвание компании
legal_entity.business_tax_idНалоговый идентификационный номер
legal_entity.dob.dayДень рождения владельца компании
legal_entity.dob.monthМесяц рождения владельца компании
legal_entity.dob.yearГод рождения владельца компании
legal_entity.first_nameИмя владельца компании
legal_entity.last_nameФамилия владельца компании
legal_entity.ssn_last_4Четыре последние цифры номера социального страхования владельца компании
legal_entity.typeindividual/company
tos_acceptance.dateДата принятия условий использования Stripe
tos_acceptance.ipIP-адрес, с которого происходило принятие условий использования Stripe

Условия использования Stripe здесь. Человек, от чьего имени будет создаваться Managed Account, должен их принять.

Также Stripe может потребовать дополнительную информацию. Для Америки это:

ИмяОписание
legal_entity.personal_id_numberЛичный идентификационный номер
legal_entity.verification.documentСкан документа, подтверждающего личность

Собираем необходимую информацию и редактируем аккаунт.

\Stripe\Stripe::setApiKey("your_secret_key"); 
$account = Account::retrieve($accountId); 
$account->legal_entity->address->city = 'New-York'; 
$account->legal_entity->address->state = 'New-York'; 
$account->legal_entity->address->postal_code = '00501'; 
$account->legal_entity->address->line1 = 'Some address'; 
$account->legal_entity->business_name = 'US TEST'; 
$account->legal_entity->business_tax_id = '00000001'; 
$account->legal_entity->dob->day = 1; 
$account->legal_entity->dob->month = 1; 
$account->legal_entity->dob->year =  1980; 
$account->legal_entity->first_name = 'Bob'; 
$account->legal_entity->last_name = 'Smith'; 
$account->legal_entity->type = 'company'; 
$account->legal_entity->ssn_last_4 = '0000'; 
$account->tos_acceptance->date = 1466074123; // timestamp 
$account->tos_acceptance->ip = <nobr>123.123.123.123</nobr>; 
try { 
   $account->save(); 
   } catch (InvalidRequest $error) { 
// ошибка во время сохранения 
  }

Теперь команда Stripe всё проверит, и в админке мы увидим статус Verified. https://dashboard.stripe.com/t…

(изображение увеличивается при клике)

image03.png#asset:4791:url

Но этого нам не будет достаточно. Также команда Stripe может указать ошибки в данных или потребовать дополнительной информации, например personal_id_number.

image00.png#asset:4792

Когда команда проверит данные, аккаунт будет обновлён. На это событие можно настроить webhook.

image01.png#asset:4793

Необходимые поля будут описаны в объекте аккаунта:

$account->verification->fields_needed

Также Stripe может выставить дедлайн для предоставления данных. Если дата есть, она будет в свойстве $account->verification->due_by.

Для тестирования верификации Stripe предоставляет хорошую тестовую среду. С помощью переводов с определённых тестовых карт мы можем симулировать разные сценарии поведения верификации аккуантов. Примеры таких сценариев:

  • данные не заполнены, и мы вообще не можем совершать переводы;
  • сработал лимит на размер платежа. Это происходит, если Stripe считает, что перевод слишком большой, и предоставленной информации ему недостаточно. В этом случае он отключает Managed Account;
  • отключение аккаунта с требованием ввести данные к определенной дате;
  • загрузка скана документа, подтверждающего личность владельца аккаунта;
  • принятие и отклонение этого скана.

Как конкретно симулировать эти случаи, описано здесь.

Обработать все ситуации придётся в любом случае. И по моему опыту, лучше сразу предоставить Stripe максимум информации, чтобы избежать сюрпризов с отключением аккаунта.

Когда все окей, и Stripe верифицировал ваш Managed Account, нужно включить переводы (transfers) с помощью API или отключить автоматические — это одно и то же. https://dashboard.stripe.com/account/transfers

image02.png#asset:4794

Итак, у нас есть верифициронный аккаунт, переводы включены, и теперь мы можем делать переводы денег напрямую поставщику.

Предположим, у нас есть книга. Поставщик хочет за неё 50 $, мы хотим 10 $ долларов комиссии себе, плюс нам надо заложить в цену комиссию Stripe на перевод. Сейчас Stripe берёт за каждый перевод 2,9% + 30¢. Мы решили, что оплатим комиссию из своей части. Тогда пользователю надо заплатить за книгу 60 $. Из своей части мы отдадим 2,04 $ комиссии Stripe.

Получаем token с помощью Stripe.js и проводим платёж со стороны сервера.

$charge = Charge::create([ 
   "amount" => 6000, // в центах 
   "currency" => 'USD', 
   "source" => $token, 
   "application_fee" => 1000, 
    "destination" => $managedAccountId 
]);

Свойство application_fee позволяет указать, какую сумму от перевода оставить на нашем счету. Комиссия Stripe будет списываться в любом случае только с нашего счёта, даже если мы сделаем полный перевод поставщику.

На банковский счёт поставщика деньги сразу не придут, они выводятся раз в семь дней. Т. е. мы переводим деньги на Stripe-аккаунт нашего поставщика, и по истечении семи дней они переводятся аккаунту на привязанный банковский счёт.

Дополнительные фичи

Кроме того, Stripe позволяет сохранять клиентов, добавлять произвольные метаданные при создании платежа, чтобы было проще ориентироваться в проведённых платежах, задавать description при платеже для его более информативного описания, и многое другое. Обо всём этом можно посмотреть в документации к API платежей.

Полезные ссылки:

Страны, которые поддерживают Stripe
Custom HTML form для получения token
Managed Acсounts
Получение token для банковского аккаунта
Необходимая банковская информация по странам
Необходимая юридическая информация для Managed Accounts по странам
Условия использования Stripe
Тестирование верификации аккуанта
Webhooks
Stripe Pricing
Stripe API Reference

Cкиллы
Разработка бэкенда мобильного приложения на стороне студии: почему это выгодно

В этой статье мы рассказываем о важности бэкенда и почему продукт получается лучше, когда команды мобильной и бэкенд-разработки находятся под одной крышей...

Клиентам
24 декабря 2019
К чему готовиться при проектировании eCommerce-приложения

Рассказываем, из каких этапов состоит проектирование приложения для крупного интернет-магазина и каких монстров нужно побороть в этом процессе

Еком
11 декабря 2017
Не дай ему уйти: как удержать пользователей в приложении интернет-магазина

Старый и преданный клиент всегда лучше пяти новых, но непреданных. Рассказываем, почему это так, и делимся способами нарастить и укрепить лояльную аудиторию

Еком
29 июня 2018