{
"openapi": "3.0.1",
"info": {
"title": "Ratepay Merchant Registration API",
"version": "2.0",
"description": "The Ratepay Merchant Registration API allows a fast, easy and automatable registration process for new shops.
After a successful registration shops should be able to use all configured payment methods for used partner profile-id."
},
"servers": [
{
"url": "https://api.ratepay.com/merchant/registry",
"description": "Production environment"
},
{
"url": "https://api-integration.ratepay.com/merchant/registry",
"description": "Test environment"
}
],
"security": [
{
"Bearer Authentication": []
}
],
"paths": {
"/v2/partners/{partner_profile_id}/shops": {
"post": {
"summary": "Register shop",
"operationId": "registerShop",
"description": "Register a new shops into Ratepay system. It is mandatory to register the shop before submitting payment requests.",
"parameters": [
{
"in": "path",
"name": "partner_profile_id",
"required": true,
"schema": {
"type": "string",
"example": "DE_PARTNER_ID_PR"
},
"description": "ID of the partner profile under which the new shop is to be registered."
}
],
"requestBody": {
"$ref": "#/components/requestBodies/CreateShopBody"
},
"responses": {
"200": {
"description": "Shop is created successfully and shop-id is returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"shop_id": {
"type": "string",
"example": "acbd18db4cc2f85cedef654fccc4a4d8"
}
}
}
}
}
},
"400": {
"description": "Required fields are missing",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Mandatory information missing."
},
"errors": {
"type": "object",
"properties": {
"field_name": {
"type": "array",
"items": {
"type": "string"
}
}
},
"example": "The given data was invalid."
}
}
}
}
}
},
"404": {
"description": "Invalid partner-profile-id is used",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Partner with profileId[PROFILE_ID] not found"
}
}
}
}
}
},
"409": {
"description": "Shop already exists",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Unable to create shop due to conflicts. Field shop_id should be unique."
}
}
}
}
}
}
}
}
},
"/v2/partners/{partner_profile_id}/shops/{shop_id}": {
"parameters": [
{
"in": "path",
"name": "partner_profile_id",
"required": true,
"schema": {
"type": "string",
"example": "DE_PARTNER_ID_PR"
},
"description": "ID of the partner profile under which the existing shop has been registered."
},
{
"in": "path",
"name": "shop_id",
"required": true,
"schema": {
"type": "string",
"example": "acbd18db4cc2f85cedef654fccc4a4d8"
},
"description": "The unique identifier of a shop, provided by the partner."
}
],
"get": {
"summary": "Retrieve Shop",
"operationId": "retrieveShop",
"description": "This Endpoint will output the stored information for the shop_id",
"responses": {
"200": {
"description": "Loaded shop details and configurations.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetrieveShop"
}
}
}
},
"404": {
"description": "Partner-Profile ID unknown or no shop found with given ID.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Partner with profileId[PROFILE_ID] not found"
}
}
}
}
}
}
}
},
"put": {
"summary": "Update Shop",
"operationId": "updateShop",
"description": "This API endpoint will replace the configuration stored for the shop by the new one passed here",
"requestBody": {
"$ref": "#/components/requestBodies/UpdateShopBody"
},
"responses": {
"200": {
"description": "Shop is created successfully and shop-id is returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"shop_id": {
"type": "string",
"example": "acbd18db4cc2f85cedef654fccc4a4d8"
}
}
}
}
}
},
"400": {
"description": "Required fields are missing",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Mandatory information missing."
},
"errors": {
"type": "object",
"properties": {
"field_name": {
"type": "array",
"items": {
"type": "string"
}
}
},
"example": "The given data was invalid."
}
}
}
}
}
},
"404": {
"description": "Invalid partner_profile_id is used",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Partner with profileId[PROFILE_ID] not found"
}
}
}
}
}
}
}
}
},
"/v2/partners/{partner_profile_id}/shops/{shop_id}/logos": {
"post": {
"summary": "Upload Shop Logo",
"operationId": "uploadShopLogo",
"description": "Use this endpoint for uploading a shop logo, which will we placed on the correspondences
**Constraints for the logo file**
Requirements for the image file:
- The logo file should not exceed 150 KB.
- Recommended resolution > 300 dpi
- The logo file format should be png.
- The background should be transparent.
- The logo should be in a horizontal design (width >= height).
Visualization rules:
- proportion-rule: It will be always proportionally stretched.
- max-height rule: The max-height of visualization will be 100px.
- It will be visualized in a width between 250 and 500px, if the height and proportion rules allow it.
- It will be placed on the top of the correspondence.",
"parameters": [
{
"in": "path",
"name": "partner_profile_id",
"required": true,
"schema": {
"type": "string",
"example": "DE_PARTNER_ID_PR"
},
"description": "ID of the partner profile under which the existing shop has been registered."
},
{
"in": "path",
"name": "shop_id",
"required": true,
"schema": {
"type": "string",
"example": "acbd18db4cc2f85cedef654fccc4a4d8"
},
"description": "The unique identifier of a shop, provided by the partner."
}
],
"requestBody": {
"$ref": "#/components/requestBodies/UploadLogoBody"
},
"responses": {
"201": {
"description": "Logo has been successfully uploaded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"example": []
}
}
}
},
"422": {
"description": "Logo file is missing or has a wrong format.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"type": "object",
"properties": {
"logo": {
"type": "array",
"example": [
"The logo must be a file of type: png."
]
}
}
}
}
}
}
}
},
"500": {
"description": "Logo too large or partner not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Server Error"
}
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"Bearer Authentication": {
"bearerFormat": "JWT",
"description": "For each request, a valid access token must be provided in the Authorization header. See [Authentication API](/docs/developer/authentication/authentication/) for obtaining a valid token.",
"scheme": "bearer",
"type": "http"
}
},
"requestBodies": {
"CreateShopBody": {
"description": "The registration request for the shop needs to include a `shop_id`, which is generated by the partner/client. It serves as a unique identifier for the shop under the respective partner profile.
\nAdditionally the request contains merchant legal information and correspondence settings needed for the buyer communication and for collection purposes.\n",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Shop"
}
}
}
},
"UpdateShopBody": {
"description": "Payload for shop update",
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/UpdateShop"
}
]
}
}
}
},
"UploadLogoBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"logo": {
"type": "string",
"description": "Binary file to be uploaded. It expects following MIME-Types: `*.png`",
"format": "binary"
}
}
}
}
}
}
},
"schemas": {
"Shop": {
"description": "The shop object contains merchant legal information and correspondence settings needed for the buyer communication and for collection purposes.\n",
"type": "object",
"properties": {
"shop_id": {
"type": "string",
"description": "The unique identifier of a new shop, provided by the partner.",
"example": "acbd18db4cc2f85cedef654fccc4a4d8"
},
"name": {
"type": "string",
"description": "Shop name. Required for the buyer communication.",
"example": "Animals GmbH"
},
"website": {
"type": "string",
"description": "URL to the shop's website, used in the buyer communication.",
"example": "https://animals.com"
},
"address": {
"$ref": "#/components/schemas/Address"
},
"legal": {
"$ref": "#/components/schemas/Legal"
},
"contacts": {
"$ref": "#/components/schemas/Contacts"
},
"correspondence_settings": {
"$ref": "#/components/schemas/CorrespondenceSettings"
}
},
"required": [
"shop_id",
"merchant_id",
"name",
"address",
"legal",
"shops"
]
},
"RetrieveShop": {
"description": "The shop object contains merchant legal information and correspondence settings needed for the buyer communication and for collection purposes.\n",
"type": "object",
"properties": {
"shop_id": {
"type": "string",
"description": "The unique identifier of a new shop, provided by the partner.",
"example": "acbd18db4cc2f85cedef654fccc4a4d8"
},
"name": {
"type": "string",
"description": "Shop name. Required for the buyer communication.",
"example": "Animals GmbH"
},
"website": {
"type": "string",
"description": "URL to the shop's website, used in the buyer communication.",
"example": "https://animals.com"
},
"address": {
"$ref": "#/components/schemas/RetrieveAddress"
},
"legal": {
"$ref": "#/components/schemas/RetrieveLegal"
},
"contacts": {
"$ref": "#/components/schemas/RetrieveContacts"
},
"correspondence_settings": {
"$ref": "#/components/schemas/RetrieveCorrespondenceSettings"
}
},
"required": [
"shop_id",
"merchant_id",
"name",
"address",
"legal",
"shops"
]
},
"UpdateShop": {
"description": "The shop object contains merchant legal information and correspondence settings needed for the buyer communication and for collection purposes.\n",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Shop name. Required for the buyer communication.",
"example": "Animals GmbH"
},
"website": {
"type": "string",
"description": "URL to the shop's website, used in the buyer communication.",
"example": "https://animals.com"
},
"address": {
"$ref": "#/components/schemas/Address"
},
"legal": {
"$ref": "#/components/schemas/Legal"
},
"contacts": {
"$ref": "#/components/schemas/Contacts"
},
"correspondence_settings": {
"$ref": "#/components/schemas/CorrespondenceSettings"
}
},
"required": [
"merchant_id",
"name",
"address",
"legal",
"shops"
]
},
"Address": {
"type": "object",
"description": "Address details of merchant/shop.",
"properties": {
"street": {
"type": "string",
"description": "Street name.",
"example": "Ollenhauer Str."
},
"street_number": {
"type": "string",
"description": "House number.",
"example": "17A"
},
"street_additional": {
"type": "string",
"description": "Additional details to address line."
},
"city": {
"type": "string",
"description": "City name.",
"example": "Stuttgart"
},
"postal_code": {
"type": "string",
"description": "Postal code.",
"example": "70599"
},
"country_code": {
"type": "string",
"description": "Country code in ISO 3166-1 (alpha-2) format, e.g. DE, CH, NL, etc.",
"example": "DE"
}
},
"required": [
"street",
"city",
"postal_code",
"country_code"
]
},
"RetrieveAddress": {
"type": "object",
"description": "Address details of merchant/shop.",
"properties": {
"street": {
"type": "string",
"description": "Street name.",
"example": "Ollenhauer Str."
},
"house_number": {
"type": "string",
"description": "House number.",
"example": "17A"
},
"street_additional": {
"type": "string",
"description": "Additional details to address line."
},
"city": {
"type": "string",
"description": "City name.",
"example": "Stuttgart"
},
"postal_code": {
"type": "string",
"description": "Postal code.",
"example": "70599"
},
"country_code": {
"type": "string",
"description": "Country code in ISO 3166-1 (alpha-2) format, e.g. DE, CH, NL, etc.",
"example": "DE"
}
},
"required": [
"street",
"city",
"postal_code",
"country_code"
]
},
"Legal": {
"type": "object",
"description": "Legal details of merchant/shop.",
"properties": {
"name": {
"type": "string",
"description": "Official merchant company name.",
"example": "Animal House"
},
"legal_form": {
"type": "string",
"description": "Legal form of the merchant or shop, e.g Ltd., GmbH, etc.",
"example": "GmbH"
},
"commercial_register_number": {
"type": "string",
"description": "Merchant company's registration number, e.g. HRB 124156B",
"example": "124156 B"
},
"registration_office": {
"type": "string",
"description": "Registrar of merchant company, e.g. Amtsgericht Charlottenburg (Berlin)",
"example": "Amtsgericht Charlottenburg (Berlin)"
},
"vat_id_number": {
"type": "string",
"description": "Merchant company's VAT number, e.g. DE 270 098 222. Either `vat_id_number` or `tax_number` is mandatory.",
"example": "DE817154243.B.01"
},
"tax_number": {
"type": "string",
"description": "Merchant company's tax number. Either `vat_id_number` or `tax_number` is mandatory.",
"example": "817154243"
},
"board_chairman": {
"type": "string",
"description": "Chairman of merchant's supervisory board.",
"example": "Katja Löwe"
},
"managing_directors": {
"type": "string",
"description": "Merchant company's management board.",
"example": "Ingrid Fellnase, Jens Kater, Tom Mieze"
},
"designation_of_management": {
"type": "string",
"description": "Type of the merchant's management board, e.g. Geschäftsführung. Mandatory if `managing_directors` are given.",
"example": "Geschäftsführung"
}
},
"required": [
"name",
"legal_form",
"registration_office",
"commercial_register_number",
"vat_id_number",
"tax_number"
]
},
"RetrieveLegal": {
"type": "object",
"description": "Legal details of merchant/shop.",
"properties": {
"legal_form": {
"type": "string",
"description": "Legal form of the merchant or shop, e.g Ltd., GmbH, etc.",
"example": "GmbH"
},
"commercial_register_number": {
"type": "string",
"description": "Merchant company's registration number, e.g. HRB 124156B",
"example": "124156 B"
},
"registration_office": {
"type": "string",
"description": "Registrar of merchant company, e.g. Amtsgericht Charlottenburg (Berlin)",
"example": "Amtsgericht Charlottenburg (Berlin)"
},
"vat_number": {
"type": "string",
"description": "Merchant company's VAT number, e.g. DE 270 098 222. Either `vat_id_number` or `tax_number` is mandatory.",
"example": "DE817154243.B.01"
},
"board_chairman": {
"type": "string",
"description": "Chairman of merchant's supervisory board.",
"example": "Katja Löwe"
},
"managing_directors": {
"type": "string",
"description": "Merchant company's management board.",
"example": "Ingrid Fellnase, Jens Kater, Tom Mieze"
},
"designation_of_management": {
"type": "string",
"description": "Type of the merchant's management board, e.g. Geschäftsführung. Mandatory if `managing_directors` are given.",
"example": "Geschäftsführung"
}
},
"required": [
"name",
"legal_form",
"registration_office",
"commercial_register_number",
"vat_id_number",
"tax_number"
]
},
"Contacts": {
"type": "object",
"description": "Contact options used by Ratepay to contact the merchant, shop or partner.",
"properties": {
"customer_service": {
"$ref": "#/components/schemas/CustomerService"
},
"fraud": {
"$ref": "#/components/schemas/Fraud"
},
"incident": {
"$ref": "#/components/schemas/Incident"
},
"data_protection": {
"$ref": "#/components/schemas/DataProtection"
},
"invoice_copy": {
"$ref": "#/components/schemas/InvoiceCopy"
}
},
"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"
}
}
},
"RetrieveContacts": {
"type": "object",
"description": "Contact options used by Ratepay to contact the merchant, shop or partner.",
"properties": {
"customer_service": {
"$ref": "#/components/schemas/CustomerService"
},
"fraud": {
"$ref": "#/components/schemas/Fraud"
},
"incident": {
"$ref": "#/components/schemas/Incident"
},
"data_protection": {
"$ref": "#/components/schemas/DataProtection"
},
"invoice_copy": {
"$ref": "#/components/schemas/RetrieveInvoiceCopy"
}
},
"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": "support@cats.de"
}
},
"CustomerService": {
"type": "object",
"description": "Contact details of the shop's customer service.",
"properties": {
"email": {
"type": "string",
"example": "support@cats.de"
},
"phone": {
"type": "string",
"example": "+49 (0)85 888 8138"
},
"fax": {
"type": "string",
"example": "+49 (0)85 888 8199"
}
},
"required": [
"email"
]
},
"Fraud": {
"type": "object",
"description": "Contact details in case of fraud.",
"properties": {
"email": {
"type": "string",
"example": "support@cats.de"
},
"phone": {
"type": "string",
"example": "+49 (0)85 888 8138"
},
"fax": {
"type": "string",
"example": "+49 (0)85 888 8199"
}
},
"required": [
"email"
]
},
"Incident": {
"type": "object",
"description": "Contact details in case of technical incidents.",
"properties": {
"email": {
"type": "string",
"example": "support@cats.de"
},
"phone": {
"type": "string",
"example": "+49 (0)85 888 8138"
},
"fax": {
"type": "string",
"example": "+49 (0)85 888 8199"
}
},
"required": [
"email"
]
},
"DataProtection": {
"type": "object",
"description": "Contact details in case of privacy compliance.",
"properties": {
"email": {
"type": "string",
"example": "support@cats.de"
},
"phone": {
"type": "string",
"example": "+49 (0)85 888 8138"
},
"fax": {
"type": "string",
"example": "+49 (0)85 888 8199"
}
},
"required": [
"email"
]
},
"InvoiceCopy": {
"type": "object",
"description": "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.",
"properties": {
"email": {
"type": "string",
"example": "support@cats.de"
}
},
"required": [
"email"
]
},
"RetrieveInvoiceCopy": {
"type": "string",
"description": "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.",
"example": "support@cats.de"
},
"ContactDetails": {
"type": "object",
"description": "Contact details.",
"properties": {
"email": {
"type": "string",
"example": "support@cats.de"
},
"phone": {
"type": "string",
"example": "+49 (0)85 888 8138"
},
"fax": {
"type": "string",
"example": "+49 (0)85 888 8199"
}
},
"required": [
"email"
]
},
"CorrespondenceSettings": {
"type": "object",
"description": "Configuration of correspondences for the buyer communication.",
"properties": {
"branding_settings": {
"$ref": "#/components/schemas/BrandingSettings"
},
"slang": {
"$ref": "#/components/schemas/Slang"
},
"payment_method_specific": {
"type": "array",
"description": "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.",
"items": {
"$ref": "#/components/schemas/CorrespondenceSpecification"
},
"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
}
}
]
}
}
},
"RetrieveCorrespondenceSettings": {
"type": "object",
"description": "Configuration of correspondences for the buyer communication.",
"properties": {
"branding_settings": {
"$ref": "#/components/schemas/BrandingSettings"
},
"payment_method_specific": {
"type": "array",
"description": "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.",
"items": {
"$ref": "#/components/schemas/CorrespondenceSpecification"
},
"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
},
"dunning_1": {
"shop_branding": true
},
"dunning_2": {
"shop_branding": true
},
"dunning_3": {
"shop_branding": true
}
}
]
}
}
},
"BrandingSettings": {
"type": "object",
"description": "Appearance options for the buyer correspondences. e.g. shop logo position and highlight color.",
"properties": {
"logo_position": {
"type": "string",
"description": "Shop logo position in buyer correspondences.",
"enum": [
"LEFT",
"CENTER",
"RIGHT"
]
},
"highlight_color": {
"type": "string",
"description": "The color for the highlighted elements in buyer correspondences as HTML HEX color code, e.g `#BADB11`",
"example": "#BADB01"
}
}
},
"Slang": {
"type": "object",
"description": "Slang definition for the buyer correspondences.",
"properties": {
"en": {
"$ref": "#/components/schemas/SlangVariation"
},
"de": {
"$ref": "#/components/schemas/SlangVariation"
},
"nl": {
"$ref": "#/components/schemas/SlangVariation"
}
},
"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"
]
}
}
},
"SlangVariation": {
"type": "object",
"properties": {
"salutation": {
"type": "string",
"description": "Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.",
"example": "Hello"
},
"order": {
"type": "string",
"description": "The type of order.",
"example": "ORDER",
"enum": [
"ORDER",
"BOOKING"
]
},
"formal_tone": {
"type": "string",
"description": "Formality level for the buyer correspondences.",
"example": "INFORMAL",
"enum": [
"FORMAL",
"INFORMAL"
]
},
"name_format": {
"type": "string",
"description": "Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.",
"example": "FIRST_NAME",
"enum": [
"FIRST_NAME",
"LAST_NAME",
"FIRST_LAST_NAME"
]
},
"customer_service_contact": {
"type": "array",
"description": "Additional lines in buyer correspondences referring to the customer service contact details of the shop, merchant or partner.",
"items": {
"type": "string"
},
"example": [
{
"Hotline": "0800 1234 1234 (29ct/min Germany)"
},
{
"Office Hours": "10:00 - 18:00 mo-sa"
},
{
"Fax": "+49 (30) 1234567-10"
}
]
}
}
},
"CorrespondenceSpecification": {
"type": "object",
"properties": {
"payment_method": {
"$ref": "#/components/schemas/PaymentMethod"
},
"invoice": {
"$ref": "#/components/schemas/Invoice"
},
"payment_instruction": {
"$ref": "#/components/schemas/PaymentInstruction"
},
"payment_receipt": {
"$ref": "#/components/schemas/PaymentReceipt"
},
"dunning_1": {
"$ref": "#/components/schemas/Dunning1"
},
"dunning_2": {
"$ref": "#/components/schemas/Dunning2"
},
"dunning_3": {
"$ref": "#/components/schemas/Dunning3"
},
"advance_notice": {
"$ref": "#/components/schemas/AdvanceNotice"
},
"order_confirmation": {
"$ref": "#/components/schemas/OrderConfirmation"
},
"initial_plan": {
"$ref": "#/components/schemas/InitialPlan"
},
"updated_plan": {
"$ref": "#/components/schemas/UpdatedPlan"
},
"advance_notice_sepa_update": {
"$ref": "#/components/schemas/AdvanceNoticeSepaUpdate"
}
}
},
"PaymentMethod": {
"type": "object",
"description": "Ratepay payment methods consists of the parameters `payment_option` and `transfer_type`.",
"properties": {
"payment_option": {
"type": "string",
"description": "Payment option.",
"enum": [
"OPEN_INVOICE",
"PREPAYMENT",
"INSTALMENT"
],
"example": "OPEN_INVOICE"
},
"transfer_type": {
"type": "string",
"description": "Payment transfer type.",
"enum": [
"BANK_TRANSFER",
"DIRECT_DEBIT"
],
"example": "BANK_TRANSFER"
}
}
},
"Invoice": {
"type": "object",
"description": "Official invoice, sent with every delivery. The invoice is skipped by default.",
"properties": {
"skip_sending": {
"type": "boolean",
"description": "Whether the correspondence should be sent by Ratepay. If `true`, the correspondence won't be sent by Ratepay. The default value is `true`.",
"example": false
},
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"PaymentInstruction": {
"type": "object",
"description": "Instructions with payment details, open amount, and due date, sent with every delivery.",
"properties": {
"skip_sending": {
"type": "boolean",
"description": "Whether the correspondence should be sent by Ratepay. If `true`, the correspondence won't be sent by Ratepay. The default value is `true`.",
"example": false
},
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"PaymentReceipt": {
"type": "object",
"description": "Payment confirmation, sent after every payment.",
"properties": {
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"Dunning1": {
"type": "object",
"description": "Friendly payment reminder, sent after the original due date is exceeded.",
"properties": {
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"Dunning2": {
"type": "object",
"description": "First payment reminder with a dunning fee. In this correspondence, Ratepay comes to the fore, even though the design is shop branded by default.",
"properties": {
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"Dunning3": {
"type": "object",
"description": "Last payment reminder. The design is in Ratepay branding, regardless of the `shop_branding` setting.",
"properties": {
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"AdvanceNotice": {
"type": "object",
"description": "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.",
"properties": {
"skip_sending": {
"type": "boolean",
"description": "Whether the correspondence should be sent by Ratepay. If `true`, the correspondence won't be sent by Ratepay. The default value is `true`.",
"example": false
},
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"OrderConfirmation": {
"type": "object",
"description": "An email with general information about a purchase with instalment option. It is sent after the purchase.",
"properties": {
"skip_sending": {
"type": "boolean",
"description": "Whether the correspondence should be sent by Ratepay. If `true`, the correspondence won't be sent by Ratepay. The default value is `true`.",
"example": false
},
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"InitialPlan": {
"type": "object",
"description": "Initial instalment plan. Contains, details of the deliveries, an overview of the instalment plan, and instructions for the monthly payments.",
"properties": {
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"UpdatedPlan": {
"type": "object",
"description": "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.",
"properties": {
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"AdvanceNoticeSepaUpdate": {
"type": "object",
"description": "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.",
"properties": {
"skip_sending": {
"type": "boolean",
"description": "Whether the correspondence should be sent by Ratepay. If `true`, the correspondence won't be sent by Ratepay. The default value is `true`.",
"example": false
},
"shop_branding": {
"type": "boolean",
"description": "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
}
}
},
"CorrespondenceSpecificationAttributes": {
"type": "object",
"properties": {
"skip_sending": {
"type": "boolean",
"description": "Whether the correspondence should be sent by Ratepay. If `true`, the correspondence won't be sent by Ratepay. The default value is `true`.",
"example": false
},
"shop_branding": {
"type": "boolean",
"description": "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
}
}
}
}
}
}