{
"openapi": "3.0.1",
"info": {
"title": "OpenAPI definition",
"version": "v0"
},
"servers": [
{
"url": "https://payment-integration.ratepay.com",
"description": "Integration environment"
},
{
"url": "https://payment.ratepay.com",
"description": "Production environment"
}
],
"security": [
{
"Bearer Authentication": []
}
],
"paths": {
"/pps/api/v1/session": {
"post": {
"tags": [
"Session management API"
],
"summary": "Creates a new session",
"operationId": "createSession",
"parameters": [
{
"description": "Optional ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See [Idempotency in HPP](/docs/developer/hosted_payment_page/idempotency/) for further details.",
"in": "header",
"name": "Idempotency-Key",
"required": false,
"schema": {
"type": "string",
"maxLength": 64
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionRequestDto"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Session created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionCreatedResponseDto"
}
}
}
},
"401": {
"description": "Authorization issue, due to e.g. missing or invalid authorization header",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedErrorResponse"
}
}
}
},
"403": {
"description": "Authorization issue, due to the provisioned token not having permission to create the specified session"
},
"404": {
"description": "Data not found, such as seller settings or transaction details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable, due to e.g. invalid session state or missing customer contact details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnprocessableEntityErrorResponse"
}
}
}
}
}
}
},
"/pps/api/v1/session-record": {
"get": {
"tags": [
"Session Records API"
],
"summary": "Retrieve a list of session records based on supplied date",
"operationId": "getSessionRecordsByDate",
"parameters": [
{
"name": "createdDate",
"in": "query",
"required": true,
"description": "A date, formatted as yyyy-MM-dd , when the records have been created",
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "List of session records returned successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SessionRecordDto"
}
}
}
}
},
"401": {
"description": "Authorization issue, due to e.g. missing or invalid authorization header",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedErrorResponse"
}
}
}
},
"403": {
"description": "Authorization issue, due to the provisioned token not having permission to create the specified session"
}
}
}
},
"/pps/api/v1/session-record/{sessionId}": {
"get": {
"tags": [
"Session Records API"
],
"summary": "Retrieve a session record according to the session ID",
"operationId": "getSessionRecord",
"parameters": [
{
"name": "sessionId",
"in": "path",
"required": true,
"description": "The session ID, as returned from the request to create sessions",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Session record returned successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionRecordDto"
}
}
}
},
"401": {
"description": "Authorization issue, due to e.g. missing or invalid authorization header",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedErrorResponse"
}
}
}
},
"403": {
"description": "Authorization issue, due to the provisioned token not having permission to create the specified session"
},
"404": {
"description": "Session record not found"
}
}
}
},
"/webhook-url": {
"post": {
"tags": [
"Webhook format"
],
"summary": "Monitor Session Status",
"operationId": "Webhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionRecordDto"
}
}
},
"required": true
},
"responses": {
"2xx": {
"description": "Handled as success case - therefore, will not be retried."
},
"5xx": {
"description": "Handled as a failure, and will be retried later. It will be retried in intervals of 3, 6 and 9 seconds until giving up. If it cannot be delivered, the merchant is advised to use the session records API to fetch the latest status of the transaction."
},
"4xx": {
"description": "Handled as a failure, and will be retried later. It will be retried in intervals of 3, 6 and 9 seconds until giving up. If it cannot be delivered, the merchant is advised to use the session records API to fetch the latest status of the transaction."
}
}
}
}
},
"components": {
"schemas": {
"AddressDto": {
"required": [
"city",
"country_code",
"street",
"zip_code"
],
"type": "object",
"properties": {
"city": {
"maxLength": 100,
"minLength": 2,
"type": "string",
"description": "The city of the address. Must be at least 2 non whitespace characters.",
"example": "Berlin"
},
"country_code": {
"pattern": "^[A-Z]{2}$",
"type": "string",
"description": "The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).",
"example": "DE"
},
"street": {
"maxLength": 100,
"minLength": 0,
"type": "string",
"description": "The name of the street.",
"example": "Schönhauser Allee"
},
"street_addition": {
"maxLength": 50,
"minLength": 0,
"type": "string",
"description": "Additional information about the address, e.g. 2nd floor, c/o John Doe.",
"example": "Seitenflügel, 2. HH"
},
"street_number": {
"maxLength": 30,
"minLength": 0,
"type": "string",
"description": "The number describing where the building is located in the street. Notice that it **must** be sent in either this field or in `street`. For example, if the `street` field contains \"Musterstraße 1\", then it is not needed to supply data here. But if `street` only contains \"Musterstraße\", then `street_number` must contain \"1\".",
"example": "84"
},
"zip_code": {
"maxLength": 10,
"minLength": 0,
"type": "string",
"description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).",
"example": "10439"
}
},
"description": "The address of the recipient."
},
"BrandingSettingsDto": {
"type": "object",
"properties": {
"highlight_color": {
"pattern": "^#[a-fA-F0-9]{6}$",
"type": "string",
"description": "The color for the highlighted elements in buyer correspondences as HTML HEX color code, e.g. `#BADB11`."
},
"logo_position": {
"type": "string",
"description": "Shop logo position in buyer correspondences.",
"enum": [
"LEFT",
"RIGHT",
"CENTER"
]
},
"logo_url": {
"type": "string",
"description": "Publicly accessible shop logo to include in buyer correspondences. This must be a valid `https://` or `http://` URL."
}
},
"description": "Shop branding settings for buyer correspondences."
},
"BuyerDto": {
"required": [
"billing_address",
"contact"
],
"type": "object",
"properties": {
"billing_address": {
"$ref": "#/components/schemas/AddressDto"
},
"company": {
"$ref": "#/components/schemas/CompanyDto"
},
"contact": {
"$ref": "#/components/schemas/ContactDto"
},
"language": {
"pattern": "^[a-z]{2}$",
"type": "string",
"description": "The language in which the buyer prefers communication to be done. If the preferred language is not supported, the buyer communication will be in German. Must conform to [ISO 639-1 alpha 2](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes)."
},
"person": {
"$ref": "#/components/schemas/PersonDto"
},
"shop_buyer_id": {
"maxLength": 100,
"minLength": 0,
"type": "string",
"description": "The buyer ID of a regular customer. See [regular customer documentation](https://docs.ratepay.com/docs/reporting/regular_customers/regular_customers_introduction/) for details. Get an [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API."
}
},
"description": "The buyer that wants to place the transaction."
},
"CompanyDto": {
"required": [
"name"
],
"type": "object",
"properties": {
"first_name": {
"maxLength": 100,
"minLength": 0,
"type": "string",
"description": "The first name of the contact person within the company."
},
"last_name": {
"maxLength": 100,
"minLength": 0,
"type": "string",
"description": "The last name of the contact person within the company."
},
"name": {
"maxLength": 100,
"minLength": 0,
"type": "string",
"description": "Official company name, should include legal form if applicable."
},
"vat_id": {
"maxLength": 20,
"minLength": 0,
"type": "string",
"description": "Value-added tax ID of the company. This can be a European VAT ID or a local one."
}
},
"description": "The company that wants to place the transaction. This implies a B2B transaction. Either provide a person or company but not both."
},
"ContactDto": {
"required": [
"email"
],
"type": "object",
"properties": {
"email": {
"maxLength": 100,
"minLength": 0,
"pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$",
"type": "string",
"description": "The email address of the buyer."
},
"phone": {
"maxLength": 60,
"minLength": 6,
"pattern": "^[+0-9/\\\\\\- ().,;]*[0-9][+0-9/\\\\\\- ().,;]*$",
"type": "string",
"description": "The phone number of the buyer. Has to have at least 6 digits without spaces."
}
},
"description": "The contact information of the buyer."
},
"CorrespondenceSettingsDto": {
"type": "object",
"properties": {
"branding_settings": {
"$ref": "#/components/schemas/BrandingSettingsDto"
},
"slangs": {
"$ref": "#/components/schemas/SlangsDto"
}
},
"description": "Settings for buyer correspondences."
},
"DeliveryDto": {
"type": "object",
"properties": {
"address": {
"$ref": "#/components/schemas/AddressDto"
},
"company": {
"type": "string",
"description": "The company name of the recipient."
},
"first_name": {
"type": "string",
"description": "The first name of the recipient. If supplied, the field `last_name` becomes mandatory, and `full_name` must not be sent."
},
"full_name": {
"type": "string",
"description": "The full name of the recipient. If supplied, the fields `first_name` and `last_name` must not be sent."
},
"in_store_collect": {
"$ref": "#/components/schemas/InStoreCollectDto"
},
"last_name": {
"type": "string",
"description": "The last name of the recipient. If supplied, the field `first_name` becomes mandatory, and `full_name` must not be sent."
},
"pick_up_box": {
"$ref": "#/components/schemas/PickUpBoxDto"
},
"pick_up_shop": {
"$ref": "#/components/schemas/PickUpShopDto"
}
},
"description": "The delivery address and additional delivery parameters."
},
"InStoreCollectDto": {
"required": [
"city",
"country_code",
"street",
"zip_code"
],
"type": "object",
"properties": {
"city": {
"maxLength": 100,
"minLength": 2,
"type": "string",
"description": "The city of the address. Must be at least 2 non whitespace characters."
},
"country_code": {
"pattern": "^[A-Z]{2}$",
"type": "string",
"description": "The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)."
},
"location_name": {
"maxLength": 127,
"minLength": 0,
"type": "string",
"description": "The name of the collection location."
},
"street": {
"maxLength": 100,
"minLength": 1,
"type": "string",
"description": "The name of the street."
},
"street_addition": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "Additional information about the address."
},
"street_number": {
"maxLength": 30,
"minLength": 1,
"type": "string",
"description": "The number describing where the building is located in the street."
},
"zip_code": {
"maxLength": 10,
"minLength": 1,
"type": "string",
"description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes)."
}
},
"description": "The information of the in-store collect."
},
"LegalDto": {
"required": [
"name"
],
"type": "object",
"properties": {
"commercial_register_number": {
"maxLength": 12,
"minLength": 2,
"type": "string",
"description": "The registration number the shop is filed under."
},
"legal_form": {
"maxLength": 255,
"minLength": 2,
"type": "string",
"description": "The legal form as which the shop is registered, e.g. Ltd., GmbH, GbR, etc."
},
"name": {
"maxLength": 255,
"minLength": 2,
"type": "string",
"description": "The name of the shop as which it is registered."
}
},
"description": "Legal information about the shop."
},
"MerchantDto": {
"type": "object",
"properties": {
"merchant_id": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "This is the unique identifier for the merchant. Before using the merchant_id in the API payload request, it must be requested from Ratepay. Please refer to the [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details."
},
"merchant_name": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "This refers to the name of the merchant. It may vary from both the shop name and the legal name of the shop, both of which are also present in the current shops object."
}
},
"description": "This section contains optional details about a merchant managing a shop. A single merchant may operate one or more shops. By connecting shops to a specific merchant, it becomes possible to configure a merchant-level set of settings in the Ratepay systems. These settings will then be applied to all the associated shops."
},
"OrderDataDto": {
"required": [
"buyer",
"currency",
"shop_baskets"
],
"type": "object",
"properties": {
"authorization_expires": {
"type": "string",
"description": "The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). If not given, a default expiry time is generated."
},
"buyer": {
"$ref": "#/components/schemas/BuyerDto"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string",
"description": "The currency of all amounts pertaining to the transaction. Upper-case alphabetic code in accordance with [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)."
},
"delivery": {
"$ref": "#/components/schemas/DeliveryDto"
},
"partner_operation_id": {
"maxLength": 255,
"minLength": 0,
"type": "string",
"description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API."
},
"partner_transaction_id": {
"maxLength": 50,
"minLength": 0,
"type": "string",
"description": "The transaction ID generated by the partner. This field must be included in at least one of the following requests: authorization or capture. This ID can be displayed in settlement reports. Get an [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API."
},
"shop_baskets": {
"type": "array",
"description": "One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.",
"items": {
"$ref": "#/components/schemas/ShopBasketDto"
}
},
"shops": {
"type": "array",
"description": "Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop.",
"items": {
"$ref": "#/components/schemas/ShopDto"
}
},
"payment_method": {
"$ref": "#/components/schemas/PaymentMethodDto"
}
}
},
"PaymentMethodDto": {
"required": [
"payment_option",
"transfer_type"
],
"type": "object",
"properties": {
"payment_option": {
"type": "string",
"description": "The accepted payment method for the current transaction.",
"example": "OPEN_INVOICE",
"enum": [
"PAY_NOW",
"OPEN_INVOICE"
]
},
"transfer_type": {
"type": "string",
"description": "The transfer type accepted for a given payment option.",
"example": "BANK_TRANSFER",
"enum": [
"SEPA_DIRECT_DEBIT",
"BANK_TRANSFER"
]
}
},
"description": "Payment method of the transaction, along with the payment type and transfer type. If not specified, all enabled payment methods are shown."
},
"PersonDto": {
"required": [
"first_name",
"last_name"
],
"type": "object",
"properties": {
"date_of_birth": {
"type": "string",
"description": "The date of birth of the person. Must be in format `YYYY-MM-DD` conforming to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
},
"first_name": {
"maxLength": 100,
"minLength": 0,
"type": "string",
"description": "The first name of the person. It must be a string containing only characters with : - any kind of letter from any language (including accented letters)
- Unicode mark characters (accents/diacritics)
- any kind of numeric character
- space
- period
- backtick (`)
- apostrophe (')
- hyphen (-)
"
},
"last_name": {
"maxLength": 100,
"minLength": 0,
"type": "string",
"description": "The last name of the person. It must be a string containing only characters with : - any kind of letter from any language (including accented letters)
- Unicode mark characters (accents/diacritics)
- any kind of numeric character
- space
- period
- backtick (`)
- apostrophe (')
- hyphen (-)
"
},
"title": {
"maxLength": 45,
"minLength": 0,
"type": "string",
"description": "The title of the person."
}
},
"description": "The person that wants to place the transaction. This implies a B2C transaction. Either provide a person or company but not both."
},
"PickUpBoxDto": {
"required": [
"city",
"country_code",
"location_id",
"zip_code"
],
"type": "object",
"properties": {
"carrier_name": {
"maxLength": 127,
"minLength": 0,
"type": "string",
"description": "The name of the parcel carrier."
},
"city": {
"maxLength": 100,
"minLength": 2,
"type": "string",
"description": "The city of the address. Must be at least 2 non whitespace characters."
},
"country_code": {
"pattern": "^[A-Z]{2}$",
"type": "string",
"description": "The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)."
},
"location_id": {
"type": "string",
"description": "The ID of pick up location with the carrier."
},
"recipient_account_id": {
"maxLength": 127,
"minLength": 0,
"type": "string",
"description": "The ID of the receiver with the carrier. It is optional only for country_code AT, otherwise it is required."
},
"zip_code": {
"maxLength": 10,
"minLength": 0,
"type": "string",
"description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes)."
}
},
"description": "The information of the pick up box."
},
"PickUpShopDto": {
"required": [
"city",
"country_code",
"street",
"zip_code"
],
"type": "object",
"properties": {
"city": {
"maxLength": 100,
"minLength": 2,
"type": "string",
"description": "The city of the address. Must be at least 2 non whitespace characters."
},
"country_code": {
"pattern": "^[A-Z]{2}$",
"type": "string",
"description": "The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)."
},
"location_name": {
"maxLength": 127,
"minLength": 0,
"type": "string",
"description": "The name of the pick up shop."
},
"street": {
"maxLength": 100,
"minLength": 1,
"type": "string",
"description": "The name of the street."
},
"street_addition": {
"maxLength": 50,
"minLength": 1,
"type": "string",
"description": "Additional information about the address."
},
"street_number": {
"maxLength": 30,
"minLength": 1,
"type": "string",
"description": "The number describing where the building is located in the street."
},
"zip_code": {
"maxLength": 10,
"minLength": 1,
"type": "string",
"description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes)."
}
},
"description": "The information of the pick up shop."
},
"SessionRequestDto": {
"required": [
"order_data"
],
"type": "object",
"properties": {
"order_data": {
"$ref": "#/components/schemas/OrderDataDto"
},
"url_data": {
"$ref": "#/components/schemas/UrlData"
}
}
},
"ShopBasketDto": {
"required": [
"gross_amount",
"items",
"partner_shop_id",
"vats"
],
"type": "object",
"properties": {
"gross_amount": {
"type": "number",
"description": "The amount for the basket including VAT given in the currency of the transaction. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details."
},
"items": {
"type": "array",
"description": "List of items contained in the transaction.",
"items": {
"$ref": "#/components/schemas/SpecialItemDto"
}
},
"partner_shop_id": {
"maxLength": 255,
"minLength": 0,
"type": "string",
"description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API."
},
"shop_merchant_id": {
"maxLength": 255,
"minLength": 0,
"type": "string",
"description": "This is the unique identifier for the merchant. Before using the merchant_id in the shop_baskets object, it must be requested from Ratepay and connected with a respective partner_shop_id in the Ratepay systems. Please refer to the [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details."
},
"shop_transaction_id": {
"maxLength": 127,
"minLength": 0,
"type": "string",
"description": "The transaction ID generated by the shop. This field must be included in at least one of the following requests: authorization or capture.This ID must be known to the buyer and is used for buyer communication, e.g. correspondences and buyer support."
},
"special_items": {
"type": "array",
"description": "List of special items contained in the transaction, e.g. shipping costs or discounts.",
"items": {
"$ref": "#/components/schemas/SpecialItemDto"
}
},
"vats": {
"type": "array",
"description": "List of value-added tax (VAT) amounts.",
"items": {
"$ref": "#/components/schemas/VatDto"
}
}
},
"description": "One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details."
},
"ShopDto": {
"required": [
"legal",
"merchant_category_code",
"name",
"partner_shop_id"
],
"type": "object",
"properties": {
"correspondence_settings": {
"$ref": "#/components/schemas/CorrespondenceSettingsDto"
},
"legal": {
"$ref": "#/components/schemas/LegalDto"
},
"merchant": {
"$ref": "#/components/schemas/MerchantDto"
},
"merchant_category_code": {
"pattern": "^[0-9]{4}$",
"type": "string",
"description": "he branch of industry of the shop. Must conform to [ISO 18245](https://www.iso.org/standard/79450.html)."
},
"name": {
"maxLength": 255,
"minLength": 2,
"type": "string",
"description": "The name of the shop. May differ from legal name."
},
"partner_shop_id": {
"maxLength": 255,
"minLength": 1,
"type": "string",
"description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](https://docs.ratepay.com/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API."
}
},
"description": "Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop."
},
"SlangDto": {
"type": "object",
"properties": {
"customer_service_contact": {
"type": "array",
"description": "List of 1 to 5 lines with correspondence information. Include how to reach customer support.",
"items": {
"type": "string",
"description": "List of 1 to 5 lines with correspondence information. Include how to reach customer support."
}
},
"formal_tone": {
"type": "string",
"description": "Formality level for the buyer correspondences.",
"enum": [
"FORMAL",
"INFORMAL"
]
},
"name_format": {
"type": "string",
"description": "Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.",
"enum": [
"EMTPY",
"FIRST_NAME",
"LAST_NAME",
"FIRST_LAST_NAME"
]
},
"salutation": {
"maxLength": 2147483647,
"minLength": 1,
"type": "string",
"description": "Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc."
},
"transaction_type": {
"type": "string",
"description": "Specifies how to call the transaction in buyer correspondences.",
"enum": [
"ORDER",
"BOOKING"
]
}
}
},
"SlangsDto": {
"type": "object",
"properties": {
"de": {
"$ref": "#/components/schemas/SlangDto"
},
"en": {
"$ref": "#/components/schemas/SlangDto"
},
"fr": {
"$ref": "#/components/schemas/SlangDto"
},
"nl": {
"$ref": "#/components/schemas/SlangDto"
}
},
"description": "Language settings for buyer correspondences."
},
"SpecialItemDto": {
"required": [
"gross_unit_price",
"name",
"quantity",
"tax_rate"
],
"type": "object",
"properties": {
"article_number": {
"maxLength": 255,
"minLength": 0,
"pattern": "^.*[\\S].*$",
"type": "string",
"description": "The article number of the item, e.g. SKU. Not allowed to contain only whitespaces."
},
"category": {
"maxLength": 511,
"minLength": 0,
"type": "string",
"description": "Category for the item."
},
"description": {
"maxLength": 511,
"minLength": 0,
"type": "string",
"description": "Description of the item."
},
"gross_total_price": {
"type": "number",
"description": "Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity"
},
"gross_unit_discount": {
"type": "number",
"description": "Gross discount on one item after taxes. Needs to be a negative value."
},
"gross_unit_price": {
"type": "number",
"description": "Gross value of one item before taxes. For the RETURN_FEE type, applicable only to the REFUND operation, the value must be negative."
},
"name": {
"type": "string",
"description": "Name of the item."
},
"net_total_price": {
"type": "number",
"description": "Net value including discount of these items before taxes. net_total_price = (net_unit_price + net_unit_discount) * quantity"
},
"net_unit_discount": {
"type": "number",
"description": "Net discount on one item before taxes. **Needs to be a negative value.**"
},
"net_unit_price": {
"type": "number",
"description": "Net value of one item before taxes."
},
"quantity": {
"type": "integer",
"description": "Ordered quantity of the item.",
"format": "int32"
},
"tax_rate": {
"type": "number",
"description": "Tax rate applicable for the item given in percent."
},
"unit": {
"maxLength": 255,
"minLength": 0,
"type": "string",
"description": "Arbitrary measurement unit of the item, e.g. kg, litre, pieces."
}
},
"description": "List of special items contained in the transaction, e.g. shipping costs or discounts."
},
"UrlData": {
"type": "object",
"properties": {
"success_url": {
"type": "string",
"description": "The location where the buyer should be redirected to, when the transaction succeeds"
},
"cancel_url": {
"type": "string",
"description": "The location where the buyer should be redirected to, when the transaction gets canceled."
},
"failure_url": {
"type": "string",
"description": "The location where the buyer should be redirected to, when the transaction fails. "
},
"webhook_url": {
"type": "string",
"description": "The address of where the result of the transaction should be posted. See [its documentation](/apis/hpp/openapi/hpp_api/webhook-format/webhook) to get more details."
}
}
},
"VatDto": {
"required": [
"net_amount",
"tax_amount",
"tax_rate"
],
"type": "object",
"properties": {
"net_amount": {
"type": "number",
"description": "The net amount before taxes for the given tax rate."
},
"tax_amount": {
"type": "number",
"description": "The tax amount for the given tax rate."
},
"tax_rate": {
"type": "number",
"description": "Tax rate given as percentage on the net amount."
}
},
"description": "List of value-added tax (VAT) amounts."
},
"NotFoundErrorResponse": {
"required": [
"code"
],
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "\n INVALID_SESSION_MISSING_TRANSACTION_ID: The session is missing a transaction ID. \n SELLER_CONFIG_NOT_FOUND: Seller configuration not found for the provided token. \n ",
"enum": [
"SELLER_CONFIG_NOT_FOUND",
"INVALID_SESSION_MISSING_TRANSACTION_ID"
]
}
}
},
"UnauthorizedErrorResponse": {
"required": [
"code"
],
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "\n INVALID_TOKEN: The provided token is invalid or expired.\n \n ",
"enum": [
"INVALID_TOKEN"
]
}
}
},
"UnprocessableEntityErrorResponse": {
"required": [
"code"
],
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "\n INVALID_SESSION_STATE: The session is in an invalid state.\n CUSTOMER_CONTACT_DETAILS_MISSING: Customer contact details are missing. \n ",
"enum": [
"INVALID_SESSION_STATE",
"CUSTOMER_CONTACT_DETAILS_MISSING"
]
}
}
},
"SessionCreatedResponseDto": {
"required": [
"landing_page"
],
"type": "object",
"properties": {
"session_id": {
"type": "string"
},
"landing_page": {
"type": "string"
}
}
},
"DeclineDto": {
"type": "object",
"properties": {
"category": {
"type": "string"
},
"reasons": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"SessionRecordDto": {
"required": [
"session_id",
"session_status"
],
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "The identifier of the interaction with the user within the scope of the Hosted Payment Page"
},
"transaction_id": {
"type": "string",
"description": "The transaction identifier in Ratepay"
},
"partner_transaction_id": {
"type": "string",
"description": "The transaction identifier on the merchant side"
},
"shop_buyer_id": {
"type": "string",
"description": "The buyer identifier on the merchant side"
},
"session_status": {
"type": "string",
"enum": [
"CREATED",
"IN_PROGRESS",
"COMPLETED",
"ERROR",
"EXPIRED",
"CANCELED",
"FRAUD_CANCELLATION_REQUESTED",
"OTP_PENDING"
],
"description": "The current status of the record.
* CREATED - the session has just been created by the merchant, but the buyer still didn't do anything.
* IN_PROGRESS - the session is being processed by Ratepay.
* COMPLETED - the transaction has been successfully completed.
* ERROR - some processing error has happened (please refer to the field `decline_reasons`).
* EXPIRED - the buyer didn't take any action within 30 minutes.
* CANCELED - the buyer clicked on the cancel button.
* FRAUD_CANCELLATION_REQUESTED - Ratepay advises for this transaction to be canceled by the merchant.
* OTP_PENDING - the buyer has been requested to validate their phone number, and Ratepay is still waiting for the verification.
\n"
},
"decline_reasons": {
"$ref": "#/components/schemas/DeclineDto"
},
"created_date": {
"type": "string",
"description": "The date and time when the status was first created"
},
"updated_date": {
"type": "string",
"description": "The date and time when the status was last updated"
}
}
}
},
"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"
}
}
}
}