Skip to content
Developer
/
/
/
Change transaction

Payment OpenAPI Specification (version 2)

This is the documentation for the Ratepay Payment API v2. The API is still in development and subject to change. The documentation will evolve as the development of the API progresses.

Download OpenAPI description
payment_api.json
payment_api.yaml
Overview
URL

https://www.ratepay.com/

Ratepay

info@ratepay.com

Languages
Servers
Ratepay Integration Platform

https://api-integration.ratepay.com/transaction/management/

Ratepay Production Platform

https://api.ratepay.com/transaction/management/

Transaction management

Operations

Authorize transaction

Request

Perform an authorization request for a transaction.

Security
Bearer Authentication
Headers
Idempotency-Keystring<= 64 characters

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 for further details.

Preferstring

According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource.

Value"return=representation"
X-Partnerstring

The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.

Bodyapplication/jsonrequired
authorization_expiresstring(date-time)

The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to ISO 8601. If not given, a default expiry time is generated.

Example: "2025-04-02T16:15:18.823+02:00"
buyerobject(BuyerDto)required

The buyer that wants to place the transaction.

buyer.​billing_addressobject(AddressDto)required

The address of the recipient.

buyer.​billing_address.​citystring[ 2 .. 100 ] charactersrequired

The city of the address. Must be at least 2 non whitespace characters.

Example: "Berlin"
buyer.​billing_address.​country_codestring[A-Z]{2}required

The country of the address. Must conform with ISO 3166-1 alpha 2.

Example: "DE"
buyer.​billing_address.​streetstring[ 1 .. 100 ] charactersrequired

The name of the street.

Example: "Schönhauser Allee"
buyer.​billing_address.​street_additionstring[ 1 .. 50 ] characters

Additional information about the address, e.g. 2nd floor, c/o John Doe.

Example: "Seitenflügel, 2. HH"
buyer.​billing_address.​street_numberstring[ 1 .. 30 ] characters

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"
buyer.​billing_address.​zip_codestring[ 1 .. 10 ] charactersrequired

The zip or post code of the address. Must be valid according to zip format of given country code. See list of postal codes.

Example: "10439"
buyer.​companyobject(CompanyDto)

The company that wants to place the transaction. This implies a B2B transaction. Either provide a person or company but not both.

Example: null
buyer.​contactobject(ContactDto)required

The contact information of the buyer.

