# B2B remittances via the Gate API {#en_b2bremit_api} An article about working with accounts of remittance recipients and making B2B payments to corporate partners via the the Gate API. ## Overview {#section_dhv_vgy_dtb .section} The following endpoints in the Gate API are used to make B2B payments to partners: - [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list)—to retrieve information about remittance recipient accounts - [/v2/recipient-account/create](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-create)—to create an account of the remittance recipient - [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update)—to modify information specified in the recipient account draft - [/v2/recipient-account/send-for-approval](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-send-for-approval)—to send the recipient account for approval to Ecommpay - [/v2/recipient-account/delete](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-delete)—to delete the recipient account - [/v2/payment/remittance/external](https://api-developers.ecommpay.com/remittances/post-v2-payment-remittance-external)—to send the remittance request. The `recipient-account` requests are synchronous while the `remittance` requests are asynchronous. To learn more about these interaction models, see [Interaction concepts](en_pp_interaction_organisation.md). To learn more about using signatures, see [Signature generation and verification](en_platform_signature.md). This section covers special aspects of sending requests to the B2B remittances endpoints. ## Retrieving recipient account data {#section_rfv_mhy_dtb .section} Requests to retrieve recipient account data should be sent to the [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list) endpoint. These requests must contain parameters `project_id` \(project ID assigned at the stage of integration\) and `signature`. Responses to such requests contain the information about all recipient accounts structured according to the [RecipientAccount](https://api-developers.ecommpay.com/api.html#/c2NoOjUxMTkxMjY1-recipient-account) model. To filter recipient account data by recipient account IDs, assigned statuses, or currency, use the `id`, `status`, and `currency` arrays. By default, if the request does not contain these arrays, the payment platform returns data for all recipient accounts. Specify recipient account IDs for the accounts you need information on and the status types and currencies in the `id`, `status` and `currency` arrays if you need to pass several values. Separate multiple elements within the arrays by a comma with a space if necessary. If you need to pass a single value, use the `id`, `status`, and `currency` strings. ``` // Request body { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" } // Response body [ { "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" } } ] ``` ## Creating a remittance recipient account {#section_fwq_23y_dtb .section} Requests to create a recipient account should be sent to the [/v2/recipient-account/create](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-create) endpoint. These requests must contain parameters `project_id` and `signature` in the `general` object and the `title` parameter \(the name of the new account\) in the `info` object. In addition, the requests can contain any other significant information about the remittance recipient\(information about the company, payment details and other financial data required to make a B2B payment to the corporate account\). Each response to such requests contains the ID of the created recipient account in the `info` object. ``` // Request body { "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" } } // Response body { "info": { "id": 7 } } ``` ## Modifying information specified in the recipient account draft {#section_jfm_43y_dtb .section} Requests to update a recipient account should be sent to the [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update) endpoint. These requests must contain parameters `project_id` and `signature` in the `general` object and the `id` parameter \(the recipient account ID assigned when the account was created\) in the `info` object. In addition, the requests must contain the information about the remittance recipient\(information about the company, payment details and other financial data required to make a B2B payment to the corporate account\) that needs to be modified. Updating the recipient account triggers a `200 OK` response. ``` { "general": { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "info": { "id": 7, "title": "Galaxy catering new" } } ``` ## Sending the recipient account for approval {#section_ohm_h1p_3tb .section} Requests to send the recipient account for approval should be sent to the [/v2/recipient-account/send-for-approval](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-send-for-approval) endpoint. These requests must contain parameters `project_id` and `signature` in the `general` object and the `id` parameter in the `info` object. Only those accounts for which you have provided all necessary data should be sent for approval. Keep in mind that the currency of the payment and the country of the recipient must be specified in the relevant formats \(see [References](en_directory.md)\). - The `info` object must contain the `title` parameter that specifies the name of the recipient account. - The `recipient_info` object must contain the following parameters: - `beneficiary_account`—account number of the remittance recipient company - `currency`—code of the currency used for making B2B payments \(in the ISO-4217 alpha-3 format\) - `remittance_description`—purpose of payment description - `beneficiary_name`—name of the remittance recipient company - `beneficiary_bank_name`—name of the bank that holds the account of the remittance recipient company - `beneficiary_bank_code`—code of the bank that holds the account of the remittance recipient company - The `remittance_details` object must contain the following parameters: - `monthly_min_amount`—minimum amount of payments over a month - `transfer_max_amount`—maximum amount of a single payment - `remittance_velocity`—expected number of payments over 30 days **Note:** If the specified maximum amount of a single payment and the expected number of payments over 30 days are significantly exceeded, processing the remittance order may take up to 14 business days. To avoid the procedure of additional approval by the Ecommpay specialists, allow some leeway when specifying the values for these parameters. - The `company_info` object must contain the following parameters: - `legal_address`—legal address of the remittance recipient company - `legal_country`—code of the country where the remittance recipient company is registered \(in the ISO 3166-1 alpha-2 format\) - `legal_city`—name of the city where the remittance recipient company is registered A valid `send-for-approval` request with correct information triggers a `200 OK` response. If the information about the recipient account is incomplete, the response to such request contains the `errors` array with the list of parameters that are missing. If the information about the recipient account is incorrect, the response to such request contains the `errors` array specifying the data that requires correction. In this case, you should specify the required information using the [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update) request and then repeat sending the recipient account for approval.If you need to look up the definitions of the received response codes, see [Handling operation processing information](en_platform_payment_info_codes.md). ``` { "general": { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "info": { "id": 7 } } ``` ``` HTTP/1.1 400 Bad Request //response status line ... //header fields { "status":"error", //request processing status "errors":[ //array with the list of the missing required parameters { "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 //response status line ... //header fields { "status":"error", //request processing status "errors":[ //information about parameters that require correction { "code":"2003", "message":"Invalid value for field recipient_info.currency", "field":"recipient_info.currency", "constraint":"" } ] } ``` ## Deleting the remittance recipient account {#section_dv2_1jy_dtb .section} Requests to delete a recipient account should be sent to the [/v2/recipient-account/delete](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-delete) endpoint. These requests must contain parameters `project_id` and `signature` in the `general` object and the `id` parameter in the `info` object. Deleting the recipient account triggers a `200 OK` response. ``` { "general": { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "info": { "id": 7 } } ``` ## Sending the remittance request {#section_zkk_njy_dtb .section} Requests to create a remittance order should be sent to the [/v2/payment/remittance/external](https://api-developers.ecommpay.com/remittances/post-v2-payment-remittance-external) endpoint. Keep in mind that remittance orders can be created only for approved recipient accounts that are not expired\(and these accounts are assigned the **Active** status\). These requests must contain the following parameters: - `id` \(the recipient account ID assigned when the account was created\) in the `recipient` object. - `project_id`, `payment_id`, and `signature` in the `general` object. - `amount`, `currency`, and `payment_method_alias` \(the payment amount, currency, and the ID of the payment method that is sourced from the `payment_methods` array sent in the response to the [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list) request\) in the `payment` object. ``` { "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 } } ``` To communicate the remittance payment results, standard callbacks are used. To learn more, see [Handling callbacks](en_platform_callbacks.md). **Parent topic:**[B2B Remittances](en_b2bremit_about.md)