B2B remittances via Gate API

Overview

The following endpoints in the Gate API are used to make B2B payments to partners:

The recipient-account requests are synchronous while the remittance requests are asynchronous. To learn more about these interaction models, see Interaction concepts. To learn more about using signatures, see Signature generation and verification.

This section covers special aspects of sending requests to the B2B remittances endpoints.

Retrieving recipient account data

Requests to retrieve recipient account data should be sent to the /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 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.

To filter recipient account data by recipient account IDs, assigned statuses, or currency, use the id, status, and currency arrays.

Figure 1. Example of the data passed in the request to retrieve recipient account data and the response to it
// 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

Requests to create a recipient account should be sent to the /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.

Figure 2. Example of the data passed in the request to create a recipient account and the response to it
// 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

Requests to update a recipient account should be sent to the /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.

Figure 3. Example of the data passed in the request to update a recipient account
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7,
    "title": "Galaxy catering new"
  }
}

Sending the recipient account for approval

Requests to send the recipient account for approval should be sent to the /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).

Figure 4. Mandatory parameters
  • 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.

A valid send-for-approval request with correct information triggers a 200 OK response. If the information about the recipient account is incomplete or incorrect, the response to such request contains the errors array with either the list of parameters that are missing, or the data that requires correction.

In this case, you should specify the required information using the /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 Information of operations performing.

Figure 5. Example of the data passed in the request to send the account for approval
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7
  }
}
Figure 6. Example of the response if the recipient account does not contain all required information
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":""
    }
  ]
}
Figure 7. Example of the response if the recipient account contains incorrect information
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

Requests to delete a recipient account should be sent to the /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.

Figure 8. Example of the data passed in the request to delete a recipient account
{
  "general": {
    "project_id": 21261,
    "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA=="
  }, 
  "info": {
    "id": 7
  }
}

Sending the remittance request

Requests to create a remittance order should be sent to the /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 request) in the payment object.
Figure 9. Example of the data passed in the remittance request
{
  "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 Callbacks.