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

Общая информация

В платёжной платформе ecommpay поддерживается возможность проводить выплаты на счета, ассоциированные с платёжными картами, с использованием платёжной формы Payment Page: с предварительной регистрацией каждой такой выплаты через Gate API и с последующим вызовом платёжной формы в режиме работы Payout. При этом отправителями выплат могут выступать как сам мерчант, так и физические лица, а при проведении выплат могут использоваться сервисы Mastercard MoneySend и Visa Direct.

Для регистрации выплаты необходимо отправить соответствующий запрос к платформе через Gate API и принять оповещение о результате этой регистрации. Если выплата зарегистрирована, в оповещении передаётся специальный идентификатор (uuid), который необходимо указать при вызове Payment Page. При этом важно учитывать, что срок действия идентификатора составляет 30 минут и при открытии платёжной формы на её страницах отображается таймер с остающимся временем до подтверждения выплаты пользователем. В случае, если пользователь не подтвердил выплату в заданное время, ему отображается соответствующее уведомление, и для проведения выплаты со стороны веб-сервиса требуется зарегистрировать её повторно, с указанием нового идентификатора платежа (payment_id).

Выплаты с использованием Payment Page выполняются с их подтверждением пользователями с помощью проверочных кодов. Такие коды отправляются от платёжной платформы на адрес электронной почты пользователя, указанный при регистрации выплаты.

Со стороны пользователя для проведения выплаты с использованием Payment Page следует выбрать платёжный инструмент, указать его реквизиты, затем указать проверочный код и получить уведомление о результате. При этом платёжные данные могут быть указаны одним из следующих способов:

• Через ввод на странице формы. В этом случае пользователь обязательно заполняет на страницах формы все требуемые поля.
• Через выбор или ввод на странице формы. В этом варианте пользователь может выбрать одни из уже сохранённых реквизитов или указать новые, которые также могут быть сохранены и доступны ему в дальнейшем.
• Через выбор до вызова формы. В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты и платёжная форма открывается с указанием необходимых реквизитов.

По результатам проведения выплат могут формироваться токены платёжных карт — в случаях, когда данные этих карт не были сохранены ранее и такая возможность подключена для используемого проекта мерчанта (подробнее).

Пользовательский сценарий

Допустим, пользователь Prostetnik Jeltz занял третье место в конкурсе Millstone Jennings Poetry с призом, равным 70 EUR. Чтобы получить выплату, пользователь указывает данные платёжного инструмента и свои имя и фамилию, после чего подтверждает выплату и ожидает результата её проведения.

Ограничения

Проведение выплат с использованием Payment Page возможно с учётом следующих ограничений:

• Возможность проведения выплат должна быть подключена для используемого проекта.

  В случае отправки запроса на регистрацию выплаты в рамках проекта, для которого не подключена такая возможность, от платёжной платформы к веб-сервису направляется оповещение с кодом ошибки 317 (подробнее).

• Для отправки запросов на регистрацию выплат должны использоваться IP-адреса, предоставленные специалистам технической поддержки ecommpay и добавленные ими в список разрешённых.

  В случае отправки запроса с IP-адреса, не добавленного в список разрешённых, от платёжной платформы к веб-сервису направляется ответ с кодом ошибки 403 (подробнее).

• Должны соблюдаться установленные ограничения для платёжной карты получателя выплаты, в том числе на количество зачислений, их общую сумму и сумму однократного зачисления.

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

• Остаток средств на счёте мерчанта должен быть достаточным для проведения выплаты.

  Если средств недостаточно, выплата отклоняется, пользователю отображается страница платёжной формы с информацией об отклонении платежа и к веб-сервису направляется оповещение с соответствующим кодом ошибки. Информацию об остатке средств можно получать через Dashboard (подробнее) и Data API (подробнее), при этом с вопросами можно обращаться к курирующему менеджеру ecommpay.

