Работа через Gate API

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

Для использования функциональности выплат на счета юридических лиц в Gate API доступны следующие конечные точки:

Запросы категории recipient-account для работы с данными о получателях выплат выполняются в рамках синхронной схемы взаимодействия, а запросы категории remittance на создание платёжных поручений на выплаты — в рамках асинхронной. Информация о работе по этим схемам представлена в статье Организация взаимодействия, а информация о формировании подписи — в статье Работа с подписью.

В этом разделе описаны особенности запросов к указанным конечным точкам.

Получение данных о партнёрах

Для получения данных из карточек партнёров следует отправлять запросы к конечной точке /v2/recipient-account/list. В этих запросах должны указываться параметры project_id (идентификатор проекта, полученный при интеграции) и signature (подпись). В ответах на такие запросы содержатся сведения из всех имеющихся карточек партнёров в соответствии с моделью RecipientAccount.

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

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

Рис. 1. Пример данных из запроса на получение данных о карточках и ответа на этот запрос
// Тело запроса
{
     "project_id": 21261,
     "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }
// Тело ответа
[
  {
    "general": {
      "project_id": 21261
    },
    "info": {
      "id": 3,
      "title": "Galaxy catering",
      "status": "expired",
      "exp_date": "2021-10-31",
      "created_date": "2021-09-27 15:24:00",
      "updated_date": "2021-09-27 15:24:00"
    },
    "recipient_info": {
      "beneficiary_account": "1242424225621221",
      "currency": "GBP",
      "remittance_description": "Catering Pluto locations",
      "beneficiary_name": "Grebulon",
      "beneficiary_bank_name": "Taurus bank",
      "beneficiary_bank_code": "3244232",
      "beneficiary_bank_country": "PL",
      "recipient_bank_address": "Tombaugh Regio, Astrid colles, 457" 
    },
    "remittance_details": {
      "monthly_min_amount": 22000,
      "transfer_max_amount": 2000,
      "remittance_velocity": 10,
      "during_days": 30
    },
    "payment_methods": [
      "bank-transfer/world"
    ],
    "company_info": {
      "legal_address": "Rupert",
      "legal_country": "RP",
      "legal_city": "Rupert",
      "zip_code": "101010"
    }
  },
  {
    "general": {
      "project_id": 21261
    },
    "info": {
      "id": 7,
      "title": "Galaxy catering",
      "status": "created",
      "exp_date": "0000-00-00",
      "created_date": "2021-09-01 10:58:36",
      "updated_date": "2021-09-01 10:58:36"
    },
    "recipient_info": {
      "beneficiary_account": "1242424225621221",
      "currency": "EUR",
      "remittance_description": "Catering Rupert locations",
      "beneficiary_name": "Grebulon",
      "beneficiary_bank_name": "Random bank",
      "beneficiary_bank_code": "13243532",
      "beneficiary_bank_country": "RP",
      "recipient_bank_address": "Lila ice plain, 324"
      "
    },
    "remittance_details": {
      "monthly_min_amount": 2099,
      "transfer_max_amount": 3099,
      "remittance_velocity": 30,
      "during_days": 30
    },
    "payment_methods": [
      "bank-transfer/world"
    ],
    "company_info": {
      "legal_address": "Rupert",
      "legal_country": "RP",
      "legal_city": "Rupert"
    }
  }
]

Создание карточки партнёра

Для создания карточек партнёров следует отправлять запросы к конечной точке /v2/recipient-account/create. В каждом из таких запросов должны указываться параметры project_id и signature в объекте general и параметр title (название создаваемой карточки) в объекте info. Также в таких запросах можно указывать остальные сведения о партнёре — получателе выплаты (сведения о компании, реквизиты и прочие финансовые детали, необходимые для проведения выплаты юридическому лицу). В ответе на каждый из таких запросов содержится идентификатор созданной карточки партнёра в объекте info.

Рис. 2. Пример данных из запроса на создание карточки и ответа на этот запрос
// Тело запроса
{
  "general": {
     "project_id": 21261,
     "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
     "title": "Galaxy catering"
  },
  "recipient_info": {
     "beneficiary_account": "1242424225621221",
     "currency": "EUR",
     "remittance_description": "Catering Rupert locations",
     "beneficiary_name": "Grebulon",
     "beneficiary_bank_name": "Random bank",
     "beneficiary_bank_code": "13243532"
  },
  "remittance_details": {
     "monthly_min_amount": 2099,
     "transfer_max_amount": 3099,
     "remittance_velocity": 30,
     "during_days": 30
  },
  "company_info": {
     "legal_address": "Rupert",
     "legal_country": "RP",
     "legal_city": "Rupert"
  }
}
// Тело ответа
{
  "info": {
      "id": 7
  }  
}

Изменение данных в черновике карточки партнёра

Для обновления данных в карточках со статусом Draft следует отправлять запросы к конечной точке /v2/recipient-account/update. В каждом из таких запросов должны указываться параметры project_id и signature в объекте general и параметр id (идентификатор карточки, присвоенный при её создании) в объекте info. Также в таких запросах следует указывать данные о получателе выплаты (сведения о компании, а также реквизиты и прочие финансовые детали, необходимые для проведения выплаты юридическому лицу), которые необходимо изменить. После обновления данных в карточке партнёра отправляется ответ с кодом 200 OK.

Рис. 3. Пример данных из запроса на обновление карточки
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7,
    "title": "Galaxy catering new"
  }
}

Отправка карточки партнёра на рассмотрение

