Changelog

Changelog
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

2025-10-13 One Time Passcode (OTP)

We’ve added a new feature : One Time Passcode (OTP) — see details here . The transactionManagement endpoint now shows the transaction result (accepted, declined, or otp-required) along with related OTP decline reasons. Also, A new 202 status code is returned when result = OTP_REQUIRED, providing OTP validity, regeneration timing, localized messages, and verification endpoints.
2025-03-20 Optional header X-Partner

A new optional header was added to ALL requests. See for example create transaction If you are using a single credential set for multiple integrations, such as countries or brands associated with one company, you can use this header to specify the correct partner-id you want to work with.
2024-10-07 Optional shop-transaction-id

It is no longer required to include shop-transaction-id in each authorization request. This change introduces a new option to set shop-transaction-id value on capture transaction. This field must be included in at least one of the following requests: authorization or capture.
2024-08-01 Optional partner-transaction-id

It is no longer required to include partner-transaction-id in each authorization request. This change introduces a new option to set partner-transaction-id value on capture transaction. This field must be included in at least one of the following requests: authorization or capture.
2024-04-09 Extension of the shop_baskets Object in the Authorization Operation

This change introduces a new optional value shop_merchant_id for shop basket object in the Authorization operation. It informs Ratepay systems that a shop has a connection to a specific merchant, so that merchant-level risk settings can be applied.
2024-03-07 Extension of the shops Object in the Authorization Operation

This change introduces a new section for merchant details within the shops object in the Authorization operation. It enables the connection of shops to a specific merchant, allowing the configuration of a merchant-level set of settings in the Ratepay systems.
2023-10-13 Description of Expiration of Transactions

A follow-up operation might get rejected because the transaction expired. We added a new page describing how expiry works and how you can prevent a transaction from expiring.
2023-08-24 Description of Basket Amount Validation

Authorization a new transaction or any follow-up operation might be rejected if the gross amount of the basket doesn't match the sum of all items and special items given in the request. A new page describes in detail how basket amount validation works.
2023-08-23 Description of Key Identifiers Used

A new page was added describing the key identifiers and their use-cases used in payment API like ratepay_transaction_id, partner_shop_id, shop_buyer_id, etc.
2023-08-02 Lookup Incremental Authorizations: New Endpoints to GET Incremental Authorizations

Two new endpoints were added.
Retrieve all incremental authorizations of a transaction.
Retrieve a single incremental authorization of a transaction by providing the incremental authorization ID generated by Ratepay.
An API client can control the amount of information returned by setting the corresponding representation request header.
The responses only include accepted incremental authorizations. Hence, rejected incremental authorization attempts are not included in the response.
2023-07-14 Lookup Cancellations: New Endpoints to GET Cancellations

Two new endpoints were added.
Retrieve all cancellations of a transaction.
Retrieve a single cancellation of a transaction by providing the cancellation ID generated by Ratepay.
An API client can control the amount of information returned by setting the corresponding representation request header.
The responses only include accepted cancellations. Hence, rejected cancellation attempts are not included in the response.
The transaction is automatically cancelled when it expired. This cancellation resource is also returned by the endpoints.
2023-07-11 Lookup Refunds: New Endpoints to GET Refunds

Two new endpoints were added.
Retrieve all refunds of a transaction.
Retrieve a single refund of a transaction by providing the refund ID generated by Ratepay.
An API client can control the amount of information returned by setting the corresponding representation request header.
The responses only include accepted refunds. Hence, rejected refund attempts are not included in the response.
2023-07-03 Specify Buyer Return Fee in Refund Calls

When creating a new refund, you can now specify a buyer return fee. To specify a buyer return fee, add a special item of type RETURN FEE with a negative amount.
2023-06-29 Lookup Captures: New Endpoints to GET Captures

Two new endpoints were added.
Retrieve all captures of a transaction.
Retrieve a single capture of a transaction by providing the capture ID generated by Ratepay.
An API client can control the amount of information returned by setting the corresponding representation request header.
The responses only include accepted captures. Hence, rejected capture attempts are not included in the response.
2023-06-12 Lookup Transaction: New Endpoint to GET Transaction

A new endpoint to lookup a transaction is now available. This endpoint returns structural information about the transaction like buyer and delivery details. The response also includes links to all existing follow-up resources like captures and refunds.
An API client can control the amount of information returned by setting the corresponding representation request header.
The endpoint supports declined transactions, i.e. transactions not accepted by Ratepay. In case of declined transactions, it might happen that not all attributes are returned if they were missing or syntactically incorrect in original request.
Please note: This endpoint doesn't provide payment status information.
2023-05-15 Capture Transaction: New Optional Attribute - partner_invoice_id

The partner's invoice ID can now be optionally included in the capture call.
2023-04-25 All Follow-up Operations now support Marketplace Transactions

All follow-up operations like capture, refund, and cancellation can now be used on marketplace transactions. To identify the basket to capture, refund, cancel, etc., the basket's partner_shop_id must be included in the belonging request.
API documentation was updated, see:
2023-03-09 Capture Transaction: New Optional Attribute - partner_shop_id

The partner's shop ID can now be optionally included in the capture call. The new attribute is required for marketplace transactions to denote which basket is getting captured.
2023-01-27 Payment References as a List

When authorizing a new transaction, the response now contains a list of payment references. This is in preparation to allow transactions with multiple baskets, which require a different payment reference for each basket. For future integration, use new ratepay_payment_references list. The single value field ratepay_payment_reference is deprecated as of now.
2022-10-21 Request Custom Authorization Expiry

When creating a new transaction, you can now provide a custom expiry time in the authorization request. If the authorization request is accepted and the custom expiry time is within contractually agreed limits, the newly created transaction will expire at the given time.
2022-10-13 Change Transaction: Extend Authorization Expiry

A new endpoint to change existing transactions is now available. It is now possible to extend authorization expiry if contractually agreed.
2022-09-29 New Slangs Supported: French & Dutch

When providing correspondence settings for a shop while authorizing a transaction, it is now possible to define French and Dutch slangs. In addition, German slang is now optional.
2022-09-27 Optional Shop On-boarding

It is no longer required to include shop information in each authorization request. Shops can be on-boarded beforehand. Contact Ratepay to on-board your shop beforehand and get a valid partner shop ID. This ID must be used in the shop basket as each basket must be related to a shop.
2022-08-25 New Payment Method: Pay Now with SEPA Direct Debit

A new payment method is available. The buyer can pay immediately by SEPA direct debit. Besides specifying this payment method and transfer type while authorizating a new transaction, also a debit bank account must be given in payment details.
2022-08-12 Specify Sales Channel during Transaction Authorization

When authorizing a new transaction, a sales channel shall be provided. See sales channel option for details.
2022-06-09 Add Shipping Information to Capture

It is now possible to add shipping information to an existing capture. See add shipping information for details.
2022-05-19 Add Support for Incremental Authorization

It is now possible to increase the transaction amount after the transaction was created. You can extend the transaction with additional items by requesting an incremental authorization. See new endpoint incremental authorization for details.
2022-04-22 Add Support for Captures, Refunds and Cancellations with Items and Special Items

All follow-up operations can now contain items and special items, which were captured, refunded or cancelled.
2022-04-04 Regular Customer Support

It is now possible to mark a buyer as a
openapi: 3.0.1
info:
contact:
email: info@ratepay.com
name: Ratepay
url: https://www.ratepay.com/
description: 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.
title: Payment OpenAPI Specification
version: version 2
servers:
- description: Ratepay Integration Platform
  url: https://api-integration.ratepay.com/transaction/management
- description: Ratepay Production Platform
  url: https://api.ratepay.com/transaction/management
  security:
- Bearer Authentication: []
  paths:
  /v2/transactions:
  post:
  description: Perform an authorization request for a transaction.
  operationId: createTransaction
  parameters:
  - description: "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](/docs/developer/api_integration/payment_2.0/idempotency/)\
  \ for further details."
  in: header
  name: Idempotency-Key
  required: false
  schema:
  type: string
  maxLength: 64
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  requestBody:
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/TransactionRequestDto'
  required: true
  responses:
  "201":
  content:
  application/hal+json:
  schema:
  $ref: '#/components/schemas/TransactionMinimalResponseDto'
  description: Transaction authorized
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/TransactionBadRequestErrorDto'
  description: Bad request
  "422":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/TransactionCreateRejectedErrorResponseDto'
  description: Transaction declined
  "500":
  description: Technical problem
  summary: Authorize transaction
  tags:
  - Transaction management
  /v2/transactions/{ratepay_transaction_id}:
  get:
  description: Retrieve attributes of an existing transaction including list of
  follow-up operations.
  operationId: getTransaction
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/LookupTransactionMinimalResponseDto'
  - $ref: '#/components/schemas/LookupTransactionFullResponseDto'
  description: Transaction retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve transaction
  tags:
  - Transaction management
  patch:
  description: Change attributes of an existing transaction.
  operationId: change
  parameters:
  - description: "ID of transaction to change. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  requestBody:
  content:
  application/merge-patch+json:
  schema:
  $ref: '#/components/schemas/ChangeDto'
  required: true
  responses:
  "204":
  content:
  '*/*':
  schema:
  type: object
  description: Transaction changed
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "422":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ChangeRejectedErrorResponseDto'
  description: Change declined
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Change transaction
  tags:
  - Transaction management
  /v2/transactions/{ratepay_transaction_id}/authorizations:
  get:
  description: Retrieve all authorization resources of an existing transaction
  including their attributes.
  operationId: getAllAuthorizations
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/LookupAllIncrementalAuthsMinimalResponseDto'
  - $ref: '#/components/schemas/LookupAllIncrementalAuthsFullResponseDto'
  description: Authorizations retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve all authorizations
  tags:
  - Incremental authorization
  post:
  description: Increase the amount of a previously authorized transaction
  operationId: incrementalAuthorizationTransaction
  parameters:
  - description: "ID of transaction to extend with additional authorization. Get\
  \ an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "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](/docs/developer/api_integration/payment_2.0/idempotency/)\
  \ for further details."
  in: header
  name: Idempotency-Key
  required: false
  schema:
  type: string
  maxLength: 64
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  requestBody:
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/IncrementalAuthorizationRequestDto'
  required: true
  responses:
  "201":
  content:
  application/hal+json:
  schema:
  $ref: '#/components/schemas/IncrementalAuthorizationMinimalResponseDto'
  description: Authorization created
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "422":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/IncrementalAuthorizationCreateRejectedErrorResponseDto'
  description: Authorization declined
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Incrementally authorize transaction
  tags:
  - Incremental authorization
  /v2/transactions/{ratepay_transaction_id}/authorizations/{ratepay_authorization_id}:
  get:
  description: Retrieve an authorization resource of an existing transaction including
  its attributes.
  operationId: getSingleAuthorization
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "ID of authorization to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_authorization_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/IncrementalAuthorizationMinimalResponseDto'
  - $ref: '#/components/schemas/IncrementalAuthorizationFullResponseDto'
  description: Authorization retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve an authorization
  tags:
  - Incremental authorization
  /v2/transactions/{ratepay_transaction_id}/cancellations:
  get:
  description: Retrieve all cancellation resources of an existing transaction
  including their attributes.
  operationId: getAllCancellations
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/LookupAllCancellationsMinimalResponseDto'
  - $ref: '#/components/schemas/LookupAllCancellationsFullResponseDto'
  description: Cancellations retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve all cancellations
  tags:
  - Cancellation
  post:
  description: Cancel a previously authorized transaction
  operationId: cancelTransaction
  parameters:
  - description: "ID of transaction to cancel. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "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](/docs/developer/api_integration/payment_2.0/idempotency/)\
  \ for further details."
  in: header
  name: Idempotency-Key
  required: false
  schema:
  type: string
  maxLength: 64
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  requestBody:
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/CancellationRequestDto'
  required: true
  responses:
  "201":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/CancellationMinimalResponseDto'
  - $ref: '#/components/schemas/CancellationFullResponseDto'
  description: Cancellation created
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "422":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/CancellationRejectedErrorResponseDto'
  description: Cancellation declined
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Cancel transaction
  tags:
  - Cancellation
  /v2/transactions/{ratepay_transaction_id}/cancellations/{ratepay_cancellation_id}:
  get:
  description: Retrieve a cancellation resource of an existing transaction including
  its attributes.
  operationId: getSingleCancellation
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "ID of cancellation to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_cancellation_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/CancellationMinimalResponseDto'
  - $ref: '#/components/schemas/CancellationFullResponseDto'
  description: Cancellation retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve a cancellation
  tags:
  - Cancellation
  /v2/transactions/{ratepay_transaction_id}/captures:
  get:
  description: Retrieve all capture resources of an existing transaction including
  their attributes.
  operationId: getAllCaptures
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/LookupAllCapturesMinimalResponseDto'
  - $ref: '#/components/schemas/LookupAllCapturesFullResponseDto'
  description: Captures retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve all captures
  tags:
  - Capture
  post:
  description: Capture a previously authorized transaction
  operationId: captureTransaction
  parameters:
  - description: "ID of transaction to capture. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "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](/docs/developer/api_integration/payment_2.0/idempotency/)\
  \ for further details."
  in: header
  name: Idempotency-Key
  required: false
  schema:
  type: string
  maxLength: 64
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  requestBody:
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/CaptureRequestDto'
  required: true
  responses:
  "201":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/CaptureMinimalResponseDto'
  - $ref: '#/components/schemas/CaptureFullResponseDto'
  description: Capture created
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "422":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/CaptureCreateRejectedErrorResponseDto'
  description: Capture declined
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Capture transaction
  tags:
  - Capture
  /v2/transactions/{ratepay_transaction_id}/captures/{ratepay_capture_id}:
  get:
  description: Retrieve a capture resource of an existing transaction including
  its attributes.
  operationId: getSingleCapture
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "ID of capture to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_capture_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/CaptureMinimalResponseDto'
  - $ref: '#/components/schemas/CaptureFullResponseDto'
  description: Capture retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve a capture
  tags:
  - Capture
  /v2/transactions/{ratepay_transaction_id}/captures/{ratepay_capture_id}/shipping-information:
  post:
  description: Add shipping information to previously captured transaction
  operationId: addShippingInformation
  parameters:
  - description: "ID of transaction. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "ID of capture the shipping information should be added to. Get\
  \ an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_capture_id
  required: true
  schema:
  type: string
  - description: "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](/docs/developer/api_integration/payment_2.0/idempotency/)\
  \ for further details."
  in: header
  name: Idempotency-Key
  required: false
  schema:
  type: string
  maxLength: 64
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  requestBody:
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/ShippingInformationRequestDto'
  required: true
  responses:
  "201":
  content:
  application/hal+json:
  schema:
  $ref: '#/components/schemas/ShippingInformationMinimalResponseDto'
  description: Shipping information added
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction or capture not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Add shipping information
  tags:
  - Shipping information
  /v2/transactions/{ratepay_transaction_id}/refunds:
  get:
  description: Retrieve all refund resources of an existing transaction including
  their attributes.
  operationId: getAllRefunds
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/LookupAllRefundsMinimalResponseDto'
  - $ref: '#/components/schemas/LookupAllRefundsFullResponseDto'
  description: Refunds retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve all refunds
  tags:
  - Refund
  post:
  description: Refund a previously authorized and captured transaction
  operationId: refundTransaction
  parameters:
  - description: "ID of transaction to refund. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "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](/docs/developer/api_integration/payment_2.0/idempotency/)\
  \ for further details."
  in: header
  name: Idempotency-Key
  required: false
  schema:
  type: string
  maxLength: 64
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  requestBody:
  content:
  application/json:
  schema:
  $ref: '#/components/schemas/RefundRequestDto'
  required: true
  responses:
  "201":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/RefundMinimalResponseDto'
  - $ref: '#/components/schemas/RefundFullResponseDto'
  description: Refund created
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "422":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/RefundCreateRejectedErrorResponseDto'
  description: Refund declined
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Refund transaction
  tags:
  - Refund
  /v2/transactions/{ratepay_transaction_id}/refunds/{ratepay_refund_id}:
  get:
  description: Retrieve a refund resource of an existing transaction including
  its attributes.
  operationId: getSingleRefund
  parameters:
  - description: "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_transaction_id
  required: true
  schema:
  type: string
  - description: "ID of refund to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  in: path
  name: ratepay_refund_id
  required: true
  schema:
  type: string
  - description: "According to RFC 7240: Provide `return=representation` if you\
  \ prefer that the response to a request includes the current state of the\
  \ resource."
  in: header
  name: Prefer
  required: false
  schema:
  type: string
  enum:
  - return=representation
  responses:
  "200":
  content:
  application/hal+json:
  schema:
  oneOf:
  - $ref: '#/components/schemas/RefundMinimalResponseDto'
  - $ref: '#/components/schemas/RefundFullResponseDto'
  description: Refund retrieved
  "400":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/BadRequestErrorResponseDto'
  description: Bad request
  "404":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/ResourceNotFoundErrorResponseDto'
  description: Transaction not found
  "451":
  content:
  application/problem+json:
  schema:
  $ref: '#/components/schemas/LegalErrorResponseDto'
  description: Legally not allowed
  "500":
  description: Technical problem
  summary: Retrieve a refund
  tags:
  - Refund
  components:
  schemas:
  AddressDto:
  type: object
  description: The address of the recipient.
  properties:
  city:
  type: string
  description: The city of the address. Must be at least 2 non whitespace
  characters.
  example: Berlin
  maxLength: 100
  minLength: 2
  country_code:
  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
  pattern: "[A-Z]{2}"
  street:
  type: string
  description: The name of the street.
  example: Schönhauser Allee
  maxLength: 100
  minLength: 1
  street_addition:
  type: string
  description: "Additional information about the address, e.g. 2nd floor,\
  \ c/o John Doe."
  example: "Seitenflügel, 2. HH"
  maxLength: 50
  minLength: 1
  street_number:
  type: string
  description: The number describing where the building is located in the
  street.
  example: "84"
  maxLength: 30
  minLength: 1
  zip_code:
  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"
  maxLength: 10
  minLength: 1
  required:
  - city
  - country_code
  - street
  - zip_code
  BadRequestDeclineDto:
  type: object
  description: Information about why transaction was not accepted and declined.
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: SYNTAX
  invalid_fields:
  type: array
  description: List of one or multiple entries describing each failed validation.
  Only present if reason is `INVALID_FIELDS`.
  items:
  $ref: '#/components/schemas/InvalidField'
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - INVALID_FIELDS
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"INVALID_FIELDS\"]"
  required:
  - category
  - reasons
  BadRequestErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/BadRequestDeclineDto'
  required:
  - decline
  BankDetailsRequestDto:
  type: object
  description: The bank account Ratepay will use to deduct captured transaction
  amounts. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT.
  properties:
  bic:
  type: string
  description: "BIC of the bank, also known as SWIFT code, without any whitespaces.\
  \ Format as specified by [ISO 9362:2014](https://en.wikipedia.org/wiki/ISO_9362)."
  example: EXBANKXXX
  pattern: "[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?"
  iban:
  type: string
  description: "IBAN of the bank account. Any whitespaces will be removed.\
  \ Format as specified by [ISO 13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number)."
  example: DE12345678901234567890
  maxLength: 34
  minLength: 15
  owner:
  type: string
  description: Owner of the bank account.
  example: Heinz Steeger
  maxLength: 100
  minLength: 1
  pattern: "[A-Za-zäöüÄÖÜß0-9/.,+\\- ]*"
  required:
  - iban
  - owner
  BankDetailsResponseDto:
  type: object
  description: The bank account the buyer has to transfer the money to. Applicable
  only in case of transfer type BANK_TRANSFER.
  properties:
  bank_name:
  type: string
  description: Name of the bank.
  example: Example Bank
  maxLength: 127
  bic:
  type: string
  description: "BIC of the bank, also known as SWIFT code, without any whitespaces.\
  \ Format as specified by [ISO 9362:2014](https://en.wikipedia.org/wiki/ISO_9362)."
  example: EXBANKXXX
  pattern: "[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?"
  iban:
  type: string
  description: "IBAN of the bank account. Format as specified by [ISO 13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number)."
  example: DE12345678901234567890
  maxLength: 34
  minLength: 15
  owner:
  type: string
  description: Owner of the bank account.
  example: Ratepay GmbH
  maxLength: 100
  pattern: "[A-Za-zäöüÄÖÜß0-9/.,+\\- ]*"
  required:
  - bank_name
  - bic
  - iban
  - owner
  BrandingSettingsDto:
  type: object
  description: Shop branding settings for buyer correspondences.
  properties:
  highlight_color:
  type: string
  description: "The color for the highlighted elements in buyer correspondences\
  \ as HTML HEX color code, e.g. `#BADB11`."
  example: '#badb11'
  pattern: "#[a-fA-F0-9]{6}"
  logo_position:
  type: string
  description: Shop logo position in buyer correspondences.
  enum:
  - LEFT
  - RIGHT
  - CENTER
  example: RIGHT
  logo_url:
  type: string
  description: Publicly accessible shop logo to include in buyer correspondences.
  This must be a valid `https://` or `http://` URL.
  example: https://cdn.example.com/a/b/c/logo-fruits-and-more_400x65.png
  BrowserDto:
  type: object
  description: The browser used by the buyer.
  properties:
  language:
  type: string
  description: "The language used by the browser. Must conform to [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag)."
  example: de-DE
  pattern: "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-[A-Z]{2})?$"
  name:
  type: string
  description: The name of the used browser.
  example: Mozilla Firefox
  maxLength: 255
  minLength: 1
  version:
  type: string
  description: The version of the used browser.
  example: 94.0 (64-bit)
  maxLength: 255
  minLength: 1
  BuyerDto:
  type: object
  description: The buyer that wants to place the transaction.
  properties:
  billing_address:
  $ref: '#/components/schemas/AddressDto'
  company:
  $ref: '#/components/schemas/CompanyDto'
  contact:
  $ref: '#/components/schemas/ContactDto'
  language:
  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-1_codes)."
  example: de
  pattern: "[a-z]{2}"
  person:
  $ref: '#/components/schemas/PersonDto'
  shop_buyer_id:
  type: string
  description: "The buyer ID of a regular customer. See [regular customer\
  \ documentation](/docs/reporting/regular_customers/regular_customers_introduction/)\
  \ for details. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: shop-buyer-id-1234
  maxLength: 100
  minLength: 1
  required:
  - billing_address
  - contact
  CancellationFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of cancellation.
  properties:
  _links:
  $ref: '#/components/schemas/CancellationLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  gross_amount:
  type: number
  description: Amount to cancel given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of cancelled items
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: cancel-id-1234
  maxLength: 255
  minLength: 0
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  ratepay_cancellation_id:
  type: string
  description: "ID of confirmed cancellation (generated by Ratepay). Get an\
  \ [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: aa7rth5-__GG44rdsasf
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  special_items:
  type: array
  description: "List of cancelled special items, 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'
  required:
  - _links
  - created
  - gross_amount
  - ratepay_cancellation_id
  CancellationLinks:
  type: object
  description: "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml)."
  properties:
  self:
  $ref: '#/components/schemas/CancellationSelfLink'
  required:
  - self
  CancellationMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay during
  cancellation creation.
  properties:
  _links:
  $ref: '#/components/schemas/CancellationLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  ratepay_cancellation_id:
  type: string
  description: "ID of confirmed cancellation generated by Ratepay. Get an\
  \ [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: aa7rth5-__GG44rdsasf
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - ratepay_cancellation_id
  CancellationRejectedDeclineDto:
  type: object
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: UNPROCESSABLE_OPERATION
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - CANCELLATION_AMOUNT_TOO_HIGH
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"CANCELLATION_AMOUNT_TOO_HIGH\"]"
  required:
  - category
  CancellationRejectedErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/CancellationRejectedDeclineDto'
  required:
  - decline
  CancellationRequestDto:
  type: object
  properties:
  gross_amount:
  type: number
  description: Amount to cancel given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of cancelled items
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: cancel-id-1234
  maxLength: 255
  minLength: 0
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  special_items:
  type: array
  description: "List of cancelled special items, 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'
  required:
  - gross_amount
  CancellationSelfLink:
  type: object
  description: The self relation identifying the cancellation resource itself.
  properties:
  href:
  type: string
  description: URI pointing to resource itself.
  example: https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/cancellations/aa7rth5-__GG44rdsasf
  required:
  - href
  CaptureCreateRejectedDeclineDto:
  type: object
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: UNPROCESSABLE_OPERATION
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - CAPTURE_AMOUNT_TOO_HIGH
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"CAPTURE_AMOUNT_TOO_HIGH\"]"
  required:
  - category
  CaptureCreateRejectedErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/CaptureCreateRejectedDeclineDto'
  required:
  - decline
  CaptureFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of capture.
  properties:
  _links:
  $ref: '#/components/schemas/CaptureLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  gross_amount:
  type: number
  description: Amount to capture given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of captured items.
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_invoice_id:
  type: string
  description: Arbitrary invoice ID generated by partner.
  example: partner-invoice-id-1234
  maxLength: 50
  minLength: 0
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: capture-id-1234
  maxLength: 255
  minLength: 0
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  ratepay_capture_id:
  type: string
  description: "ID of confirmed capture (generated by Ratepay). Get an [overview\
  \ of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: BFNpWnim6LUDFQA8x3VN
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  special_items:
  type: array
  description: "List of captured special items, 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'
  required:
  - _links
  - created
  - gross_amount
  - ratepay_capture_id
  CaptureLinks:
  type: object
  description: "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml)."
  properties:
  self:
  $ref: '#/components/schemas/CaptureSelfLink'
  required:
  - self
  CaptureMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay during
  capture creation.
  properties:
  _links:
  $ref: '#/components/schemas/CaptureLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  ratepay_capture_id:
  type: string
  description: "ID of confirmed capture (generated by Ratepay). Get an [overview\
  \ of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: BFNpWnim6LUDFQA8x3VN
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - ratepay_capture_id
  CaptureRequestDto:
  type: object
  properties:
  gross_amount:
  type: number
  description: Amount to capture given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of captured items.
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_invoice_id:
  type: string
  description: Arbitrary invoice ID generated by partner.
  example: partner-invoice-id-1234
  maxLength: 50
  minLength: 0
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: capture-id-1234
  maxLength: 255
  minLength: 0
  partner_transaction_id:
  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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-transaction-id-1234
  maxLength: 50
  minLength: 1
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  special_items:
  type: array
  description: "List of captured special items, 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'
  required:
  - gross_amount
  CaptureSelfLink:
  type: object
  description: The self relation identifying the capture resource itself.
  properties:
  href:
  type: string
  description: URI pointing to resource itself.
  example: https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN
  required:
  - href
  ChangeDto:
  type: object
  properties:
  authorization_expires:
  type: string
  format: date-time
  description: Timestamp when the transaction should expire.
  example: 2024-10-08T13:34:10.205+02:00
  required:
  - authorization_expires
  ChangeRejectedErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/UnprocessableOperationNotAllowedForDeclinedTransaction'
  required:
  - decline
  CompanyDto:
  type: object
  description: The company that wants to place the transaction. This implies a
  B2B transaction. Either provide a person or company but not both.
  example: null
  properties:
  first_name:
  type: string
  description: The first name of the contact person within the company.
  example: Heinz
  maxLength: 100
  minLength: 1
  last_name:
  type: string
  description: The last name of the contact person within the company.
  example: Steeger
  maxLength: 100
  minLength: 1
  name:
  type: string
  description: "Official company name, should include legal form if applicable."
  example: Berlin Advertising Agency GmbH
  maxLength: 100
  minLength: 1
  vat_id:
  type: string
  description: Value-added tax ID of the company. This can be a European VAT
  ID or a local one.
  example: DE123456789
  maxLength: 20
  minLength: 1
  required:
  - name
  ContactDto:
  type: object
  description: The contact information of the buyer.
  properties:
  email:
  type: string
  description: The email address of the buyer.
  example: heinz.steeger@example.org
  maxLength: 100
  minLength: 1
  pattern: "[A-Za-z0-9!#$%&amp;'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&amp;'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\\
  .)+[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?"
  phone:
  type: string
  description: The phone number of the buyer. Has to have at least 6 digits
  without spaces.
  example: +49 177 44455553
  maxLength: 60
  minLength: 6
  pattern: "[+0-9/\\\\\\- ().,;]*[0-9][+0-9/\\\\\\- ().,;]*"
  required:
  - email
  - phone
  CorrespondenceSettingsDto:
  type: object
  description: Settings for buyer correspondences.
  properties:
  branding_settings:
  $ref: '#/components/schemas/BrandingSettingsDto'
  slangs:
  $ref: '#/components/schemas/SlangsDto'
  DeclineDto:
  type: object
  description: Information about why transaction was not accepted and declined.
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: BUYER_DATA
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - INVALID_BILLING_ADDRESS
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"INVALID_BILLING_ADDRESS\"]"
  required:
  - category
  - reasons
  DeliveryDto:
  type: object
  description: The delivery address and additional delivery parameters.
  properties:
  address:
  $ref: '#/components/schemas/AddressDto'
  company:
  type: string
  description: The company name of the recipient.
  example: Berlin Advertising Agency
  maxLength: 100
  minLength: 1
  first_name:
  type: string
  description: "The first name of the recipient. You shall also provide a\
  \ last name, but no full name."
  example: Heinz
  maxLength: 100
  minLength: 1
  full_name:
  type: string
  description: The full name of the recipient. You shall not provide first
  and last name.
  example: null
  maxLength: 200
  minLength: 1
  in_store_collect:
  $ref: '#/components/schemas/InStoreCollectDto'
  last_name:
  type: string
  description: "The last name of the recipient. You shall also provide a first\
  \ name, but no full name."
  example: Steeger
  maxLength: 100
  minLength: 1
  pick_up_box:
  $ref: '#/components/schemas/PickUpBoxDto'
  pick_up_shop:
  $ref: '#/components/schemas/PickUpShopDto'
  DeviceDto:
  type: object
  description: The device used to initiate the transaction.
  properties:
  browser:
  $ref: '#/components/schemas/BrowserDto'
  finger_print:
  type: string
  description: "A unique fingerprint to identify the buyer's device. This\
  \ fingerprint is generated by the partner. Provide this if you do not\
  \ integrate [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/).\
  \ Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: bc47575c-7f93-4bae-84dc-282edf6a5d85
  maxLength: 255
  minLength: 1
  geo_location:
  $ref: '#/components/schemas/GeoLocationDto'
  http_forwarded_ip_address:
  type: string
  description: The IP address given in the HTTP Forwarded header. Can be an
  IPv4 or IPv6 address.
  example: 123.123.123.123
  maxLength: 255
  minLength: 1
  risk:
  $ref: '#/components/schemas/RiskDto'
  screen:
  $ref: '#/components/schemas/ScreenDto'
  source_ip_address:
  type: string
  description: The IP address of the network client initiating the connection
  to the web shop. Can be an IPv4 or IPv6 address.
  example: 10.17.1.1
  maxLength: 255
  minLength: 1
  token:
  type: string
  description: "ID generated using [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/).\
  \ Include the generated token if you are using the device fingerprinting\
  \ feature in your integration. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: ade028c1-d2a2-4189-9214-e21089cd47f1
  maxLength: 255
  minLength: 1
  DeviceLookupResponseDto:
  type: object
  description: The device used to initiate the transaction.
  properties:
  token:
  type: string
  description: "ID generated using [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/).\
  \ Include the generated token if you are using the device fingerprinting\
  \ feature in your integration. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: ade028c1-d2a2-4189-9214-e21089cd47f1
  maxLength: 255
  minLength: 1
  GeoLocationDto:
  type: object
  description: The geographical position of the buyer's device.
  properties:
  latitude:
  type: number
  description: The latitude of the geographical position of the buyer's device.
  example: 52.518368
  longitude:
  type: number
  description: The longitude of the geographical position of the buyer's device.
  example: 13.325109
  InStoreCollectDto:
  type: object
  description: The information of the in-store collect.
  example: null
  properties:
  city:
  type: string
  description: The city of the address. Must be at least 2 non whitespace
  characters.
  example: Berlin
  maxLength: 100
  minLength: 2
  country_code:
  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
  pattern: "[A-Z]{2}"
  location_name:
  type: string
  description: The name of the collection location.
  example: Apotheke am Rathaus
  maxLength: 127
  minLength: 1
  street:
  type: string
  description: The name of the street.
  example: Hauptstraße
  maxLength: 100
  minLength: 1
  street_addition:
  type: string
  description: Additional information about the address.
  maxLength: 50
  minLength: 1
  street_number:
  type: string
  description: The number describing where the building is located in the
  street.
  example: "22"
  maxLength: 30
  minLength: 1
  zip_code:
  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"
  maxLength: 10
  minLength: 1
  required:
  - city
  - country_code
  - street
  - zip_code
  IncrementalAuthorizationCreateRejectedDeclineDto:
  type: object
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: UNPROCESSABLE_OPERATION
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT\"]"
  required:
  - category
  IncrementalAuthorizationCreateRejectedErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/IncrementalAuthorizationCreateRejectedDeclineDto'
  required:
  - decline
  IncrementalAuthorizationFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of authorization.
  properties:
  _links:
  $ref: '#/components/schemas/IncrementalAuthorizationLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  gross_amount:
  type: number
  description: Amount to increase given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of items to add.
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: authorization-id-1234
  maxLength: 255
  minLength: 0
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  ratepay_authorization_id:
  type: string
  description: "ID of confirmed authorization (generated by Ratepay). Get\
  \ an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: 9wdn0Fvkb9Zxsfiql5l6
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  special_items:
  type: array
  description: "List of special items to add, 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'
  required:
  - _links
  - created
  - gross_amount
  - ratepay_authorization_id
  IncrementalAuthorizationLinks:
  type: object
  description: "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml)."
  properties:
  self:
  $ref: '#/components/schemas/IncrementalAuthorizationSelfLink'
  required:
  - self
  IncrementalAuthorizationMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay during
  authorization creation.
  properties:
  _links:
  $ref: '#/components/schemas/IncrementalAuthorizationLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  ratepay_authorization_id:
  type: string
  description: "ID of confirmed authorization generated by Ratepay. Get an\
  \ [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: 9wdn0Fvkb9Zxsfiql5l6
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - ratepay_authorization_id
  IncrementalAuthorizationRequestDto:
  type: object
  properties:
  gross_amount:
  type: number
  description: Amount to increase given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of items to add.
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: authorization-id-1234
  maxLength: 255
  minLength: 0
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  special_items:
  type: array
  description: "List of special items to add, 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'
  required:
  - gross_amount
  IncrementalAuthorizationSelfLink:
  type: object
  description: The self relation identifying the authorization resource itself.
  properties:
  href:
  type: string
  description: URI pointing to resource itself.
  example: https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/authorizations/9wdn0Fvkb9Zxsfiql5l6
  required:
  - href
  InvalidField:
  type: object
  description: List of one or multiple entries describing each failed validation.
  Only present if reason is `INVALID_FIELDS`.
  properties:
  json_path:
  type: string
  description: The JSON path pointing to the location where the validation
  failed.
  example: partner_operation_id
  message:
  type: string
  description: A message describing which constraint was violated.
  example: size must be between 0 and 255
  required:
  - json_path
  - message
  ItemDto:
  type: object
  description: List of items to add.
  properties:
  article_number:
  type: string
  description: "The article number of the item, e.g. SKU. Not allowed to contain\
  \ only whitespaces."
  example: kitchen-utils-1
  maxLength: 255
  minLength: 1
  pattern: ".*[\\S].*"
  category:
  type: string
  description: Category for the item.
  example: household
  maxLength: 511
  minLength: 0
  description:
  type: string
  description: Description of the item.
  example: "fruit knife with curved blade, 8 cm"
  maxLength: 511
  minLength: 0
  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
  example: 33.8
  multipleOf: 0.01
  gross_unit_discount:
  type: number
  description: Gross discount on one item after taxes. Needs to be a negative
  value.
  example: -1.55
  exclusiveMaximum: false
  maximum: 0.0
  multipleOf: 0.01
  gross_unit_price:
  type: number
  description: Gross value of one item after taxes.
  example: 18.45
  multipleOf: 0.01
  name:
  type: string
  description: Name of the item.
  example: fruit knife
  maxLength: 255
  minLength: 1
  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
  example: 28.4
  multipleOf: 0.01
  net_unit_discount:
  type: number
  description: Net discount on one item before taxes. Needs to be a negative
  value.
  example: -1.3
  exclusiveMaximum: false
  maximum: 0.0
  multipleOf: 0.01
  net_unit_price:
  type: number
  description: Net value of one item before taxes.
  example: 15.5
  multipleOf: 0.01
  quantity:
  type: number
  description: Ordered quantity of the item.
  example: 2
  exclusiveMinimum: false
  minimum: 0.0
  multipleOf: 0.00000000010
  tax_rate:
  type: number
  description: Tax rate applicable for the item given in percent.
  example: 19.0
  exclusiveMaximum: true
  exclusiveMinimum: false
  maximum: 1000
  minimum: 0.0
  multipleOf: 0.01
  unit:
  type: string
  description: "Arbitrary measurement unit of the item, e.g. kg, litre, pieces."
  example: piece
  maxLength: 255
  minLength: 0
  required:
  - gross_unit_price
  - name
  - quantity
  - tax_rate
  LegalDeclineDto:
  type: object
  description: Information about why transaction was not accepted and declined.
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: LEGAL
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - ANONYMIZED_BY_BUYER
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"ANONYMIZED_BY_BUYER\"]"
  required:
  - category
  - reasons
  LegalErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/LegalDeclineDto'
  required:
  - decline
  LookupAllCancellationsFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of all cancellations.
  properties:
  _embedded:
  type: object
  properties:
  cancellations:
  type: array
  description: Embedded list of cancellations.
  items:
  $ref: '#/components/schemas/CancellationFullResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupAllCancellationsMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay.
  properties:
  _embedded:
  type: object
  properties:
  cancellations:
  type: array
  description: Embedded list of cancellations.
  items:
  $ref: '#/components/schemas/CancellationMinimalResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupAllCapturesFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of all captures.
  properties:
  _embedded:
  type: object
  properties:
  captures:
  type: array
  description: Embedded list of captures.
  items:
  $ref: '#/components/schemas/CaptureFullResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupAllCapturesMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay.
  properties:
  _embedded:
  type: object
  properties:
  captures:
  type: array
  description: Embedded list of captures.
  items:
  $ref: '#/components/schemas/CaptureMinimalResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupAllIncrementalAuthsFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of all incremental auths.
  properties:
  _embedded:
  type: object
  properties:
  authorizations:
  type: array
  description: Embedded list of incremental auths.
  items:
  $ref: '#/components/schemas/IncrementalAuthorizationFullResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupAllIncrementalAuthsMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay.
  properties:
  _embedded:
  type: object
  properties:
  authorizations:
  type: array
  description: Embedded list of incremental auths.
  items:
  $ref: '#/components/schemas/IncrementalAuthorizationMinimalResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupAllRefundsFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of all refunds.
  properties:
  _embedded:
  type: object
  properties:
  refunds:
  type: array
  description: Embedded list of refunds.
  items:
  $ref: '#/components/schemas/RefundFullResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupAllRefundsMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay.
  properties:
  _embedded:
  type: object
  properties:
  refunds:
  type: array
  description: Embedded list of refunds.
  items:
  $ref: '#/components/schemas/RefundMinimalResponseDto'
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - ratepay_transaction_id
  LookupTransactionFullResponseDto:
  type: object
  description: "This response is returned if representation header is specified.\
  \ Response includes all attributes of transaction plus links to related resources.\
  \ Note that in case of a declined transaction, all attributes are optional\
  \ as they may have not been present in the original request due to syntax\
  \ error."
  properties:
  _links:
  $ref: '#/components/schemas/LookupTransactionLinks'
  authorization_expires:
  type: string
  format: date-time
  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)."
  example: 2024-10-08T13:34:10.205+02:00
  buyer:
  $ref: '#/components/schemas/BuyerDto'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  currency:
  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)."
  example: EUR
  pattern: "[A-Z]{3}"
  decline:
  $ref: '#/components/schemas/DeclineDto'
  delivery:
  $ref: '#/components/schemas/DeliveryDto'
  device:
  $ref: '#/components/schemas/DeviceLookupResponseDto'
  options:
  $ref: '#/components/schemas/OptionsDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-operation-id-1234
  maxLength: 255
  partner_transaction_id:
  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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-transaction-id-1234
  maxLength: 50
  minLength: 1
  payment_details:
  $ref: '#/components/schemas/PaymentDetailsFullResponseDto'
  payment_method:
  $ref: '#/components/schemas/PaymentMethodDto'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  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](/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/ShopLookupResponseDto'
  required:
  - _links
  - created
  - ratepay_transaction_id
  LookupTransactionLinks:
  type: object
  description: "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml)."
  properties:
  authorizations:
  type: array
  description: List of additional authorization resources belonging to this
  transaction.
  items:
  $ref: '#/components/schemas/IncrementalAuthorizationSelfLink'
  cancellations:
  type: array
  description: List of cancellation resources belonging to this transaction.
  items:
  $ref: '#/components/schemas/CancellationSelfLink'
  captures:
  type: array
  description: List of capture resources belonging to this transaction.
  items:
  $ref: '#/components/schemas/CaptureSelfLink'
  refunds:
  type: array
  description: List of refund resources belonging to this transaction.
  items:
  $ref: '#/components/schemas/RefundSelfLink'
  self:
  $ref: '#/components/schemas/TransactionSelfLink'
  required:
  - authorizations
  - cancellations
  - captures
  - refunds
  - self
  LookupTransactionMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes plus links to related resources.
  properties:
  _links:
  $ref: '#/components/schemas/LookupTransactionLinks'
  authorization_expires:
  type: string
  format: date-time
  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)."
  example: 2024-10-08T13:34:10.205+02:00
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  decline:
  $ref: '#/components/schemas/DeclineDto'
  payment_details:
  $ref: '#/components/schemas/PaymentDetailsMinimalResponseDto'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - ratepay_transaction_id
  MerchantDto:
  type: 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."
  properties:
  merchant_id:
  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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in the payment API 2.0 for more details."
  example: ratepay-merchant-id-123
  maxLength: 255
  minLength: 1
  merchant_name:
  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."
  example: Merchant XYZ
  maxLength: 255
  minLength: 1
  OptionsDto:
  type: object
  description: The options controlling transaction processing.
  properties:
  sales_channel:
  type: string
  description: The sales channel the transaction originates from.
  enum:
  - WEBSHOP
  - POINT_OF_SALE
  - PHONE_OR_MAIL
  example: POINT_OF_SALE
  PaymentDetailsFullResponseDto:
  type: object
  description: Provides details about the payment to be either executed by the
  buyer or Ratepay depending on selected payment method.
  properties:
  debit_bank_account:
  $ref: '#/components/schemas/BankDetailsRequestDto'
  deposit_bank_account:
  $ref: '#/components/schemas/BankDetailsResponseDto'
  ratepay_payment_references:
  type: array
  description: List of payment references and the shop they belong to.
  items:
  $ref: '#/components/schemas/PaymentReferenceDto'
  PaymentDetailsMinimalResponseDto:
  type: object
  description: Provides details about the payment to be either executed by the
  buyer or Ratepay depending on selected payment method.
  properties:
  deposit_bank_account:
  $ref: '#/components/schemas/BankDetailsResponseDto'
  ratepay_payment_references:
  type: array
  description: List of payment references and the shop they belong to.
  items:
  $ref: '#/components/schemas/PaymentReferenceDto'
  PaymentDetailsMinimalResponseLegacyDto:
  type: object
  description: Provides details about the payment to be executed by the buyer
  (generated by Ratepay).
  properties:
  deposit_bank_account:
  $ref: '#/components/schemas/BankDetailsResponseDto'
  ratepay_payment_reference:
  type: string
  deprecated: true
  description: "Purpose to be indicated in the bank transfer (generated by\
  \ Ratepay). This is deprecated in favor of ratepay_payment_references.\
  \ Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: ET1285368M8
  maxLength: 127
  minLength: 1
  pattern: "[A-Za-z0-9 /-+]{1,127}"
  ratepay_payment_references:
  type: array
  description: List of payment references and the shop they belong to.
  items:
  $ref: '#/components/schemas/PaymentReferenceDto'
  PaymentDetailsRequestDto:
  type: object
  description: Provides details about the payment to be executed by Ratepay. Applicable
  only in case of transfer-type SEPA_DIRECT_DEBIT.
  example: null
  properties:
  debit_bank_account:
  $ref: '#/components/schemas/BankDetailsRequestDto'
  required:
  - debit_bank_account
  PaymentMethodDto:
  type: object
  description: The payment method selected by the buyer.
  properties:
  payment_option:
  type: string
  description: The payment option the buyer selected.
  enum:
  - OPEN_INVOICE
  - PAY_NOW
  example: OPEN_INVOICE
  transfer_type:
  type: string
  description: The transfer type the buyer selected.
  enum:
  - BANK_TRANSFER
  - SEPA_DIRECT_DEBIT
  example: BANK_TRANSFER
  required:
  - payment_option
  - transfer_type
  PaymentReferenceDto:
  type: object
  description: List of payment references and the shop they belong to.
  properties:
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  ratepay_payment_reference:
  type: string
  description: "Purpose to be indicated in the bank transfer (generated by\
  \ Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: ET1285368M8
  maxLength: 127
  minLength: 1
  pattern: "[A-Za-z0-9 /-+]{1,127}"
  required:
  - partner_shop_id
  - ratepay_payment_reference
  PersonDto:
  type: object
  description: The person that wants to place the transaction. This implies a
  B2C transaction. Either provide a person or company but not both.
  properties:
  date_of_birth:
  type: string
  format: date
  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)."
  example: 1971-05-19
  first_name:
  type: string
  description: The first name of the person.
  example: Heinz
  maxLength: 100
  minLength: 1
  last_name:
  type: string
  description: The last name of the person.
  example: Steeger
  maxLength: 100
  minLength: 1
  title:
  type: string
  description: The title of the person.
  example: Dr.
  maxLength: 45
  minLength: 1
  required:
  - date_of_birth
  - first_name
  - last_name
  PickUpBoxDto:
  type: object
  description: The information of the pick up box.
  example: null
  properties:
  carrier_name:
  type: string
  description: The name of the parcel carrier.
  example: DHL
  maxLength: 127
  minLength: 1
  city:
  type: string
  description: The city of the address. Must be at least 2 non whitespace
  characters.
  example: Berlin
  maxLength: 100
  minLength: 2
  country_code:
  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
  pattern: "[A-Z]{2}"
  location_id:
  type: string
  description: The ID of pick up location with the carrier.
  example: Packstation 985
  maxLength: 127
  minLength: 1
  recipient_account_id:
  type: string
  description: "The ID of the receiver with the carrier. It is optional only\
  \ for country_code AT, otherwise it is required."
  example: "445522299"
  maxLength: 127
  minLength: 1
  zip_code:
  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"
  maxLength: 10
  minLength: 1
  required:
  - city
  - country_code
  - location_id
  - zip_code
  PickUpShopDto:
  type: object
  description: The information of the pick up shop.
  example: null
  properties:
  city:
  type: string
  description: The city of the address. Must be at least 2 non whitespace
  characters.
  example: Berlin
  maxLength: 100
  minLength: 2
  country_code:
  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
  pattern: "[A-Z]{2}"
  location_name:
  type: string
  description: The name of the pick up shop.
  example: Kiosk am Stadtpark
  maxLength: 127
  minLength: 1
  street:
  type: string
  description: The name of the street.
  example: Fichtenweg
  maxLength: 100
  minLength: 1
  street_addition:
  type: string
  description: Additional information about the address.
  maxLength: 50
  minLength: 1
  street_number:
  type: string
  description: The number describing where the building is located in the
  street.
  example: 2b
  maxLength: 30
  minLength: 1
  zip_code:
  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"
  maxLength: 10
  minLength: 1
  required:
  - city
  - country_code
  - street
  - zip_code
  RefundCreateRejectedDeclineDto:
  type: object
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: UNPROCESSABLE_OPERATION
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - REFUND_AMOUNT_TOO_HIGH
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"REFUND_AMOUNT_TOO_HIGH\"]"
  required:
  - category
  RefundCreateRejectedErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/RefundCreateRejectedDeclineDto'
  required:
  - decline
  RefundFullResponseDto:
  type: object
  description: This response is returned if representation header is specified.
  Response includes all attributes of refund.
  properties:
  _links:
  $ref: '#/components/schemas/RefundLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  gross_amount:
  type: number
  description: Amount to refund given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of refunded items.
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: refund-id-1234
  maxLength: 255
  minLength: 0
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  ratepay_refund_id:
  type: string
  description: "ID of confirmed refund (generated by Ratepay). Get an [overview\
  \ of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: 9FkZsddr-MaFFFx7gAs_
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  special_items:
  type: array
  description: "List of refunded special items, 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'
  required:
  - _links
  - created
  - gross_amount
  - ratepay_refund_id
  RefundLinks:
  type: object
  description: "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml)."
  properties:
  self:
  $ref: '#/components/schemas/RefundSelfLink'
  required:
  - self
  RefundMinimalResponseDto:
  type: object
  description: Includes only minimal set of attributes generated by Ratepay during
  refund creation.
  properties:
  _links:
  $ref: '#/components/schemas/RefundLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  ratepay_refund_id:
  type: string
  description: "ID of confirmed refund generated by Ratepay. Get an [overview\
  \ of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: 9FkZsddr-MaFFFx7gAs_
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - ratepay_refund_id
  RefundRequestDto:
  type: object
  properties:
  gross_amount:
  type: number
  description: Amount to refund given in currency of original transaction.
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of refunded items.
  items:
  $ref: '#/components/schemas/ItemDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: refund-id-1234
  maxLength: 255
  minLength: 0
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API. This field is required in case of marketplace transaction."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  special_items:
  type: array
  description: "List of refunded special items, 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'
  required:
  - gross_amount
  RefundSelfLink:
  type: object
  description: The self relation identifying the refund resource itself.
  properties:
  href:
  type: string
  description: URI pointing to resource itself.
  example: https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/refunds/9FkZsddr-MaFFFx7gAs_
  required:
  - href
  ResourceNotFoundDeclineDto:
  type: object
  description: Information about why transaction was not accepted and declined.
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: RESOURCE_NOT_FOUND
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - TRANSACTION_NOT_FOUND
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"TRANSACTION_NOT_FOUND\"]"
  required:
  - category
  - reasons
  ResourceNotFoundErrorResponseDto:
  type: object
  properties:
  decline:
  $ref: '#/components/schemas/ResourceNotFoundDeclineDto'
  required:
  - decline
  RiskDto:
  type: object
  description: The risk associated with the buyer's device.
  properties:
  reasons:
  type: array
  description: List of reasons for the estimated risk.
  example:
  - RISKY_DEVICE_BEHAVIOR
  items:
  type: string
  description: List of reasons for the estimated risk.
  example: "[\"RISKY_DEVICE_BEHAVIOR\"]"
  maxLength: 255
  minLength: 1
  score:
  type: integer
  description: A numerical value for the estimated risk.
  example: 123
  maximum: 1000
  minimum: 1
  ScreenDto:
  type: object
  description: The dimensions of the buyer's screen.
  properties:
  height:
  type: integer
  description: The height of the buyer's screen in pixel.
  example: 1080
  maximum: 2147483647
  minimum: 0
  width:
  type: integer
  description: The width of the buyer's screen in pixel.
  example: 1920
  maximum: 2147483647
  minimum: 0
  ShippingInformationLinks:
  type: object
  description: "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml)."
  properties:
  self:
  $ref: '#/components/schemas/ShippingInformationSelfLink'
  required:
  - self
  ShippingInformationMinimalResponseDto:
  type: object
  properties:
  _links:
  $ref: '#/components/schemas/ShippingInformationLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  ratepay_shipping_information_id:
  type: string
  description: "ID of added shipping information generated by Ratepay. Get\
  \ an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: HR1iyZYradbGbvOQzZ79
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - ratepay_shipping_information_id
  ShippingInformationRequestDto:
  type: object
  properties:
  carrier_name:
  type: string
  description: Name of carrier responsible for shipment.
  enum:
  - DHL
  - POST_AUSTRIA
  - UPS
  - DPD
  - SWISS_POST
  - GLS
  - ASENDIA
  - HERMES_LOGISTICS
  - FEDEX
  - OTHER_WITH_TRACKING
  - OTHER_WITHOUT_TRACKING
  example: DHL
  tracking_number:
  type: string
  description: "Tracking number for delivery. This field is mandatory for\
  \ each carrier_name except: `OTHER_WITHOUT_TRACKING`"
  example: tracking-123456789
  maxLength: 127
  minLength: 1
  required:
  - carrier_name
  ShippingInformationSelfLink:
  type: object
  description: The self relation identifying the shipping information resource
  itself.
  properties:
  href:
  type: string
  description: URI pointing to resource itself.
  example: https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN/shipping-information/HR1iyZYradbGbvOQzZ79
  required:
  - href
  ShopBasketDto:
  type: object
  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](/docs/developer/api_integration/payment_2.0/basket_validation/)\
  \ for additional details."
  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](/docs/developer/api_integration/payment_2.0/basket_validation/)\
  \ for additional details."
  example: 67.6
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  items:
  type: array
  description: List of items contained in the transaction.
  items:
  $ref: '#/components/schemas/ItemDto'
  maxItems: 2147483647
  minItems: 1
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  shop_merchant_id:
  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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in the payment API 2.0 for more details."
  example: ratepay-merchant-id-123
  maxLength: 255
  minLength: 1
  shop_transaction_id:
  type: string
  description: "The transaction ID generated by the shop. 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
  maxLength: 127
  minLength: 1
  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'
  required:
  - gross_amount
  - items
  - partner_shop_id
  - shop_transaction_id
  - vats
  ShopDto:
  type: object
  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."
  properties:
  correspondence_settings:
  $ref: '#/components/schemas/CorrespondenceSettingsDto'
  legal:
  $ref: '#/components/schemas/ShopLegalDto'
  merchant:
  $ref: '#/components/schemas/MerchantDto'
  merchant_category_code:
  type: string
  description: "The branch of industry of the shop. Must conform to [ISO 18245](https://www.iso.org/standard/79450.html)."
  example: "5499"
  pattern: "[0-9]{4}"
  name:
  type: string
  description: The name of the shop. May differ from legal name.
  example: fruits and more
  maxLength: 255
  minLength: 2
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  required:
  - legal
  - merchant_category_code
  - name
  - partner_shop_id
  ShopLegalDto:
  type: object
  description: Legal information about the shop.
  properties:
  commercial_register_number:
  type: string
  description: The registration number the shop is filed under.
  example: HRB 12345FF
  maxLength: 12
  minLength: 2
  legal_form:
  type: string
  description: "The legal form as which the shop is registered, e.g. Ltd.,\
  \ GmbH, GbR, etc."
  example: GmbH
  maxLength: 255
  minLength: 2
  name:
  type: string
  description: The name of the shop as which it is registered.
  example: Fruits and more GmbH
  maxLength: 255
  minLength: 2
  required:
  - name
  ShopLookupResponseDto:
  type: object
  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."
  properties:
  merchant_category_code:
  type: string
  description: "The branch of industry of the shop. Must conform to [ISO 18245](https://www.iso.org/standard/79450.html)."
  example: "5499"
  pattern: "[0-9]{4}"
  partner_shop_id:
  type: string
  description: "The shop ID generated by the partner or provided upfront by\
  \ Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-shop-id-1
  maxLength: 255
  minLength: 1
  required:
  - merchant_category_code
  - partner_shop_id
  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.
  example:
  - 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"
  items:
  type: string
  description: List of 1 to 5 lines with correspondence information. Include
  how to reach customer support.
  example: "[\"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\"]"
  maxItems: 5
  minItems: 1
  formal_tone:
  type: string
  description: Formality level for the buyer correspondences.
  enum:
  - FORMAL
  - INFORMAL
  example: INFORMAL
  name_format:
  type: string
  description: Specifies how to visualize the buyer's name after the salutation
  in the buyer correspondences.
  enum:
  - EMPTY
  - FIRST_NAME
  - LAST_NAME
  - FIRST_LAST_NAME
  example: FIRST_LAST_NAME
  salutation:
  type: string
  description: "Word for salutation in the buyer correspondences in this language,\
  \ e.g. Hi, Hello, Hallo, Guten Tag, etc."
  example: Hello
  maxLength: 2147483647
  minLength: 1
  transaction_type:
  type: string
  description: Specifies how to call the transaction in buyer correspondences.
  enum:
  - ORDER
  - BOOKING
  example: ORDER
  SlangsDto:
  type: object
  description: Language settings for buyer correspondences.
  properties:
  de:
  $ref: '#/components/schemas/SlangDto'
  en:
  $ref: '#/components/schemas/SlangDto'
  fr:
  $ref: '#/components/schemas/SlangDto'
  nl:
  $ref: '#/components/schemas/SlangDto'
  SpecialItemDto:
  type: object
  description: "List of special items to add, e.g. shipping costs or discounts."
  properties:
  article_number:
  type: string
  description: "The article number of the item, e.g. SKU. Not allowed to contain\
  \ only whitespaces."
  example: kitchen-utils-1
  maxLength: 255
  minLength: 1
  pattern: ".*[\\S].*"
  category:
  type: string
  description: Category for the item.
  example: household
  maxLength: 511
  minLength: 0
  description:
  type: string
  description: Description of the item.
  example: "fruit knife with curved blade, 8 cm"
  maxLength: 511
  minLength: 0
  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
  example: 33.8
  multipleOf: 0.01
  gross_unit_discount:
  type: number
  description: Gross discount on one item after taxes. Needs to be a negative
  value.
  example: -1.55
  exclusiveMaximum: false
  maximum: 0.0
  multipleOf: 0.01
  gross_unit_price:
  type: number
  description: Gross value of one item after taxes.
  example: 18.45
  multipleOf: 0.01
  name:
  type: string
  description: Name of the item.
  example: fruit knife
  maxLength: 255
  minLength: 1
  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
  example: 28.4
  multipleOf: 0.01
  net_unit_discount:
  type: number
  description: Net discount on one item before taxes. Needs to be a negative
  value.
  example: -1.3
  exclusiveMaximum: false
  maximum: 0.0
  multipleOf: 0.01
  net_unit_price:
  type: number
  description: Net value of one item before taxes.
  example: 15.5
  multipleOf: 0.01
  quantity:
  type: number
  description: Ordered quantity of the item.
  example: 2
  exclusiveMinimum: false
  minimum: 0.0
  multipleOf: 0.00000000010
  tax_rate:
  type: number
  description: Tax rate applicable for the item given in percent.
  example: 19.0
  exclusiveMaximum: true
  exclusiveMinimum: false
  maximum: 1000
  minimum: 0.0
  multipleOf: 0.01
  type:
  type: string
  description: The special item type the buyer selected.
  enum:
  - RETURN_FEE
  example: RETURN_FEE
  unit:
  type: string
  description: "Arbitrary measurement unit of the item, e.g. kg, litre, pieces."
  example: piece
  maxLength: 255
  minLength: 0
  required:
  - gross_unit_price
  - name
  - quantity
  - tax_rate
  TransactionBadRequestErrorDto:
  type: object
  properties:
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  decline:
  $ref: '#/components/schemas/BadRequestDeclineDto'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - decline
  - ratepay_transaction_id
  TransactionCreateRejectedDeclineDto:
  type: object
  description: Information about why transaction was not accepted and declined.
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: CONTRACT
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - CURRENCY_NOT_ALLOWED
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"CURRENCY_NOT_ALLOWED\"]"
  required:
  - category
  TransactionCreateRejectedErrorResponseDto:
  type: object
  properties:
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  decline:
  $ref: '#/components/schemas/TransactionCreateRejectedDeclineDto'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - created
  - decline
  - ratepay_transaction_id
  TransactionLinks:
  type: object
  description: "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml)."
  properties:
  self:
  $ref: '#/components/schemas/TransactionSelfLink'
  required:
  - self
  TransactionMinimalResponseDto:
  type: object
  properties:
  _links:
  $ref: '#/components/schemas/TransactionLinks'
  authorization_expires:
  type: string
  format: date-time
  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)."
  created:
  type: string
  format: date-time
  description: "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)."
  payment_details:
  $ref: '#/components/schemas/PaymentDetailsMinimalResponseLegacyDto'
  ratepay_transaction_id:
  type: string
  description: "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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: scwBgARW-nE93I7_ywhp
  maxLength: 127
  minLength: 20
  pattern: "[A-Za-z0-9-_]{20,127}"
  required:
  - _links
  - authorization_expires
  - created
  - ratepay_transaction_id
  TransactionRequestDto:
  type: object
  properties:
  authorization_expires:
  type: string
  format: date-time
  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."
  example: 2024-10-08T13:34:10.205+02:00
  buyer:
  $ref: '#/components/schemas/BuyerDto'
  currency:
  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)."
  example: EUR
  pattern: "[A-Z]{3}"
  delivery:
  $ref: '#/components/schemas/DeliveryDto'
  device:
  $ref: '#/components/schemas/DeviceDto'
  options:
  $ref: '#/components/schemas/OptionsDto'
  partner_operation_id:
  type: string
  description: "Arbitrary ID of partner for the operation. This ID can be\
  \ displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-operation-id-1234
  maxLength: 255
  minLength: 0
  partner_transaction_id:
  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](/docs/developer/api_integration/payment_2.0/key_identifiers/)\
  \ used in payment API."
  example: partner-transaction-id-1234
  maxLength: 50
  minLength: 1
  payment_details:
  $ref: '#/components/schemas/PaymentDetailsRequestDto'
  payment_method:
  $ref: '#/components/schemas/PaymentMethodDto'
  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](/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'
  required:
  - buyer
  - currency
  - payment_method
  - shop_baskets
  TransactionSelfLink:
  type: object
  description: The self relation identifying the transaction resource itself.
  properties:
  href:
  type: string
  description: URI pointing to resource itself.
  example: https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp
  required:
  - href
  UnprocessableOperationNotAllowedForDeclinedTransaction:
  type: object
  properties:
  category:
  type: string
  description: "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ for details."
  enum:
  - BUYER_DATA
  - BUYER_IDENTITY
  - CONFLICT
  - CONTRACT
  - LEGAL
  - PAYMENT_ATTRIBUTE
  - RESOURCE_NOT_FOUND
  - RISK_DECISION
  - SYNTAX
  - TRANSACTION_RISK
  - UNPROCESSABLE_OPERATION
  example: UNPROCESSABLE_OPERATION
  reasons:
  type: array
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  example:
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  items:
  type: string
  description: "List of none, one or multiple reasons why the request was\
  \ declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/)\
  \ to learn about possible reasons for each decline category."
  enum:
  - INVALID_FIELDS
  - INVALID_JSON
  - INVALID_BILLING_ADDRESS
  - INVALID_BILLING_ADDRESS_ZIP_CODE
  - INVALID_DELIVERY_ADDRESS
  - INVALID_DELIVERY_ADDRESS_ZIP_CODE
  - CURRENCY_NOT_ALLOWED
  - ANONYMIZED_BY_BUYER
  - CANCELLATION_AMOUNT_TOO_HIGH
  - CANCELLATION_NOT_FOUND
  - CAPTURE_AMOUNT_TOO_HIGH
  - CAPTURE_NOT_FOUND
  - REFUND_NOT_FOUND
  - AUTHORIZATION_NOT_FOUND
  - NOT_ALLOWED_FOR_DECLINED_TRANSACTION
  - REFUND_AMOUNT_TOO_HIGH
  - TRANSACTION_NOT_FOUND
  - WRONG_NUMBER_OF_SHOP_BASKETS
  - WRONG_NUMBER_OF_SHOPS
  - MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED
  - BASKET_WITH_UNKNOWN_SHOP
  - BASKET_AMOUNT_TOO_LOW
  - BASKET_AMOUNT_TOO_HIGH
  - DELIVERY_COUNTRY_NOT_ALLOWED
  - BILLING_COUNTRY_NOT_ALLOWED
  - IDEMPOTENCY_KEY_ALREADY_USED
  - DELIVERY_TYPE_NOT_ALLOWED
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT
  - SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT
  - B2C_BUYER_NOT_ALLOWED
  - B2B_BUYER_NOT_ALLOWED
  - INVALID_PERSON_DATA
  - SALES_CHANNEL_NOT_ALLOWED
  - INVALID_IBAN
  - PAYMENT_METHOD_NOT_ALLOWED
  - SHOP_CREATION_NOT_ALLOWED
  - MAXIMUM_EXPIRY_EXCEEDED
  - NOT_ALLOWED_FOR_EXPIRED_TRANSACTION
  - MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED
  - MULTIPLE_RETURN_FEES_NOT_ALLOWED
  - RETURN_FEE_NOT_ALLOWED
  - PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS
  - DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED
  - DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED
  example: "[\"NOT_ALLOWED_FOR_DECLINED_TRANSACTION\"]"
  required:
  - category
  VatDto:
  type: object
  description: List of value-added tax (VAT) amounts.
  properties:
  net_amount:
  type: number
  description: The net amount before taxes for the given tax rate.
  example: 56.81
  exclusiveMinimum: true
  minimum: 0.0
  multipleOf: 0.01
  tax_amount:
  type: number
  description: The tax amount for the given tax rate.
  example: 10.79
  exclusiveMinimum: false
  minimum: 0.0
  multipleOf: 0.01
  tax_rate:
  type: number
  description: Tax rate given as percentage on the net amount.
  example: 19
  exclusiveMaximum: true
  exclusiveMinimum: false
  maximum: 1000
  minimum: 0.0
  multipleOf: 0.01
  required:
  - net_amount
  - tax_amount
  - tax_rate
  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
a regular customer when creating a transaction by providing the shop's ID of that buyer. See authorize transaction request for details.
2022-03-25 Added Support for Partial Captures

It is now possible to only capture a partial amount of the original transaction. Before, captures with amount lower than original transaction amount were rejected. See capture request documentation.
2022-03-17 Added Support for Pick-Up Locations

It is now possible to specify a pick-up location for delivery instead of a delivery address. The following types of pick-up locations are supported:
pick-up box - buyer collecting delivery at a delivery station
pick-up shop - buyer collecting delivery at a post office or similar
in-store collect
- buyer collecting delivery at a store of the merchant
2022-02-25 Added Support for B2B

A company can now be specified as buyer in authorization request. See company section in buyer .
A buyer must either be a company or person, but not both. By providing a company as buyer, request is considered to be B2B.
ChangelogCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

2025-10-13 One Time Passcode (OTP)

2025-03-20 Optional header X-Partner

2024-10-07 Optional shop-transaction-id

2024-08-01 Optional partner-transaction-id

2024-04-09 Extension of the shop_baskets Object in the Authorization Operation

2024-03-07 Extension of the shops Object in the Authorization Operation

2023-10-13 Description of Expiration of Transactions

2023-08-24 Description of Basket Amount Validation

2023-08-23 Description of Key Identifiers Used

2023-08-02 Lookup Incremental Authorizations: New Endpoints to GET Incremental Authorizations

2023-07-14 Lookup Cancellations: New Endpoints to GET Cancellations

2023-07-11 Lookup Refunds: New Endpoints to GET Refunds

2023-07-03 Specify Buyer Return Fee in Refund Calls

2023-06-29 Lookup Captures: New Endpoints to GET Captures

2023-06-12 Lookup Transaction: New Endpoint to GET Transaction

2023-05-15 Capture Transaction: New Optional Attribute - partner_invoice_id

2023-04-25 All Follow-up Operations now support Marketplace Transactions

2023-03-09 Capture Transaction: New Optional Attribute - partner_shop_id

2023-01-27 Payment References as a List

2022-10-21 Request Custom Authorization Expiry

2022-10-13 Change Transaction: Extend Authorization Expiry

2022-09-29 New Slangs Supported: French & Dutch

2022-09-27 Optional Shop On-boarding

2022-08-25 New Payment Method: Pay Now with SEPA Direct Debit

2022-08-12 Specify Sales Channel during Transaction Authorization

2022-06-09 Add Shipping Information to Capture

2022-05-19 Add Support for Incremental Authorization

2022-04-22 Add Support for Captures, Refunds and Cancellations with Items and Special Items

2022-04-04 Regular Customer Support

2022-03-25 Added Support for Partial Captures

2022-03-17 Added Support for Pick-Up Locations

2022-02-25 Added Support for B2B

Was this helpful?

Changelog
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