buyer.​contact.​emailstring[ 1 .. 100 ] characters[A-Za-z0-9!#$%&amp;'*+/=?^_`{|}~-]+(\.[A-Za-z...required

The email address of the buyer.

Example: "heinz.steeger@example.org"
buyer.​contact.​phonestring[ 6 .. 60 ] characters[+0-9/\\\- ().,;]*[0-9][+0-9/\\\- ().,;]*required

The phone number of the buyer. Has to have at least 6 digits without spaces.

Example: "+49 177 44455553"
buyer.​languagestring[a-z]{2}

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.

Example: "de"
buyer.​personobject(PersonDto)

The person that wants to place the transaction. This implies a B2C transaction. Either provide a person or company but not both.

buyer.​shop_buyer_idstring[ 1 .. 100 ] characters

The buyer ID of a regular customer. See regular customer documentation for details. Get an overview of key identifiers used in payment API.

Example: "shop-buyer-id-1234"
currencystring[A-Z]{3}required

The currency of all amounts pertaining to the transaction. Upper-case alphabetic code in accordance with ISO 4217.

Example: "EUR"
deliveryobject(DeliveryDto)

The delivery address and additional delivery parameters.

deviceobject(DeviceDto)

The device used to initiate the transaction.

optionsobject(OptionsDto)

The options controlling transaction processing.

partner_operation_idstring[ 0 .. 255 ] characters

Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an overview of key identifiers used in payment API.

Example: "partner-operation-id-1234"
partner_transaction_idstring[ 1 .. 50 ] characters

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 used in payment API.

Example: "partner-transaction-id-1234"
payment_detailsobject(PaymentDetailsRequestDto)

Provides details about the payment to be executed by Ratepay. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT.

Example: null
payment_methodobject(PaymentMethodDto)required

The payment method selected by the buyer.

payment_method.​payment_optionstringrequired

The payment option the buyer selected.

Enum"OPEN_INVOICE""PAY_NOW"
Example: "OPEN_INVOICE"
payment_method.​transfer_typestringrequired

The transfer type the buyer selected.

Enum"BANK_TRANSFER""SEPA_DIRECT_DEBIT"
Example: "BANK_TRANSFER"
shop_basketsArray of objects(ShopBasketDto)required

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 for additional details.

shop_baskets[].​gross_amountnumberdecimal places <= 2> 0required

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 for additional details.

Example: 67.6
shop_baskets[].​itemsArray of objects(ItemDto)[ 1 .. 2147483647 ] itemsrequired

List of items contained in the transaction.

shop_baskets[].​items[].​article_numberstring[ 1 .. 255 ] characters.*[\S].*

The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.

Example: "kitchen-utils-1"
shop_baskets[].​items[].​categorystring[ 0 .. 511 ] characters

Category for the item.

Example: "household"
shop_baskets[].​items[].​descriptionstring[ 0 .. 511 ] characters

Description of the item.

Example: "fruit knife with curved blade, 8 cm"
shop_baskets[].​items[].​gross_total_pricenumberdecimal places <= 2

Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity

Example: 33.8
shop_baskets[].​items[].​gross_unit_discountnumberdecimal places <= 2<= 0

Gross discount on one item after taxes. Needs to be a negative value.

Example: -1.55
shop_baskets[].​items[].​gross_unit_pricenumberdecimal places <= 2required

Gross value of one item before taxes. For the RETURN_FEE type, applicable only to the REFUND operation, the value must be negative.

Example: 18.45
shop_baskets[].​items[].​namestring[ 1 .. 255 ] charactersrequired

Name of the item.

Example: "fruit knife"
shop_baskets[].​items[].​net_total_pricenumberdecimal places <= 2

Net value including discount of these items before taxes. net_total_price = (net_unit_price + net_unit_discount) * quantity

Example: 28.4
shop_baskets[].​items[].​net_unit_discountnumberdecimal places <= 2<= 0

Net discount on one item before taxes. Needs to be a negative value.

Example: -1.3
shop_baskets[].​items[].​net_unit_pricenumberdecimal places <= 2

Net value of one item before taxes.

Example: 15.5
shop_baskets[].​items[].​quantitynumbermultiple of 1e-10>= 0required

Ordered quantity of the item.

Example: 2
shop_baskets[].​items[].​tax_ratenumberdecimal places <= 2[ 0 .. 1000 )required

Tax rate applicable for the item given in percent.

Example: 19
shop_baskets[].​items[].​unitstring[ 0 .. 255 ] characters

Arbitrary measurement unit of the item, e.g. kg, litre, pieces.

Example: "piece"
shop_baskets[].​partner_shop_idstring[ 1 .. 255 ] charactersrequired

The shop ID generated by the partner or provided upfront by Ratepay. Get an overview of key identifiers used in payment API.

Example: "partner-shop-id-1"
shop_baskets[].​shop_merchant_idstring[ 1 .. 255 ] characters

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 used in the payment API 2.0 for more details.

Example: "ratepay-merchant-id-123"
shop_baskets[].​shop_transaction_idstring[ 1 .. 127 ] charactersrequired

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.

Example: "shop-transaction-id-1234"
shop_baskets[].​special_itemsArray of objects(SpecialItemDto)

List of special items contained in the transaction, e.g. shipping costs or discounts.

shop_baskets[].​vatsArray of objects(VatDto)required

List of value-added tax (VAT) amounts.

shop_baskets[].​vats[].​net_amountnumberdecimal places <= 2> 0required

The net amount before taxes for the given tax rate.

Example: 56.81
shop_baskets[].​vats[].​tax_amountnumberdecimal places <= 2>= 0required

The tax amount for the given tax rate.

Example: 10.79
shop_baskets[].​vats[].​tax_ratenumberdecimal places <= 2[ 0 .. 1000 )required

Tax rate given as percentage on the net amount.

Example: 19
shopsArray of objects(ShopDto)

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.

curl -i -X POST \
  https://api-integration.ratepay.com/transaction/management/v2/transactions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Prefer: return=representation' \
  -H 'X-Partner: string' \
  -d '{
    "authorization_expires": "2025-04-02T16:15:18.823+02:00",
    "buyer": {
      "billing_address": {
        "city": "Berlin",
        "country_code": "DE",
        "street": "Schönhauser Allee",
        "street_addition": "Seitenflügel, 2. HH",
        "street_number": "84",
        "zip_code": "10439"
      },
      "company": null,
      "contact": {
        "email": "heinz.steeger@example.org",
        "phone": "+49 177 44455553"
      },
      "language": "de",
      "person": {
        "date_of_birth": "1971-05-19",
        "first_name": "Heinz",
        "last_name": "Steeger",
        "title": "Dr."
      },
      "shop_buyer_id": "shop-buyer-id-1234"
    },
    "currency": "EUR",
    "delivery": {
      "address": {
        "city": "Berlin",
        "country_code": "DE",
        "street": "Schönhauser Allee",
        "street_addition": "Seitenflügel, 2. HH",
        "street_number": "84",
        "zip_code": "10439"
      },
      "company": "Berlin Advertising Agency",
      "first_name": "Heinz",
      "full_name": null,
      "in_store_collect": null,
      "last_name": "Steeger",
      "pick_up_box": null,
      "pick_up_shop": null
    },
    "device": {
      "browser": {
        "language": "de-DE",
        "name": "Mozilla Firefox",
        "version": "94.0 (64-bit)"
      },
      "finger_print": "bc47575c-7f93-4bae-84dc-282edf6a5d85",
      "geo_location": {
        "latitude": 52.518368,
        "longitude": 13.325109
      },
      "http_forwarded_ip_address": "123.123.123.123",
      "risk": {
        "reasons": [
          "RISKY_DEVICE_BEHAVIOR"
        ],
        "score": 123
      },
      "screen": {
        "height": 1080,
        "width": 1920
      },
      "source_ip_address": "10.17.1.1",
      "token": "ade028c1-d2a2-4189-9214-e21089cd47f1"
    },
    "options": {
      "sales_channel": "POINT_OF_SALE"
    },
    "partner_operation_id": "partner-operation-id-1234",
    "partner_transaction_id": "partner-transaction-id-1234",
    "payment_details": null,
    "payment_method": {
      "payment_option": "OPEN_INVOICE",
      "transfer_type": "BANK_TRANSFER"
    },
    "shop_baskets": [
      {
        "gross_amount": 67.6,
        "items": [
          {
            "article_number": "kitchen-utils-1",
            "category": "household",
            "description": "fruit knife with curved blade, 8 cm",
            "gross_total_price": 33.8,
            "gross_unit_discount": -1.55,
            "gross_unit_price": 18.45,
            "name": "fruit knife",
            "net_total_price": 28.4,
            "net_unit_discount": -1.3,
            "net_unit_price": 15.5,
            "quantity": 2,
            "tax_rate": 19,
            "unit": "piece"
          }
        ],
        "partner_shop_id": "partner-shop-id-1",
        "shop_merchant_id": "ratepay-merchant-id-123",
        "shop_transaction_id": "shop-transaction-id-1234",
        "special_items": [
          {
            "article_number": "kitchen-utils-1",
            "category": "household",
            "description": "fruit knife with curved blade, 8 cm",
            "gross_total_price": 33.8,
            "gross_unit_discount": -1.55,
            "gross_unit_price": 18.45,
            "name": "fruit knife",
            "net_total_price": 28.4,
            "net_unit_discount": -1.3,
            "net_unit_price": 15.5,
            "quantity": 2,
            "tax_rate": 19,
            "type": "RETURN_FEE",
            "unit": "piece"
          }
        ],
        "vats": [
          {
            "net_amount": 56.81,
            "tax_amount": 10.79,
            "tax_rate": 19
          }
        ]
      }
    ],
    "shops": [
      {
        "correspondence_settings": {
          "branding_settings": {
            "highlight_color": "#badb11",
            "logo_position": "RIGHT",
            "logo_url": "https://cdn.example.com/a/b/c/logo-fruits-and-more_400x65.png"
          },
          "slangs": {
            "de": {
              "customer_service_contact": [
                "You can reach our customer service Mon - Sun 7 am to 8 pm",
                "by mail: customer-service@example.com",
                "by phone: 030 / 123 456 789",
                "contact form: example.com/contact"
              ],
              "formal_tone": "INFORMAL",
              "name_format": "FIRST_LAST_NAME",
              "salutation": "Hello",
              "transaction_type": "ORDER"
            },
            "en": {
              "customer_service_contact": [
                "You can reach our customer service Mon - Sun 7 am to 8 pm",
                "by mail: customer-service@example.com",
                "by phone: 030 / 123 456 789",
                "contact form: example.com/contact"
              ],
              "formal_tone": "INFORMAL",
              "name_format": "FIRST_LAST_NAME",
              "salutation": "Hello",
              "transaction_type": "ORDER"
            },
            "fr": {
              "customer_service_contact": [
                "You can reach our customer service Mon - Sun 7 am to 8 pm",
                "by mail: customer-service@example.com",
                "by phone: 030 / 123 456 789",
                "contact form: example.com/contact"
              ],
              "formal_tone": "INFORMAL",
              "name_format": "FIRST_LAST_NAME",
              "salutation": "Hello",
              "transaction_type": "ORDER"
            },
            "nl": {
              "customer_service_contact": [
                "You can reach our customer service Mon - Sun 7 am to 8 pm",
                "by mail: customer-service@example.com",
                "by phone: 030 / 123 456 789",
                "contact form: example.com/contact"
              ],
              "formal_tone": "INFORMAL",
              "name_format": "FIRST_LAST_NAME",
              "salutation": "Hello",
              "transaction_type": "ORDER"
            }
          }
        },
        "legal": {
          "commercial_register_number": "HRB 12345FF",
          "legal_form": "GmbH",
          "name": "Fruits and more GmbH"
        },
        "merchant": {
          "merchant_id": "ratepay-merchant-id-123",
          "merchant_name": "Merchant XYZ"
        },
        "merchant_category_code": "5499",
        "name": "fruits and more",
        "partner_shop_id": "partner-shop-id-1"
      }
    ]
  }'