• Должны соблюдаться требования платёжных систем и программ, в рамках которых проводится выплата, а также специфические требования и условия, характерные для отдельных регионов, платёжных систем и провайдеров.

  Так, для разных программ может требоваться указывать различные сведения об отправителе или получателе выплаты в запросах на открытие платёжной формы.

  Прим.:

  Такие требования могут касаться, в частности, следующих случаев:

  • для выплат в рамках программ сервиса MoneySend платёжной системы Mastercard, в которых отправителем является физическое лицо, должны указываться имя и фамилия получателя, а также имя и фамилия, основной идентификатор используемого платёжного инструмента и информация о местонахождении отправителя — если эти сведения не указаны в запросе на открытие платёжной формы, выплата отклоняется;
  • для выплат в рамках программы Money Transfer платёжной системы Visa должна указываться информация о местонахождении получателя, если карта получателя выпущена в Канаде — если эти сведения не указаны в запросе на открытие платёжной формы, пользователю отображается дополнительная страница с полями для их указания.

  С вопросами о специфике проведения выплат в различных регионах и с учётом различных факторов можно обращаться к курирующему менеджеру ecommpay.

• При вызове платёжной формы не должна использоваться возможность ограничения времени работы с ней (подробнее); время работы с платёжной формой при проведении выплат ограничено по умолчанию и соответствует времени, остающемуся до окончания срока действия идентификатора uuid.

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

Подключение

Чтобы подключить возможность проведения выплат с использованием Payment Page, со стороны мерчанта необходимо:

1. Согласовать с курирующим менеджером ecommpay подключение этой возможности, необходимость её тестирования и применение ограничений в каждом конкретном случае.
2. Если была согласована необходимость тестирования, получить от специалистов ecommpay уведомление о готовности к тестированию, проверить работу платёжной формы с использованием этой возможности и сообщить о готовности к запуску.
3. Получить от специалистов ecommpay уведомление о подключении возможности.

Схема работы

Для проведения выплаты с использованием Payment Page со стороны веб-сервиса необходимо:

1. Сформировать и отправить в платёжную платформу запрос на регистрацию выплаты.
2. Принять от платформы оповещение о регистрации выплаты.
3. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page в режиме Payout.
4. Принять от платформы оповещение о результате платежа.

При проведении выплат может выполняться дополнение информации о платеже, в рамках которого пользователю отображаются дополнительные поля, которые требуется заполнить здесь же, в платёжной форме. Эта процедура выполняется без участия веб-сервиса мерчанта, но требует участия пользователя.

Формат запроса на регистрацию выплаты

При работе с запросами на регистрацию выплат необходимо учитывать следующее:

1. Для регистрации каждый выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/payout/registration.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным);
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;
     • email — адрес электронной почты пользователя;
     • phone — номер телефона пользователя;
     • ip_address — IP-адрес пользователя, актуальный для регистрируемой выплаты.

Таким образом, корректный запрос на регистрацию выплаты должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, контактные данные пользователя (адрес электронной почты и номер телефона), а также подпись.

  "general": {
    "project_id": 91348,
    "payment_id": "cosmoshop_payout_1323",
    "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer": {
    "id": "16061314",
    "email": "p.jeltz@mail.com",
    "phone": "44991234567",  
    "ip_address": "93.47.230.225"
  },
  "payment": {
    "amount": 7000,
    "currency": "EUR"
  }
}

Формат оповещения о результате регистрации выплаты

При проведении каждой выплаты с использованием Payment Page необходимо принять промежуточное оповещение от платёжной платформы о результате регистрации выплаты и использовать идентификатор, передаваемый в параметре uuid. Формат таких оповещений является типовым (подробнее).

В следующем примере содержится информация о том, что в рамках проекта 91348 для пользователя 16061314 была зарегистрирована выплата.

{
    "general": {
        "project_id": "91348",
        "payment_id": "cosmoshop_payout_1323",
        "signature": "V2mxcUcGUcCtAE51lgesBefZgfG9NHpQEbfdI2X1Q=="
    },
    "request_id": "50715",
    "payment": {
        "id": "cosmoshop_payout_1323",
        "type": "payout",
        "status": "awaiting_payout_completion",
     },
    "operation": {
        "id": "500359719",
        "type": "payout",
        "status": "awaiting_payout_completion"
    },
    "customer": {
        "id": "16061314"
    },
    "sum_request":
    {
        "amount": "7000",
        "currency": "EUR"
    },
    "transaction": {
        "type": "payout"
    },
    "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==",
    "uuid_expired_at": "2024-04-24T13:50:37+0000"
}

Формат запроса на открытие платёжной формы

