This guide walks you through the process of adding (creating) merchants to our system. As a result, you will receive the merchant_id, which is necessary for all actions you want to take on that merchant.
Before you start
Please note that at at this point you MUST have subscribed to the relevant notifications.
You also MUST have the required merchant information. We will describe what information is needed in this section.
Create merchant request
To create a merchant, you use Relay's Merchant Service. You can find the service definitions in the corresponding .proto file and in our API reference.
To create a merchant, you send the Merchant Service's CreateRequest call. If successful, you will receive the
merchant_id in the Create method's response. This
merchant_id is required for any future action for that merchant.
With the CreateRequest call, you send:
reference: a string (limited to 36 alphanumeric characters) that you can use for your own reference. t's a good practice, to populate this field with your own system's merchant reference.
enabled_for_consolidated_payout: boolian. Required to be
truefor certain payment methods. (More here).
merchant_data. Can be
enabled_for_consolidated_payout:false. (More here).
Direct payout vs consolidated payout
There are two ways of setting up the payouts for your merchant:
enabled_for_consolidated_payout:false - the merchants receive their funds directly from the involved payment service provider. We are not involved in processing these payouts.
enabled_for_consolidated_payout:true - our processing of the payment includes collecting and we consolidate the payouts to the merchant. For the merchant that brings benefits for example when organising their accounting and when they want to consistently refer to incoming payments.
Some of the available payment methods are only available for consolidated payouts. Here, the
enabled_for_consolidated_payout value MUST be
true. Please check our Add payment method section whether this is the case for your desired payment method - payment method provider combination.
We need merchant_data for consolidated payouts
For us, if set to
true, additional vetting of the merchant is necessary. As a consequence it might take longer for you to get a success response. Also, in the
true case, the
merchant_data field (see below) is required.
Alternately, if the processing does not include collecting, the value MAY be set to
false: the settlement has to be done with the payment provider directly, independently of us. In that case the
merchant_data field (see below) MAY be NULL.
Some payment methods require consolidated payouts
A merchant with
enabled_for_consolidated_payout:true is qualified for all payment methods. A merchant with
enabled_for_consolidated_payout:false can't use certain payment methods.
enabled_for_consolidated_payout value can be changed later by sending the merchant services UpdateRequest.
enabled_for_consolidated_payout value is set to
merchant_data field can be set to
merchant_data field expects a structured object which contains more structured objects.
Please find a complete list of the required values for
merchant_data in our API reference.
Please note that the
LegalEntityType field expects one of the following values:
Create Merchant Response
If successful, the
CreateResponse contains the
merchant_id and a
You now have received a valid
merchant_id. This enables you to perform additional actions for that merchant.
Once you've received the
merchant_id you can perform additional actions from the Merchant Service (and other Relay services) such as:
- GetRequest - you send the
merchant_idand get the
merchant_dataand additional information about the merchant
- UpdateRequest - allows you to update existend merchant information (overwrite)
- EnableRequest - Enables a merchant who is disabled
- DisableRequest - Disables a merchant who is enabled
Please find detailed information about these messages in our API reference (Merchant Service).
merchant_id is valid for all Relay services.