Responses

Transaction authorized

Bodyapplication/hal+json
_linksobject(TransactionLinks)required

Links related to the resource following specification by IANA.

_links.​selfobject(TransactionSelfLink)required

The self relation identifying the transaction resource itself.

_links.​self.​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"
authorization_expiresstring(date-time)required

The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to ISO 8601.

createdstring(date-time)required

Timestamp with offset according to ISO 8601.

payment_detailsobject(PaymentDetailsMinimalResponseLegacyDto)

Provides details about the payment to be executed by the buyer (generated by Ratepay).

resultstringrequired

Indicates the outcome of the transaction request. Possible value : ACCEPTED – The transaction has been successfully authorized and can proceed to capture.

Example: "ACCEPTED"
ratepay_transaction_idstring[ 20 .. 127 ] characters[A-Za-z0-9-_]{20,127}required

ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an overview of key identifiers used in payment API.

Example: "scwBgARW-nE93I7_ywhp"
Response
application/hal+json
{
  "_links": {
    "self": { … }
  },
  "authorization_expires": "2019-08-24T14:15:22Z",
  "created": "2019-08-24T14:15:22Z",
  "payment_details": {
    "deposit_bank_account": { … },
    "ratepay_payment_reference": "ET1285368M8",
    "ratepay_payment_references": [ … ]
  },
  "result": "ACCEPTED",
  "ratepay_transaction_id": "scwBgARW-nE93I7_ywhp"
}

