Changelog

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.

1. Retrieve all incremental authorizations of a transaction .
2. 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.

1. Retrieve all cancellations of a transaction .
2. 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.

1. Retrieve all refunds of a transaction .
2. 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.

1. Retrieve all captures of a transaction .
2. 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 partnershopid must be included in the belonging request.

API documentation was updated, see:

• capture
• refund
• cancellation
• incremental authorization

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.

• Capture request
• Refund request
• Cancellation request

2022-04-04 Regular Customer Support

It is now possible to mark a buyer aopenapi: 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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 ." 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
    \ 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 ." 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 ." 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 ." 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 ." 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 ." 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
    \ 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
    \ 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
    \ 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 ." 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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 ." 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
    \ 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
    \ 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
    \ 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!#$% & '*+/=?^_`{|}~-] +( \ . [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
    \ 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
    \ 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 .
    \ Get an overview of 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 .
    \ Include the generated token if you are using the device fingerprinting
    \ feature in your integration. Get an overview of 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 .
    \ Include the generated token if you are using the device fingerprinting
    \ feature in your integration. Get an overview of 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
    \ 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
    \ 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
    \ 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 ." 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
    \ 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
    \ 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
    \ 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 ." 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 ." currency: type: string description: "The currency of all amounts pertaining to the transaction.
    \ Upper-case alphabetic code in accordance with 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
    \ 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
    \ 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
    \ 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 ." 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 ." example: 2024-10-08T13:34:10.205+02:00 created: type: string format: date-time description: "Timestamp with offset according to 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
    \ 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
    \ 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
    \ 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 ." 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 ." 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 ." 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 ." 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
    \ 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
    \ 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
    \ 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 ." 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
    \ 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
    \ 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
    \ 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
    \ 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 ." 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
    \ 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
    \ 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
    \ 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." 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 ." 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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 ." 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 ." created: type: string format: date-time description: "Timestamp with offset according to 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 ." 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ 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
    \ for obtaining a valid token." scheme: bearer type: http s a [regular customer](/docs/reporting/regular customers/regular customers introduction/) 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.