# Работа через Gate API {#ru_b2bremit_api}

статья о порядке работы с карточками партнёров и выплатами партнёрам через интерфейс Gate API

## Общая информация {#section_dhv_vgy_dtb .section}

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

-   [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list) — для получения данных из карточек партнёров;
-   [/v2/recipient-account/create](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-create) — для создания карточки партнёра — получателя выплаты;
-   [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update) — для изменения данных в черновике карточки партнёра;
-   [/v2/recipient-account/send-for-approval](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-send-for-approval) — для отправки карточки партнёра на рассмотрение в Ecommpay;
-   [/v2/recipient-account/delete](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-delete) — для удаления карточки партнёра;
-   [/v2/payment/remittance/external](https://api-developers.ecommpay.com/remittances/post-v2-payment-remittance-external) — для отправки запроса на выплату.

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

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

## Получение данных о партнёрах {#section_rfv_mhy_dtb .section}

Для получения данных из карточек партнёров следует отправлять запросы к конечной точке [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list). В этих запросах должны указываться параметры `project_id` \(идентификатор проекта, полученный при интеграции\) и `signature` \(подпись\). В ответах на такие запросы содержатся сведения из всех имеющихся карточек партнёров в соответствии с моделью [RecipientAccount](https://api-developers.ecommpay.com/api.html#/c2NoOjUxMTkxMjY1-recipient-account).

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

```
// Тело запроса
{
     "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"
    }
  }
]
```

## Создание карточки партнёра {#section_fwq_23y_dtb .section}

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

```
// Тело запроса
{
  "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
  }  
}
```

## Изменение данных в черновике карточки партнёра {#section_jfm_43y_dtb .section}

Для обновления данных в карточках со статусом **Draft** следует отправлять запросы к конечной точке [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update). В каждом из таких запросов должны указываться параметры `project_id` и `signature` в объекте `general` и параметр `id` \(идентификатор карточки, присвоенный при её создании\) в объекте `info`. Также в таких запросах следует указывать данные о получателе выплаты\(сведения о компании, а также реквизиты и прочие финансовые детали, необходимые для проведения выплаты юридическому лицу\), которые необходимо изменить. После обновления данных в карточке партнёра отправляется ответ с кодом `200 OK`.

```
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7,
    "title": "Galaxy catering new"
  }
}
```

## Отправка карточки партнёра на рассмотрение {#section_ohm_h1p_3tb .section}

Для отправки карточек на рассмотрение в Ecommpay следует отправлять запросы к конечной точке [/v2/recipient-account/send-for-approval](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-send-for-approval) . В каждом из таких запросов должны указываться параметры `project_id` и `signature` в объекте `general` и параметр `id` в объекте `info`. На рассмотрение следует отправлять карточки со всеми данными, указание которых является обязательным. При этом сведения о валюте выплат и стране получателя должны передаваться в форматах, указанных в [Справочниках](ru_directory.md).

-   В объекте `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` передаётся информация о неверно указанном параметре.

В таких случаях можно указать недостающие параметры или передать корректную информацию, используя запрос к конечной точке [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update), и повторно отправить карточку на рассмотрение.Информацию о передаваемых кодах ответов на запросы следует уточнять в статье [Работа с информацией об операциях](ru_platform_payment_info_codes.md).

```
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7
  }
}
```

```
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":""
    }
  ]
}    
```

```
HTTP/1.1 400 Bad Request                              //стартовая строка ответа
...                                                   //поля заголовка
{
  "status":"error",                                   //статус обработки запроса
  "errors":[                                  //информация о некорректных данных
    {
      "code":"2003",                                     
      "message":"Invalid value for field recipient_info.currency",
      "field":"recipient_info.currency",
      "constraint":""
    }
  ]
}    
```

## Удаление карточки партнёра {#section_dv2_1jy_dtb .section}

Для удаления карточек с любым из присвоенных статусов, кроме статуса **Created**, следует отправлять запросы к конечной точке [/v2/recipient-account/delete](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-delete). В каждом из таких запросов должны указываться параметры `project_id` и `signature` в объекте `general` и параметр `id` в объекте `info`. По удалении карточки партнёра отправляется ответ с кодом `200 OK`.

```
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7
  }
}

```

## Отправка запроса на выплату {#section_zkk_njy_dtb .section}

Чтобы создавать платёжные поручения на выплаты юридическим лицам, следует отправлять запросы к конечной точке [/v2/payment/remittance/external](https://api-developers.ecommpay.com/remittances/post-v2-payment-remittance-external). Необходимо помнить, что заявки на выплату можно создавать только для получателей, карточки которых одобрены и их срок действия не истёк\(что подтверждается статусом **Active**\). В каждом из таких запросов должны указываться:

-   параметр `id` \(идентификатор карточки получателя платежа\) в объекте `recipient`;
-   параметры `project_id`, `payment_id` и `signature` в объекте `general`;
-   параметры `amount`, `currency` и `payment_method_alias` \(сумма и валюта платежа, а также идентификатор платёжного метода из массива `payment_methods`, переданного в ответе на запрос категории [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list)\) в объекте `payment`.

```
{
  "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
  }
}
```

Информация о результатах проведения выплат передаётся в оповещениях типового формата, описание которых представлено в статье [Работа с оповещениями](ru_platform_callbacks.md).

**На уровень выше:**[B2B-выплаты](ru_b2bremit_about.md)