# Register shop

Register a new shops into Ratepay system. It is mandatory to register the shop before submitting payment requests.

Endpoint: POST /v2/partners/{partner_profile_id}/shops
Version: 2.0
Security: Bearer Authentication

## Path parameters:

  - `partner_profile_id` (string, required)
    ID of the partner profile under which the new shop is to be registered.
    Example: "DE_PARTNER_ID_PR"

## Request fields (application/json):

  - `shop_id` (string, required)
    The unique identifier of a new shop, provided by the partner.
    Example: "acbd18db4cc2f85cedef654fccc4a4d8"

  - `name` (string, required)
    Shop name. Required for the buyer communication.
    Example: "Animals GmbH"

  - `website` (string)
    URL to the shop's website, used in the buyer communication.
    Example: "https://animals.com"

  - `address` (object, required)
    Address details of merchant/shop.

  - `address.street` (string, required)
    Street name.
    Example: "Ollenhauer Str."

  - `address.street_number` (string)
    House number.
    Example: "17A"

  - `address.street_additional` (string)
    Additional details to address line.

  - `address.city` (string, required)
    City name.
    Example: "Stuttgart"

  - `address.postal_code` (string, required)
    Postal code.
    Example: "70599"

  - `address.country_code` (string, required)
    Country code in ISO 3166-1 (alpha-2) format, e.g. DE, CH, NL, etc.
    Example: "DE"

  - `legal` (object, required)
    Legal details of merchant/shop.

  - `legal.name` (string, required)
    Official merchant company name.
    Example: "Animal House"

  - `legal.legal_form` (string, required)
    Legal form of the merchant or shop, e.g Ltd., GmbH, etc.
    Example: "GmbH"

  - `legal.commercial_register_number` (string, required)
    Merchant company's registration number, e.g. HRB 124156B
    Example: "124156 B"

  - `legal.registration_office` (string, required)
    Registrar of merchant company, e.g. Amtsgericht Charlottenburg (Berlin)
    Example: "Amtsgericht Charlottenburg (Berlin)"

  - `legal.vat_id_number` (string, required)
    Merchant company's VAT number, e.g. DE 270 098 222. Either vat_id_number or tax_number is mandatory.
    Example: "DE817154243.B.01"

  - `legal.tax_number` (string, required)
    Merchant company's tax number. Either vat_id_number or tax_number is mandatory.
    Example: "817154243"

  - `legal.board_chairman` (string)
    Chairman of merchant's supervisory board.
    Example: "Katja Löwe"

  - `legal.managing_directors` (string)
    Merchant company's management board.
    Example: "Ingrid Fellnase, Jens Kater, Tom Mieze"

  - `legal.designation_of_management` (string)
    Type of the merchant's management board, e.g. Geschäftsführung. Mandatory if managing_directors are given.
    Example: "Geschäftsführung"

  - `contacts` (object)
    Contact options used by Ratepay to contact the merchant, shop or partner.
    Example: {"customer_service":{"email":"support@cats.de"},"fraud":{"email":"fraud@cats.de"},"incident":{"email":"incident@cats.de"},"data_protection":{"email":"privacy@cats.de"},"invoice_copy":{"email":"support@cats.de"}}

  - `contacts.customer_service` (object)
    Contact details of the shop's customer service.

  - `contacts.customer_service.email` (string, required)
    Example: "support@cats.de"

  - `contacts.customer_service.phone` (string)
    Example: "+49 (0)85 888 8138"

  - `contacts.customer_service.fax` (string)
    Example: "+49 (0)85 888 8199"

  - `contacts.fraud` (object)
    Contact details in case of fraud.

  - `contacts.incident` (object)
    Contact details in case of technical incidents.

  - `contacts.data_protection` (object)
    Contact details in case of privacy compliance.

  - `contacts.invoice_copy` (object)
    Blind copy (BCC) email address for invoice correspondences. Shops can provide it to receive copies of the invoices sent to their buyers. For this contact option only email is allowed.

  - `correspondence_settings` (object)
    Configuration of correspondences for the buyer communication.

  - `correspondence_settings.branding_settings` (object)
    Appearance options for the buyer correspondences. e.g. shop logo position and highlight color.

  - `correspondence_settings.branding_settings.logo_position` (string)
    Shop logo position in buyer correspondences.
    Enum: "LEFT", "CENTER", "RIGHT"

  - `correspondence_settings.branding_settings.highlight_color` (string)
    The color for the highlighted elements in buyer correspondences as HTML HEX color code, e.g #BADB11
    Example: "#BADB01"

  - `correspondence_settings.slang` (object)
    Slang definition for the buyer correspondences.
    Example: {"de":{"salutation":"Guten Tag","order":"BOOKING","name_format":"LAST_NAME","formal_tone":"FORMAL","customer_service_contact":["Hotline: 0800 1234 1234 (29ct/min aus dt. Netz)","Fax: +49 (30) 1234567-10"]},"en":{"salutation":"Hello","order":"ORDER","name_format":"FIRST_NAME","formal_tone":"INFORMAL","customer_service_contact":["Office Hours: 10:00 - 18:00"]}}

  - `correspondence_settings.slang.en` (object)

  - `correspondence_settings.slang.en.salutation` (string)
    Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.
    Example: "Hello"

  - `correspondence_settings.slang.en.order` (string)
    The type of order.
    Enum: "ORDER", "BOOKING"

  - `correspondence_settings.slang.en.formal_tone` (string)
    Formality level for the buyer correspondences.
    Enum: "FORMAL", "INFORMAL"

  - `correspondence_settings.slang.en.name_format` (string)
    Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.
    Enum: "FIRST_NAME", "LAST_NAME", "FIRST_LAST_NAME"

  - `correspondence_settings.slang.en.customer_service_contact` (array)
    Additional lines in buyer correspondences referring to the  customer service contact details of the shop, merchant or partner.
    Example: [{"Hotline":"0800 1234 1234 (29ct/min Germany)"},{"Office Hours":"10:00 - 18:00 mo-sa"},{"Fax":"+49 (30) 1234567-10"}]

  - `correspondence_settings.slang.de` (object)

  - `correspondence_settings.slang.nl` (object)

  - `correspondence_settings.payment_method_specific` (array)
    Within this array you can configure the settings for specific correspondences. You can choose the set of correspondences to be sent by Ratepay. Additionally you can specify their branding (Ratepay or shop branding). The correspondence specifications are grouped by payment method.All correspondences, except of invoices, are sent by Ratepay per default. All correspondences, except of dunning_3 are sent in shop branding.
    Example: [{"payment_method":{"payment_option":"OPEN_INVOICE","transfer_type":"BANK_TRANSFER"},"invoice":{"skip_sending":false,"shop_branding":true},"deposit_confirmation":{"skip_sending":false,"shop_branding":true},"dunning_1":{"skip_sending":false,"shop_branding":true},"dunning_2":{"skip_sending":false,"shop_branding":true},"dunning_3":{"skip_sending":false,"shop_branding":true}},{"payment_method":{"payment_option":"INSTALMENT","transfer_type":"DIRECT_DEBIT"},"invoice":{"skip_sending":true,"shop_branding":true},"deposit_confirmation":{"skip_sending":false,"shop_branding":true},"dunning_1":{"skip_sending":false,"shop_branding":true},"dunning_2":{"skip_sending":false,"shop_branding":true},"dunning_3":{"skip_sending":false,"shop_branding":true}}]

  - `correspondence_settings.payment_method_specific.payment_method` (object)
    Ratepay payment methods consists of the parameters payment_option and transfer_type.

  - `correspondence_settings.payment_method_specific.payment_method.payment_option` (string)
    Payment option.
    Enum: "OPEN_INVOICE", "PREPAYMENT", "INSTALMENT"

  - `correspondence_settings.payment_method_specific.payment_method.transfer_type` (string)
    Payment transfer type.
    Enum: "BANK_TRANSFER", "DIRECT_DEBIT"

  - `correspondence_settings.payment_method_specific.invoice` (object)
    Official invoice, sent with every delivery. The invoice is skipped by default.

  - `correspondence_settings.payment_method_specific.invoice.skip_sending` (boolean)
    Whether the correspondence should be sent by Ratepay. If true, the correspondence won't be sent by Ratepay. The default value is true.

  - `correspondence_settings.payment_method_specific.invoice.shop_branding` (boolean)
    Whether the correspondence should be branded with shop details e.g. logo, colors, etc. If true, the correspondence will be sent following the branding_settings for this merchant/shop. The default value is true.
    Example: true

  - `correspondence_settings.payment_method_specific.payment_instruction` (object)
    Instructions with payment details, open amount, and due date, sent with every delivery.

  - `correspondence_settings.payment_method_specific.payment_receipt` (object)
    Payment confirmation, sent after every payment.

  - `correspondence_settings.payment_method_specific.dunning_1` (object)
    Friendly payment reminder, sent after the original due date is exceeded.

  - `correspondence_settings.payment_method_specific.dunning_2` (object)
    First payment reminder with a dunning fee. In this correspondence, Ratepay comes to the fore, even though the design is shop branded by default.

  - `correspondence_settings.payment_method_specific.dunning_3` (object)
    Last payment reminder. The design is in Ratepay branding, regardless of the shop_branding setting.

  - `correspondence_settings.payment_method_specific.advance_notice` (object)
    Notification for an upcoming direct debit withdrawal. Warning: There is a legal obligation to send such correspondence before the direct debit withdrawal. If you skip this correspondence, make sure to send a replacement for it.

  - `correspondence_settings.payment_method_specific.order_confirmation` (object)
    An email with general information about a purchase with instalment option. It is sent  after the purchase.

  - `correspondence_settings.payment_method_specific.initial_plan` (object)
    Initial instalment plan. Contains, details of the deliveries, an overview of the instalment plan, and instructions for the monthly payments.

  - `correspondence_settings.payment_method_specific.updated_plan` (object)
    Updated instalment plan. This email is sent, if there was additional delivery, unplanned payment, or change in the ordered items. It contains updated payment instructions for the monthly payments.

  - `correspondence_settings.payment_method_specific.advance_notice_sepa_update` (object)
    Notification for an upcoming direct debit withdrawal. Unlike the advance_notice, this email is sent after a buyer changed their SEPA bank connection. Warning: There is a legal obligation to send such correspondence before the direct debit withdrawal. If you skip this correspondence, make sure to send a replacement for it.

## Response 200 fields (application/json):

  - `shop_id` (string)
    Example: "acbd18db4cc2f85cedef654fccc4a4d8"

## Response 400 fields (application/json):

  - `message` (string)
    Example: "Mandatory information missing."

  - `errors` (object)
    Example: "The given data was invalid."

  - `errors.field_name` (array)

## Response 404 fields (application/json):

  - `message` (string)
    Example: "Partner with profileId[PROFILE_ID] not found"

## Response 409 fields (application/json):

  - `message` (string)
    Example: "Unable to create shop due to conflicts. Field shop_id should be unique."