Skip to content
Relay

    Create merchant

    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:

    • the 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 true for certain payment methods. (More here).

    • merchant_data. Can be null if enabled_for_consolidated_payout:false. (More here).

    Consolidated payout

    Direct payout vs consolidated payout

    There are two ways of setting up the payouts for your merchant:

    direct payout: 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.

    consolidated payout: 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.

    The enabled_for_consolidated_payout value can be changed later by sending the merchant services UpdateRequest.

    Merchant data

    If the enabled_for_consolidated_payout value is set to false the merchant_data field can be set to null.


    The 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:

    • INDIVIDUAL;
    • ORGANIZATIONAL;
    • PARTNERSHIP;
    • NON_PROFIT_ORGANIZATION

    Create Merchant Response

    If successful, the CreateResponse contains the merchant_id and a status.

    🎉

    You now have received a valid merchant_id. This enables you to perform additional actions for that merchant.

    Additional actions

    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_id and get the merchant_data and 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).

    The merchant_id is valid for all Relay services.