Skip to content

Ratepay Merchant Registration API (2.0)

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.

Download OpenAPI description
operations.json
operations.yaml
Languages
Servers
Production environment
https://api.ratepay.com/merchant/registry
Test environment
https://api-integration.ratepay.com/merchant/registry

Register shop

Request

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

Security
Bearer Authentication
Path
partner_profile_idstringrequired

ID of the partner profile under which the new shop is to be registered.

Example: DE_PARTNER_ID_PR
Bodyapplication/jsonrequired

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.
Additionally the request contains merchant legal information and correspondence settings needed for the buyer communication and for collection purposes.

shop_idstringrequired

The unique identifier of a new shop, provided by the partner.

Example: "acbd18db4cc2f85cedef654fccc4a4d8"
namestringrequired

Shop name. Required for the buyer communication.

Example: "Animals GmbH"
websitestring

URL to the shop's website, used in the buyer communication.

Example: "https://animals.com"
addressobject(Address)required

Address details of merchant/shop.

legalobject(Legal)required

Legal details of merchant/shop.

contactsobject(Contacts)

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"}}
correspondence_settingsobject(CorrespondenceSettings)

Configuration of correspondences for the buyer communication.

curl -i -X POST \
  https://api.ratepay.com/merchant/registry/v2/partners/DE_PARTNER_ID_PR/shops \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shop_id": "acbd18db4cc2f85cedef654fccc4a4d8",
    "name": "Animals GmbH",
    "website": "https://animals.com",
    "address": {
      "street": "Ollenhauer Str.",
      "street_number": "17A",
      "street_additional": "string",
      "city": "Stuttgart",
      "postal_code": "70599",
      "country_code": "DE"
    },
    "legal": {
      "name": "Animal House",
      "legal_form": "GmbH",
      "commercial_register_number": "124156 B",
      "registration_office": "Amtsgericht Charlottenburg (Berlin)",
      "vat_id_number": "DE817154243.B.01",
      "tax_number": "817154243",
      "board_chairman": "Katja Löwe",
      "managing_directors": "Ingrid Fellnase, Jens Kater, Tom Mieze",
      "designation_of_management": "Geschäftsführung"
    },
    "contacts": {
      "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"
      }
    },
    "correspondence_settings": {
      "branding_settings": {
        "logo_position": "LEFT",
        "highlight_color": "#BADB01"
      },
      "slang": {
        "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"
          ]
        }
      },
      "payment_method_specific": [
        {
          "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
          }
        }
      ]
    }
  }'

Responses

Shop is created successfully and shop-id is returned

Bodyapplication/json
shop_idstring
Example: "acbd18db4cc2f85cedef654fccc4a4d8"
Response
application/json
{
  "shop_id": "acbd18db4cc2f85cedef654fccc4a4d8"
}

Retrieve Shop

Request

This Endpoint will output the stored information for the shop_id

Security
Bearer Authentication
Path
partner_profile_idstringrequired

ID of the partner profile under which the existing shop has been registered.

Example: DE_PARTNER_ID_PR
shop_idstringrequired

The unique identifier of a shop, provided by the partner.

Example: acbd18db4cc2f85cedef654fccc4a4d8
curl -i -X GET \
  https://api.ratepay.com/merchant/registry/v2/partners/DE_PARTNER_ID_PR/shops/acbd18db4cc2f85cedef654fccc4a4d8 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Loaded shop details and configurations.

Bodyapplication/json
shop_idstringrequired

The unique identifier of a new shop, provided by the partner.

Example: "acbd18db4cc2f85cedef654fccc4a4d8"
namestringrequired

Shop name. Required for the buyer communication.

Example: "Animals GmbH"
websitestring

URL to the shop's website, used in the buyer communication.

Example: "https://animals.com"
addressobject(RetrieveAddress)required

Address details of merchant/shop.

legalobject(RetrieveLegal)required

Legal details of merchant/shop.

contactsobject(RetrieveContacts)

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":"support@cats.de"}
correspondence_settingsobject(RetrieveCorrespondenceSettings)

Configuration of correspondences for the buyer communication.

Response
application/json
{
  "shop_id": "acbd18db4cc2f85cedef654fccc4a4d8",
  "name": "Animals GmbH",
  "website": "https://animals.com",
  "address": {
    "street": "Ollenhauer Str.",
    "house_number": "17A",
    "street_additional": "string",
    "city": "Stuttgart",
    "postal_code": "70599",
    "country_code": "DE"
  },
  "legal": {
    "legal_form": "GmbH",
    "commercial_register_number": "124156 B",
    "registration_office": "Amtsgericht Charlottenburg (Berlin)",
    "vat_number": "DE817154243.B.01",
    "board_chairman": "Katja Löwe",
    "managing_directors": "Ingrid Fellnase, Jens Kater, Tom Mieze",
    "designation_of_management": "Geschäftsführung"
  },
  "contacts": {
    "customer_service": { … },
    "fraud": { … },
    "incident": { … },
    "data_protection": { … },
    "invoice_copy": "support@cats.de"
  },
  "correspondence_settings": {
    "branding_settings": { … },
    "payment_method_specific": [ … ]
  }
}

Update Shop

Request

This API endpoint will replace the configuration stored for the shop by the new one passed here

Security
Bearer Authentication
Path
partner_profile_idstringrequired

ID of the partner profile under which the existing shop has been registered.

Example: DE_PARTNER_ID_PR
shop_idstringrequired

The unique identifier of a shop, provided by the partner.

Example: acbd18db4cc2f85cedef654fccc4a4d8
Bodyapplication/jsonrequired

Payload for shop update

namestringrequired

Shop name. Required for the buyer communication.

Example: "Animals GmbH"
websitestring

URL to the shop's website, used in the buyer communication.

Example: "https://animals.com"
addressobject(Address)required

Address details of merchant/shop.

legalobject(Legal)required

Legal details of merchant/shop.

contactsobject(Contacts)

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"}}
correspondence_settingsobject(CorrespondenceSettings)

Configuration of correspondences for the buyer communication.

curl -i -X PUT \
  https://api.ratepay.com/merchant/registry/v2/partners/DE_PARTNER_ID_PR/shops/acbd18db4cc2f85cedef654fccc4a4d8 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Animals GmbH",
    "website": "https://animals.com",
    "address": {
      "street": "Ollenhauer Str.",
      "street_number": "17A",
      "street_additional": "string",
      "city": "Stuttgart",
      "postal_code": "70599",
      "country_code": "DE"
    },
    "legal": {
      "name": "Animal House",
      "legal_form": "GmbH",
      "commercial_register_number": "124156 B",
      "registration_office": "Amtsgericht Charlottenburg (Berlin)",
      "vat_id_number": "DE817154243.B.01",
      "tax_number": "817154243",
      "board_chairman": "Katja Löwe",
      "managing_directors": "Ingrid Fellnase, Jens Kater, Tom Mieze",
      "designation_of_management": "Geschäftsführung"
    },
    "contacts": {
      "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"
      }
    },
    "correspondence_settings": {
      "branding_settings": {
        "logo_position": "LEFT",
        "highlight_color": "#BADB01"
      },
      "slang": {
        "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"
          ]
        }
      },
      "payment_method_specific": [
        {
          "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
          }
        }
      ]
    }
  }'

Responses

Shop is created successfully and shop-id is returned

Bodyapplication/json
shop_idstring
Example: "acbd18db4cc2f85cedef654fccc4a4d8"
Response
application/json
{
  "shop_id": "acbd18db4cc2f85cedef654fccc4a4d8"
}