Retrieve transaction

Request

Retrieve attributes of an existing transaction including list of follow-up operations.

Security
Bearer Authentication
Path
ratepay_transaction_idstringrequired

ID of transaction to retrieve. Get an overview of key identifiers used in payment API.

Headers
Preferstring

According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource.

Value"return=representation"
X-Partnerstring

The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.

curl -i -X GET \
  'https://api-integration.ratepay.com/transaction/management/v2/transactions/{ratepay_transaction_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Prefer: return=representation' \
  -H 'X-Partner: string'

Responses

Transaction retrieved

Bodyapplication/hal+json
One of:

Includes only minimal set of attributes plus links to related resources.

_linksobject(LookupTransactionLinks)required

Links related to the resource following specification by IANA.

_links.​authorizationsArray of objects(IncrementalAuthorizationSelfLink)required

List of additional authorization resources belonging to this transaction.

_links.​authorizations[].​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/authorizations/9wdn0Fvkb9Zxsfiql5l6"
_links.​cancellationsArray of objects(CancellationSelfLink)required

List of cancellation resources belonging to this transaction.

_links.​cancellations[].​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/cancellations/aa7rth5-__GG44rdsasf"
_links.​capturesArray of objects(CaptureSelfLink)required

List of capture resources belonging to this transaction.