Для отправки карточек на рассмотрение в ecommpay следует отправлять запросы к конечной точке /v2/recipient-account/send-for-approval . В каждом из таких запросов должны указываться параметры project_id и signature в объекте general и параметр id в объекте info. На рассмотрение следует отправлять карточки со всеми данными, указание которых является обязательным. При этом сведения о валюте выплат и стране получателя должны передаваться в форматах, указанных в Справочниках.

Рис. 4. Обязательные параметры
  • В объекте info должен быть передан параметр title с названием карточки.
  • В объекте recipient_info должны быть переданы следующие параметры:
    • beneficiary_account — номер счёта компании-партнёра;
    • currency — код валюты для проведения платежей (в формате ISO-4217 alpha-3);
    • remittance_description — назначение платежей;
    • beneficiary_name — название компании-партнёра;
    • beneficiary_bank_name — название банка, в котором открыт счёт компании-партнёра;
    • beneficiary_bank_code — код банка, в котором открыт счёт компании-партнёра.
  • В объекте remittance_details должны быть переданы следующие параметры:
    • monthly_min_amount — минимальная сумма выплат в месяц;
    • transfer_max_amount — максимальная сумма разовой выплаты;
    • remittance_velocity — планируемое количество выплат в течение 30 дней.
    Прим.: При существенном превышении максимальной суммы разовой выплаты и запланированного количества выплат для проведения платежа может требоваться до 14 рабочих дней. Во избежание процедуры дополнительного одобрения со стороны ecommpay рекомендуется устанавливать ограничения с соответствующими запасами.
  • В объекте company_info должны быть переданы следующие параметры:
    • legal_address — юридический адрес компании-партнёра;
    • legal_country — код страны, где зарегистрирована компания-партнёр (в формате ISO 3166-1 alpha-2);
    • legal_city — название города, в котором зарегистрирована компания-партнёр.

Если полученный запрос на отправку карточки корректен, от платформы возвращается ответ с кодом 200 OK. Если данные представлены в карточке не полностью, в ответе на запрос отправки карточки на рассмотрение в массиве errors содержится список недостающих параметров. Если в карточке содержатся некорректные данные, в ответе на такой запрос в массиве errors передаётся информация о неверно указанном параметре.

Если полученный запрос на отправку карточки корректен, от платформы возвращается ответ с кодом 200 OK. Если данные представлены в карточке не полностью или они некорректны, в ответе на такой запрос в массиве errors передаётся либо список недостающих параметров, либо информация о неверно указанных параметрах.

В таких случаях можно указать недостающие параметры или передать корректную информацию, используя запрос к конечной точке /v2/recipient-account/update, и повторно отправить карточку на рассмотрение. Информацию о передаваемых кодах ответов на запросы следует уточнять в статье Информация об операциях.

Рис. 5. Пример данных из запроса на отправку карточки
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7
  }
}
Рис. 6. Пример ответа на запрос, если в карточке не указаны все необходимые параметры
HTTP/1.1 400 Bad Request                              //стартовая строка ответа
...                                                   //поля заголовка
{
  "status":"error",                                   //статус обработки запроса
  "errors":[                          //массив со списком необходимых параметров
    {
      "code":"2003",                                     
      "message":"Must be at least 4 characters long",
      "field":"recipient_info.beneficiary_account",
      "constraint":""
    },
    {
      "code":"2003",                                     
      "message":"Must have a minimum value of 1",
      "field":"remittance_details.monthly_min_amount",
      "constraint":""
    }
  ]
}
Рис. 7. Пример ответа на запрос, если в карточке указаны некорректные данные
HTTP/1.1 400 Bad Request                              //стартовая строка ответа
...                                                   //поля заголовка
{
  "status":"error",                                   //статус обработки запроса
  "errors":[                                  //информация о некорректных данных
    {
      "code":"2003",                                     
      "message":"Invalid value for field recipient_info.currency",
      "field":"recipient_info.currency",
      "constraint":""
    }
  ]
}

Удаление карточки партнёра

Для удаления карточек с любым из присвоенных статусов, кроме статуса Created, следует отправлять запросы к конечной точке /v2/recipient-account/delete. В каждом из таких запросов должны указываться параметры project_id и signature в объекте general и параметр id в объекте info. По удалении карточки партнёра отправляется ответ с кодом 200 OK.

Рис. 8. Пример данных из запроса на удаление карточки
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7
  }
}

Отправка запроса на выплату

Чтобы создавать платёжные поручения на выплаты юридическим лицам, следует отправлять запросы к конечной точке /v2/payment/remittance/external. Необходимо помнить, что заявки на выплату можно создавать только для получателей, карточки которых одобрены и их срок действия не истёк (что подтверждается статусом Active). В каждом из таких запросов должны указываться:

  • параметр id (идентификатор карточки получателя платежа) в объекте recipient;
  • параметры project_id, payment_id и signature в объекте general;
  • параметры amount, currency и payment_method_alias (сумма и валюта платежа, а также идентификатор платёжного метода из массива payment_methods, переданного в ответе на запрос категории /v2/recipient-account/list) в объекте payment.
Рис. 9. Пример данных из запроса на выплату
{
  "general": {
    "project_id": 21261,
    "payment_id": "galaxy_catering_0001",
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  },
  "payment": {
    "amount": 234,
    "currency": "EUR",
    "payment_method_alias": "bank-transfer/world",
    "description": "Catering Mars locations"
  },
  "recipient": {
    "id": 7
  }
}

Информация о результатах проведения выплат передаётся в оповещениях типового формата, описание которых представлено в статье Оповещения.