Формат запроса на открытие Payment Page для проведения выплаты с использованием платёжной карты соответствует описанному в статье Организация взаимодействия. При формировании такого запроса необходимо учитывать следующее:

1. В запросе должны использоваться следующие обязательные параметры:
   • mode — индикатор режима работы Payment Page, для которого следует указывать значение payout;
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, соответствующий указанному в запросе на регистрацию выплаты и уникальный в рамках проекта;
   • uuid — идентификатор выплаты, полученный в оповещении о результате регистрации;
   • customer_id — идентификатор пользователя, соответствующий указанному в запросе на регистрацию выплаты и уникальный в рамках проекта;
   • customer_email — адрес электронной почты пользователя, соответствующий указанному в запросе на регистрацию выплаты;
   • payment_amount — сумма платежа, соответствующая указанной в запросе на регистрацию выплаты, в дробных единицах валюты;
   • payment_currency — код валюты платежа, соответствующий указанному в запросе на регистрацию выплаты, в формате ISO 4217 alpha-3;
   • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
2. Должен использоваться базовый минимум параметров: mode (payout), project_id, payment_id, uuid, payment_currency, payment_amount, customer_id, customer_email, signature.
3. Для использования токена платёжной карты, предварительно выбранной пользователем в веб-сервисе, этот токен должен указываться в параметре account_token.
4. Для указания сведений об отправителе выплаты могут использоваться следующие параметры:
   • sender_wallet_id — номер (идентификатор) кошелька отправителя.
   • sender_first_name — имя отправителя.
   • sender_last_name — фамилия отправителя.
   • sender_country — код страны местонахождения отправителя в формате ISO 3166-1 alpha-2.
   • sender_state — внутренний код территории местонахождения отправителя (штата, провинции, региона или иной территориальной области). Этот код; представляет собой вторую часть международного кода территории (в формате ISO 3166-2), без двухбуквенного кода страны и разделительного дефиса. Например, ON для провинции Онтарио в Канаде (с международным кодом CA-ON).
   • sender_city — название города местонахождения отправителя.
   • sender_address — название улицы и номер дома местонахождения отправителя.
   • sender_zip — почтовый индекс местонахождения отправителя.
5. Для указания сведений о получателе выплаты могут использоваться следующие параметры:
   • recipient_first_name — имя получателя.
   • recipient_last_name — фамилия получателя.
   • recipient_country — код страны местонахождения получателя в формате ISO 3166-1 alpha-2.
   • recipient_state — внутренний код территории местонахождения получателя (штата, провинции, региона или иной территориальной области). Этот код; представляет собой вторую часть международного кода территории (в формате ISO 3166-2), без двухбуквенного кода страны и разделительного дефиса. Например, ON для провинции Онтарио в Канаде (с международным кодом CA-ON).
   • recipient_city — название города местонахождения получателя.
   • recipient_address — название улицы и номер дома местонахождения получателя.

   В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, из них обязательны к указанию сведения о местоположении получателя: код страны (recipient_country), название города (recipient_city), название улицы и номер дома (recipient_address) и, если код страны получателя соответствует CA или US, код штата, провинции или территории (recipient_state).

6. Для отображения пользователю платёжной формы на заданном языке код этого языка в формате ISO 639-1 alpha-2 должен указываться в параметре language_code. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически (по языку браузера, языку региона или по умолчанию; подробнее).
7. Для добавления описания платежа, отображаемого пользователю на странице с информацией о результате выплаты и доступного специалистам мерчанта через оповещения и интерфейс Dashboard, в запросе следует использовать параметр payment_description.
8. Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Payout. Полный список параметров вызова Payment Page представлен в статье Параметры вызова платёжной формы.

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

{
   "project_id": "91348",
   "payment_id": "cosmoshop_payout_1323",
   "payment_currency": "EUR",
   "payment_amount": "7000",
   "customer_id": "16061314",
   "customer_email": "p.jeltz@mail.com",  
   "mode": "payout",
   "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5...",
   "signature": "xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB..."

// при проведении выплаты по предварительно выбранной карте:
    "account_token":"959c664ad6045679d71d89caff6c242a0..."

}

Формат оповещения о результате выплаты

Формат оповещения о результатах проведения выплат с использованием платёжных карт соответствует описанному в разделе Работа с оповещениями.