_links.​captures[].​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN"
_links.​refundsArray of objects(RefundSelfLink)required

List of refund resources belonging to this transaction.

_links.​refunds[].​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/refunds/9FkZsddr-MaFFFx7gAs_"
_links.​selfobject(TransactionSelfLink)required

The self relation identifying the transaction resource itself.

_links.​self.​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"
authorization_expiresstring(date-time)

The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to ISO 8601.

Example: "2025-04-02T16:15:18.823+02:00"
createdstring(date-time)required

Timestamp with offset according to ISO 8601.

declineobject(DeclineDto)

Information about why transaction was not accepted and declined.

payment_detailsobject(PaymentDetailsMinimalResponseDto)

Provides details about the payment to be either executed by the buyer or Ratepay depending on selected payment method.

ratepay_transaction_idstring[ 20 .. 127 ] characters[A-Za-z0-9-_]{20,127}required

ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an overview of key identifiers used in payment API.

Example: "scwBgARW-nE93I7_ywhp"
resultstring(TransactionStatus)required

Indicates the outcome of the transaction request. Possible values: ACCEPTED – The transaction has been successfully authorized and can proceed to capture. DECLINED – The transaction has been rejected; the merchant must not proceed with order fulfillment. OTP_REQUIRED – The buyer must complete OTP verification before the transaction can be finalized.

Enum"ACCEPTED""DECLINED""OTP_REQUIRED"
Example: "ACCEPTED"
Response
application/hal+json
{
  "_links": {
    "authorizations": [ … ],
    "cancellations": [ … ],
    "captures": [ … ],
    "refunds": [ … ],
    "self": { … }
  },
  "authorization_expires": "2025-04-02T16:15:18.823+02:00",
  "created": "2019-08-24T14:15:22Z",
  "decline": {
    "category": "BUYER_DATA",
    "reasons": [ … ]
  },
  "payment_details": {
    "deposit_bank_account": { … },
    "ratepay_payment_references": [ … ]
  },
  "ratepay_transaction_id": "scwBgARW-nE93I7_ywhp",
  "result": "ACCEPTED"
}

Change transaction

Request

Change attributes of an existing transaction.

Security
Bearer Authentication
Path
ratepay_transaction_idstringrequired

ID of transaction to change. Get an overview of key identifiers used in payment API.

Headers
X-Partnerstring

The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.

Bodyapplication/merge-patch+jsonrequired
authorization_expiresstring(date-time)required

Timestamp when the transaction should expire.

Example: "2025-04-02T16:15:18.823+02:00"
curl -i -X PATCH \
  'https://api-integration.ratepay.com/transaction/management/v2/transactions/{ratepay_transaction_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/merge-patch+json' \
  -H 'X-Partner: string' \
  -d '{
    "authorization_expires": "2025-04-02T16:15:18.823+02:00"
  }'

Responses

Transaction changed

Body*/*
object
Response
No content

Incremental authorization

Operations

Cancellation

Operations

Capture

Operations

Shipping information

Operations

Refund

Operations