{ "openapi": "3.0.1", "info": { "contact": { "email": "info@ratepay.com", "name": "Ratepay", "url": "https://www.ratepay.com/" }, "description": "This is the documentation for the Ratepay Payment API v2. The API is still in development and subject to change. The documentation will evolve as the development of the API progresses.", "title": "Payment OpenAPI Specification", "version": "version 2" }, "servers": [ { "description": "Ratepay Integration Platform", "url": "https://api-integration.ratepay.com/transaction/management" }, { "description": "Ratepay Production Platform", "url": "https://api.ratepay.com/transaction/management" } ], "security": [ { "Bearer Authentication": [] } ], "paths": { "/v2/transactions": { "post": { "description": "Perform an authorization request for a transaction.", "operationId": "createTransaction", "parameters": [ { "description": "ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See [Idempotency](/docs/developer/api_integration/payment_2.0/idempotency/) for further details.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource. If not provided, the response will only contain the minimal set of attributes .", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequestDto" } } }, "required": true }, "responses": { "201": { "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/AuthorizationTransactionMinimalResponseDto" } } }, "description": "Transaction authorized" }, "202": { "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/TransactionMinimalResponseDtoOtpRequired" } } }, "description": "Transaction pre-authorized — buyer OTP verification required to complete payment" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TransactionBadRequestErrorDto" } } }, "description": "Bad request" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/TransactionCreateRejectedErrorResponseDto" } } }, "description": "Transaction declined" }, "500": { "description": "Technical problem" } }, "summary": "Authorize transaction", "tags": [ "Transaction management" ] } }, "/v2/transactions/{ratepay_transaction_id}": { "get": { "description": "Retrieve attributes of an existing transaction including list of follow-up operations.", "operationId": "getTransaction", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LookupTransactionMinimalResponseDto" }, { "$ref": "#/components/schemas/LookupTransactionFullResponseDto" } ] } } }, "description": "Transaction retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve transaction", "tags": [ "Transaction management" ] }, "patch": { "description": "Change attributes of an existing transaction.", "operationId": "change", "parameters": [ { "description": "ID of transaction to change. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/ChangeDto" } } }, "required": true }, "responses": { "204": { "content": { "*/*": { "schema": { "type": "object" } } }, "description": "Transaction changed" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ChangeRejectedErrorResponseDto" } } }, "description": "Change declined" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Change transaction", "tags": [ "Transaction management" ] } }, "/v2/transactions/{ratepay_transaction_id}/authorizations": { "get": { "description": "Retrieve all authorization resources of an existing transaction including their attributes.", "operationId": "getAllAuthorizations", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LookupAllIncrementalAuthsMinimalResponseDto" }, { "$ref": "#/components/schemas/LookupAllIncrementalAuthsFullResponseDto" } ] } } }, "description": "Authorizations retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve all authorizations", "tags": [ "Incremental authorization" ] }, "post": { "description": "Increase the amount of a previously authorized transaction", "operationId": "incrementalAuthorizationTransaction", "parameters": [ { "description": "ID of transaction to extend with additional authorization. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See [Idempotency](/docs/developer/api_integration/payment_2.0/idempotency/) for further details.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncrementalAuthorizationRequestDto" } } }, "required": true }, "responses": { "201": { "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/IncrementalAuthorizationMinimalResponseDto" } } }, "description": "Authorization created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/IncrementalAuthorizationCreateRejectedErrorResponseDto" } } }, "description": "Authorization declined" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Incrementally authorize transaction", "tags": [ "Incremental authorization" ] } }, "/v2/transactions/{ratepay_transaction_id}/authorizations/{ratepay_authorization_id}": { "get": { "description": "Retrieve an authorization resource of an existing transaction including its attributes.", "operationId": "getSingleAuthorization", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID of authorization to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_authorization_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/IncrementalAuthorizationMinimalResponseDto" }, { "$ref": "#/components/schemas/IncrementalAuthorizationFullResponseDto" } ] } } }, "description": "Authorization retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve an authorization", "tags": [ "Incremental authorization" ] } }, "/v2/transactions/{ratepay_transaction_id}/cancellations": { "get": { "description": "Retrieve all cancellation resources of an existing transaction including their attributes.", "operationId": "getAllCancellations", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LookupAllCancellationsMinimalResponseDto" }, { "$ref": "#/components/schemas/LookupAllCancellationsFullResponseDto" } ] } } }, "description": "Cancellations retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve all cancellations", "tags": [ "Cancellation" ] }, "post": { "description": "Cancel a previously authorized transaction", "operationId": "cancelTransaction", "parameters": [ { "description": "ID of transaction to cancel. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See [Idempotency](/docs/developer/api_integration/payment_2.0/idempotency/) for further details.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancellationRequestDto" } } }, "required": true }, "responses": { "201": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancellationMinimalResponseDto" }, { "$ref": "#/components/schemas/CancellationFullResponseDto" } ] } } }, "description": "Cancellation created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CancellationRejectedErrorResponseDto" } } }, "description": "Cancellation declined" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Cancel transaction", "tags": [ "Cancellation" ] } }, "/v2/transactions/{ratepay_transaction_id}/cancellations/{ratepay_cancellation_id}": { "get": { "description": "Retrieve a cancellation resource of an existing transaction including its attributes.", "operationId": "getSingleCancellation", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID of cancellation to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_cancellation_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancellationMinimalResponseDto" }, { "$ref": "#/components/schemas/CancellationFullResponseDto" } ] } } }, "description": "Cancellation retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve a cancellation", "tags": [ "Cancellation" ] } }, "/v2/transactions/{ratepay_transaction_id}/captures": { "get": { "description": "Retrieve all capture resources of an existing transaction including their attributes.", "operationId": "getAllCaptures", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LookupAllCapturesMinimalResponseDto" }, { "$ref": "#/components/schemas/LookupAllCapturesFullResponseDto" } ] } } }, "description": "Captures retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve all captures", "tags": [ "Capture" ] }, "post": { "description": "Capture a previously authorized transaction", "operationId": "captureTransaction", "parameters": [ { "description": "ID of transaction to capture. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See [Idempotency](/docs/developer/api_integration/payment_2.0/idempotency/) for further details.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureRequestDto" } } }, "required": true }, "responses": { "201": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CaptureMinimalResponseDto" }, { "$ref": "#/components/schemas/CaptureFullResponseDto" } ] } } }, "description": "Capture created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/CaptureCreateRejectedErrorResponseDto" } } }, "description": "Capture declined" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Capture transaction", "tags": [ "Capture" ] } }, "/v2/transactions/{ratepay_transaction_id}/captures/{ratepay_capture_id}": { "get": { "description": "Retrieve a capture resource of an existing transaction including its attributes.", "operationId": "getSingleCapture", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID of capture to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_capture_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CaptureMinimalResponseDto" }, { "$ref": "#/components/schemas/CaptureFullResponseDto" } ] } } }, "description": "Capture retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve a capture", "tags": [ "Capture" ] } }, "/v2/transactions/{ratepay_transaction_id}/captures/{ratepay_capture_id}/shipping-information": { "post": { "description": "Add shipping information to previously captured transaction", "operationId": "addShippingInformation", "parameters": [ { "description": "ID of transaction. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID of capture the shipping information should be added to. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_capture_id", "required": true, "schema": { "type": "string" } }, { "description": "ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See [Idempotency](/docs/developer/api_integration/payment_2.0/idempotency/) for further details.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingInformationRequestDto" } } }, "required": true }, "responses": { "201": { "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/ShippingInformationMinimalResponseDto" } } }, "description": "Shipping information added" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction or capture not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Add shipping information", "tags": [ "Shipping information" ] } }, "/v2/transactions/{ratepay_transaction_id}/refunds": { "get": { "description": "Retrieve all refund resources of an existing transaction including their attributes.", "operationId": "getAllRefunds", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LookupAllRefundsMinimalResponseDto" }, { "$ref": "#/components/schemas/LookupAllRefundsFullResponseDto" } ] } } }, "description": "Refunds retrieved" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Retrieve all refunds", "tags": [ "Refund" ] }, "post": { "description": "Refund a previously authorized and captured transaction", "operationId": "refundTransaction", "parameters": [ { "description": "ID of transaction to refund. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See [Idempotency](/docs/developer/api_integration/payment_2.0/idempotency/) for further details.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequestDto" } } }, "required": true }, "responses": { "201": { "content": { "application/hal+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RefundMinimalResponseDto" }, { "$ref": "#/components/schemas/RefundFullResponseDto" } ] } } }, "description": "Refund created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponseDto" } } }, "description": "Bad request" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ResourceNotFoundErrorResponseDto" } } }, "description": "Transaction not found" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/RefundCreateRejectedErrorResponseDto" } } }, "description": "Refund declined" }, "451": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/LegalErrorResponseDto" } } }, "description": "Legally not allowed" }, "500": { "description": "Technical problem" } }, "summary": "Refund transaction", "tags": [ "Refund" ] } }, "/v2/transactions/{ratepay_transaction_id}/refunds/{ratepay_refund_id}": { "get": { "description": "Retrieve a refund resource of an existing transaction including its attributes.", "operationId": "getSingleRefund", "parameters": [ { "description": "ID of transaction to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_transaction_id", "required": true, "schema": { "type": "string" } }, { "description": "ID of refund to retrieve. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "in": "path", "name": "ratepay_refund_id", "required": true, "schema": { "type": "string" } }, { "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.", "in": "header", "name": "Prefer", "required": false, "schema": { "type": "string", "enum": [ "return=representation" ] } }, { "description": "The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company.", "in": "header", "name": "X-Partner", "required": false, "schema": { "type": "string" } } ], "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. Notice that it **must** be sent in either this field or in `street`. For example, if the `street` field contains \"Musterstraße 1, then it is not needed to supply data here. But if `street` only contains \"Musterstraße\", then `street_number` must contain \"1\".", "example": "84", "maxLength": 30, "minLength": 1 }, "zip_code": { "type": "string", "description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).", "example": "10439", "maxLength": 10, "minLength": 1 } }, "required": [ "city", "country_code", "street", "zip_code" ] }, "BadRequestDeclineDto": { "type": "object", "description": "Information about why transaction was not accepted and declined.", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "SYNTAX" }, "invalid_fields": { "type": "array", "description": "List of one or multiple entries describing each failed validation. Only present if reason is `INVALID_FIELDS`.", "items": { "$ref": "#/components/schemas/InvalidField" } }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "INVALID_FIELDS" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED", "OTP_VERIFICATION_REQUIRED_BUT_FEATURE_NOT_ENABLED", "ORDER_WITH_PHONE_INTELLIGENCE_FRAUD_SUSPICION_BLOCKLISTED", "OTP_FAILED", "OTP_EXPIRED" ], "example": "[\"INVALID_FIELDS\"]" } } }, "required": [ "category", "reasons" ] }, "BadRequestErrorResponseDto": { "type": "object", "properties": { "decline": { "$ref": "#/components/schemas/BadRequestDeclineDto" } }, "required": [ "decline" ] }, "BankDetailsRequestDto": { "type": "object", "description": "The bank account Ratepay will use to deduct captured transaction amounts. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT.", "properties": { "bic": { "type": "string", "description": "BIC of the bank, also known as SWIFT code, without any whitespaces. Format as specified by [ISO 9362:2014](https://en.wikipedia.org/wiki/ISO_9362).", "example": "EXBANKXXX", "pattern": "[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?" }, "iban": { "type": "string", "description": "IBAN of the bank account. Any whitespaces will be removed. Format as specified by [ISO 13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "example": "DE12345678901234567890", "maxLength": 34, "minLength": 15 }, "owner": { "type": "string", "description": "Owner of the bank account.", "example": "Heinz Steeger", "maxLength": 100, "minLength": 1, "pattern": "[A-Za-zäöüÄÖÜß0-9/.,+\\- ]*" } }, "required": [ "iban", "owner" ] }, "BankDetailsResponseDto": { "type": "object", "description": "The bank account the buyer has to transfer the money to. Applicable only in case of transfer type BANK_TRANSFER.", "properties": { "bank_name": { "type": "string", "description": "Name of the bank.", "example": "Example Bank", "maxLength": 127 }, "bic": { "type": "string", "description": "BIC of the bank, also known as SWIFT code, without any whitespaces. Format as specified by [ISO 9362:2014](https://en.wikipedia.org/wiki/ISO_9362).", "example": "EXBANKXXX", "pattern": "[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?" }, "iban": { "type": "string", "description": "IBAN of the bank account. Format as specified by [ISO 13616:2020](https://en.wikipedia.org/wiki/International_Bank_Account_Number).", "example": "DE12345678901234567890", "maxLength": 34, "minLength": 15 }, "owner": { "type": "string", "description": "Owner of the bank account.", "example": "Ratepay GmbH", "maxLength": 100, "pattern": "[A-Za-zäöüÄÖÜß0-9/.,+\\- ]*" } }, "required": [ "bank_name", "bic", "iban", "owner" ] }, "BrandingSettingsDto": { "type": "object", "description": "Shop branding settings for buyer correspondences.", "properties": { "highlight_color": { "type": "string", "description": "The color for the highlighted elements in buyer correspondences as HTML HEX color code, e.g. `#BADB11`.", "example": "#badb11", "pattern": "#[a-fA-F0-9]{6}" }, "logo_position": { "type": "string", "description": "Shop logo position in buyer correspondences.", "enum": [ "LEFT", "RIGHT", "CENTER" ], "example": "RIGHT" }, "logo_url": { "type": "string", "description": "Publicly accessible shop logo to include in buyer correspondences. This must be a valid `https://` or `http://` URL.", "example": "https://cdn.example.com/a/b/c/logo-fruits-and-more_400x65.png" } } }, "BrowserDto": { "type": "object", "description": "The browser used by the buyer.", "properties": { "language": { "type": "string", "description": "The language used by the browser. Must conform to [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag).", "example": "de-DE", "pattern": "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-[A-Z]{2})?$" }, "name": { "type": "string", "description": "The name of the used browser.", "example": "Mozilla Firefox", "maxLength": 255, "minLength": 1 }, "version": { "type": "string", "description": "The version of the used browser.", "example": "94.0 (64-bit)", "maxLength": 255, "minLength": 1 } } }, "BuyerDto": { "type": "object", "description": "The buyer that wants to place the transaction.", "properties": { "billing_address": { "$ref": "#/components/schemas/AddressDto" }, "company": { "$ref": "#/components/schemas/CompanyDto" }, "contact": { "$ref": "#/components/schemas/ContactDto" }, "language": { "type": "string", "description": "The language in which the buyer prefers communication to be done. If the preferred language is not supported, the buyer communication will be in German. Must conform to [ISO 639-1 alpha 2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).", "example": "de", "pattern": "[a-z]{2}" }, "person": { "$ref": "#/components/schemas/PersonDto" }, "shop_buyer_id": { "type": "string", "description": "The buyer ID of a regular customer. See [regular customer documentation](/docs/reporting/regular_customers/regular_customers_introduction/) for details. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "shop-buyer-id-1234", "maxLength": 100, "minLength": 1 } }, "required": [ "billing_address", "contact" ] }, "CancellationFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of cancellation.", "properties": { "_links": { "$ref": "#/components/schemas/CancellationLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "gross_amount": { "type": "number", "description": "Amount to cancel given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of cancelled items", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "cancel-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "ratepay_cancellation_id": { "type": "string", "description": "ID of confirmed cancellation (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "aa7rth5-__GG44rdsasf", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "special_items": { "type": "array", "description": "List of cancelled special items, e.g. shipping costs or discounts.", "items": { "$ref": "#/components/schemas/SpecialItemDto" } }, "vats": { "type": "array", "description": "List of value-added tax (VAT) amounts.", "items": { "$ref": "#/components/schemas/VatDto" } } }, "required": [ "_links", "created", "gross_amount", "ratepay_cancellation_id" ] }, "CancellationLinks": { "type": "object", "description": "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "properties": { "self": { "$ref": "#/components/schemas/CancellationSelfLink" } }, "required": [ "self" ] }, "CancellationMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay during cancellation creation.", "properties": { "_links": { "$ref": "#/components/schemas/CancellationLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "ratepay_cancellation_id": { "type": "string", "description": "ID of confirmed cancellation generated by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "aa7rth5-__GG44rdsasf", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "created", "ratepay_cancellation_id" ] }, "CancellationRejectedDeclineDto": { "type": "object", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "UNPROCESSABLE_OPERATION" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "CANCELLATION_AMOUNT_TOO_HIGH" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ], "example": "[\"CANCELLATION_AMOUNT_TOO_HIGH\"]" } } }, "required": [ "category" ] }, "CancellationRejectedErrorResponseDto": { "type": "object", "properties": { "decline": { "$ref": "#/components/schemas/CancellationRejectedDeclineDto" } }, "required": [ "decline" ] }, "CancellationRequestDto": { "type": "object", "properties": { "gross_amount": { "type": "number", "description": "Amount to cancel given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of cancelled items", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "cancel-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "special_items": { "type": "array", "description": "List of cancelled special items, e.g. shipping costs or discounts.", "items": { "$ref": "#/components/schemas/SpecialItemDto" } }, "vats": { "type": "array", "description": "List of value-added tax (VAT) amounts.", "items": { "$ref": "#/components/schemas/VatDto" } } }, "required": [ "gross_amount" ] }, "CancellationSelfLink": { "type": "object", "description": "The self relation identifying the cancellation resource itself.", "properties": { "href": { "type": "string", "description": "URI pointing to resource itself.", "example": "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/cancellations/aa7rth5-__GG44rdsasf" } }, "required": [ "href" ] }, "CaptureCreateRejectedDeclineDto": { "type": "object", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "UNPROCESSABLE_OPERATION" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "CAPTURE_AMOUNT_TOO_HIGH" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ], "example": "[\"CAPTURE_AMOUNT_TOO_HIGH\"]" } } }, "required": [ "category" ] }, "CaptureCreateRejectedErrorResponseDto": { "type": "object", "properties": { "decline": { "$ref": "#/components/schemas/CaptureCreateRejectedDeclineDto" } }, "required": [ "decline" ] }, "CaptureFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of capture.", "properties": { "_links": { "$ref": "#/components/schemas/CaptureLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "gross_amount": { "type": "number", "description": "Amount to capture given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of captured items.", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_invoice_id": { "type": "string", "description": "Arbitrary invoice ID generated by partner.", "example": "partner-invoice-id-1234", "maxLength": 50, "minLength": 0 }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "capture-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "partner_transaction_id": { "type": "string", "description": "The transaction ID generated by the partner. **This field must be included in at least one of the following requests: authorization or capture.** This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.\n", "example": "partner-transaction-id-1234", "maxLength": 50, "minLength": 1 }, "ratepay_capture_id": { "type": "string", "description": "ID of confirmed capture (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "BFNpWnim6LUDFQA8x3VN", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "shop_transaction_id": { "type": "string", "description": "The transaction ID generated by the shop. **This field must be included in at least one of the following requests: authorization or capture.** This ID must be known to the buyer and is used for buyer communication, e.g. correspondences and buyer support.\n", "example": "shop-transaction-id-1234", "maxLength": 127, "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": [ "_links", "created", "gross_amount", "ratepay_capture_id" ] }, "CaptureLinks": { "type": "object", "description": "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "properties": { "self": { "$ref": "#/components/schemas/CaptureSelfLink" } }, "required": [ "self" ] }, "CaptureMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay during capture creation.", "properties": { "_links": { "$ref": "#/components/schemas/CaptureLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "ratepay_capture_id": { "type": "string", "description": "ID of confirmed capture (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "BFNpWnim6LUDFQA8x3VN", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "created", "ratepay_capture_id" ] }, "CaptureRequestDto": { "type": "object", "properties": { "gross_amount": { "type": "number", "description": "Amount to capture given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of captured items.", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_invoice_id": { "type": "string", "description": "Arbitrary invoice ID generated by partner.", "example": "partner-invoice-id-1234", "maxLength": 50, "minLength": 0 }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "capture-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "partner_transaction_id": { "type": "string", "description": "The transaction ID generated by the partner (i.e. Partner Order ID). Identical to shop_transaction_id for single‑entity merchants. **This field must be included in at least one of the following requests: authorization or capture.** This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.\n", "example": "partner-transaction-id-1234", "maxLength": 50, "minLength": 1 }, "shop_transaction_id": { "type": "string", "description": "The transaction ID generated by the shop (i.e. Shop Order ID). Differs from partner_transaction_id only in multi-entity scenarios. **This field must be included in at least one of the following requests: authorization or capture.** This ID must be known to the buyer and is used for buyer communication, e.g. correspondences and buyer support.\n", "example": "shop-transaction-id-1234", "maxLength": 127, "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", "shop_transaction_id", "partner_transaction_id" ] }, "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": "2025-04-02T16:15:18.823+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]([A-Za-z0-9-]*[A-Za-z0-9])?" }, "phone": { "type": "string", "description": "The phone number of the buyer. Has to have at least 6 digits without spaces.", "example": "+49 177 44455553", "maxLength": 60, "minLength": 6, "pattern": "[+0-9/\\\\\\- ().,;]*[0-9][+0-9/\\\\\\- ().,;]*" } }, "required": [ "email", "phone" ] }, "CorrespondenceSettingsDto": { "type": "object", "description": "Settings for buyer correspondences.", "properties": { "branding_settings": { "$ref": "#/components/schemas/BrandingSettingsDto" }, "slangs": { "$ref": "#/components/schemas/SlangsDto" } } }, "DeclineDto": { "type": "object", "description": "Information about why transaction was not accepted and declined.", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "BUYER_DATA" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "INVALID_BILLING_ADDRESS" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED", "OTP_VERIFICATION_REQUIRED_BUT_FEATURE_NOT_ENABLED", "ORDER_WITH_PHONE_INTELLIGENCE_FRAUD_SUSPICION_BLOCKLISTED", "OTP_FAILED", "OTP_EXPIRED" ], "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. If supplied, the field `last_name` becomes mandatory, and `full_name` must not be sent.", "example": "Heinz", "maxLength": 100, "minLength": 1 }, "full_name": { "type": "string", "description": "The full name of the recipient. If supplied, the fields `first_name` and `last_name` must not be sent.", "example": null, "maxLength": 200, "minLength": 1 }, "in_store_collect": { "$ref": "#/components/schemas/InStoreCollectDto" }, "last_name": { "type": "string", "description": "The last name of the recipient. If supplied, the field `first_name` becomes mandatory, and `full_name` must not be sent.", "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" }, "geo_location": { "$ref": "#/components/schemas/GeoLocationDto" }, "http_forwarded_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. It is **mandatory** in case of Online orders, but optional otherwise.", "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. It is **mandatory** in case of Online orders, but optional otherwise.", "example": "10.17.1.1", "maxLength": 255, "minLength": 1 } }, "oneOf": [ { "title": "WithToken", "description": "Use this variant when integrating Ratepay's device fingerprinting feature. Provide the token generated by the Ratepay script.", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "ID generated using [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/). Include the generated token if you are using the device fingerprinting feature in your integration.", "example": "ade028c1-d2a2-4189-9214-e21089cd47f1", "maxLength": 255, "minLength": 1 } } }, { "title": "WithFingerprint", "description": "Use this variant when NOT using Ratepay's device fingerprinting feature. Provide a fingerprint generated by your own system.", "required": [ "finger_print" ], "properties": { "finger_print": { "type": "string", "description": "A unique fingerprint to identify the buyer's device. This fingerprint is generated by the partner. Provide this if you do not integrate [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/).", "example": "bc47575c-7f93-4bae-84dc-282edf6a5d85", "maxLength": 255, "minLength": 1 } } } ] }, "DeviceLookupResponseDto": { "type": "object", "description": "The device used to initiate the transaction.", "properties": { "token": { "type": "string", "description": "ID generated using [Ratepay's device fingerprinting feature](/docs/developer/device_fingerprinting/device_fingerprinting/). Include the generated token if you are using the device fingerprinting feature in your integration. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "ade028c1-d2a2-4189-9214-e21089cd47f1", "maxLength": 255, "minLength": 1 } } }, "GeoLocationDto": { "type": "object", "description": "The geographical position of the buyer's device.", "properties": { "latitude": { "type": "number", "description": "The latitude of the geographical position of the buyer's device.", "example": 52.518368 }, "longitude": { "type": "number", "description": "The longitude of the geographical position of the buyer's device.", "example": 13.325109 } } }, "InStoreCollectDto": { "type": "object", "description": "The information of the in-store collect.", "example": null, "properties": { "city": { "type": "string", "description": "The city of the address. Must be at least 2 non whitespace characters.", "example": "Berlin", "maxLength": 100, "minLength": 2 }, "country_code": { "type": "string", "description": "The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "example": "DE", "pattern": "[A-Z]{2}" }, "location_name": { "type": "string", "description": "The name of the collection location.", "example": "Apotheke am Rathaus", "maxLength": 127, "minLength": 1 }, "street": { "type": "string", "description": "The name of the street.", "example": "Hauptstraße", "maxLength": 100, "minLength": 1 }, "street_addition": { "type": "string", "description": "Additional information about the address.", "maxLength": 50, "minLength": 1 }, "street_number": { "type": "string", "description": "The number describing where the building is located in the street.", "example": "22", "maxLength": 30, "minLength": 1 }, "zip_code": { "type": "string", "description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).", "example": "10439", "maxLength": 10, "minLength": 1 } }, "required": [ "city", "country_code", "street", "zip_code" ] }, "IncrementalAuthorizationCreateRejectedDeclineDto": { "type": "object", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "UNPROCESSABLE_OPERATION" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ], "example": "[\"SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT\"]" } } }, "required": [ "category" ] }, "IncrementalAuthorizationCreateRejectedErrorResponseDto": { "type": "object", "properties": { "decline": { "$ref": "#/components/schemas/IncrementalAuthorizationCreateRejectedDeclineDto" } }, "required": [ "decline" ] }, "IncrementalAuthorizationFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of authorization.", "properties": { "_links": { "$ref": "#/components/schemas/IncrementalAuthorizationLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "gross_amount": { "type": "number", "description": "Amount to increase given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of items to add.", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "authorization-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "ratepay_authorization_id": { "type": "string", "description": "ID of confirmed authorization (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "9wdn0Fvkb9Zxsfiql5l6", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "special_items": { "type": "array", "description": "List of special items to add, e.g. shipping costs or discounts.", "items": { "$ref": "#/components/schemas/SpecialItemDto" } }, "vats": { "type": "array", "description": "List of value-added tax (VAT) amounts.", "items": { "$ref": "#/components/schemas/VatDto" } } }, "required": [ "_links", "created", "gross_amount", "ratepay_authorization_id" ] }, "IncrementalAuthorizationLinks": { "type": "object", "description": "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "properties": { "self": { "$ref": "#/components/schemas/IncrementalAuthorizationSelfLink" } }, "required": [ "self" ] }, "IncrementalAuthorizationMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay during authorization creation.", "properties": { "_links": { "$ref": "#/components/schemas/IncrementalAuthorizationLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "ratepay_authorization_id": { "type": "string", "description": "ID of confirmed authorization generated by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "9wdn0Fvkb9Zxsfiql5l6", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "created", "ratepay_authorization_id" ] }, "IncrementalAuthorizationRequestDto": { "type": "object", "properties": { "gross_amount": { "type": "number", "description": "Amount to increase given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of items to add.", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "authorization-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "special_items": { "type": "array", "description": "List of special items to add, e.g. shipping costs or discounts.", "items": { "$ref": "#/components/schemas/SpecialItemDto" } }, "vats": { "type": "array", "description": "List of value-added tax (VAT) amounts.", "items": { "$ref": "#/components/schemas/VatDto" } } }, "required": [ "gross_amount" ] }, "IncrementalAuthorizationSelfLink": { "type": "object", "description": "The self relation identifying the authorization resource itself.", "properties": { "href": { "type": "string", "description": "URI pointing to resource itself.", "example": "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/authorizations/9wdn0Fvkb9Zxsfiql5l6" } }, "required": [ "href" ] }, "InvalidField": { "type": "object", "description": "List of one or multiple entries describing each failed validation. Only present if reason is `INVALID_FIELDS`.", "properties": { "json_path": { "type": "string", "description": "The JSON path pointing to the location where the validation failed.", "example": "partner_operation_id" }, "message": { "type": "string", "description": "A message describing which constraint was violated.", "example": "size must be between 0 and 255" } }, "required": [ "json_path", "message" ] }, "ItemDto": { "type": "object", "description": "List of items to add.", "properties": { "article_number": { "type": "string", "description": "The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.", "example": "kitchen-utils-1", "maxLength": 255, "minLength": 1, "pattern": ".*[\\S].*" }, "category": { "type": "string", "description": "Category for the item.", "example": "household", "maxLength": 511, "minLength": 0 }, "description": { "type": "string", "description": "Description of the item.", "example": "fruit knife with curved blade, 8 cm", "maxLength": 511, "minLength": 0 }, "gross_total_price": { "type": "number", "description": "Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity", "example": 33.8, "multipleOf": 0.01 }, "gross_unit_discount": { "type": "number", "description": "Gross discount on one item after taxes. Needs to be a negative value.", "example": -1.55, "exclusiveMaximum": false, "maximum": 0, "multipleOf": 0.01 }, "gross_unit_price": { "type": "number", "description": "Gross value of one item before taxes. For the RETURN_FEE type, applicable only to the REFUND operation, the value must be negative.", "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, "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, "multipleOf": 1e-10 }, "tax_rate": { "type": "number", "description": "Tax rate applicable for the item given in percent.", "example": 19, "exclusiveMaximum": true, "exclusiveMinimum": false, "maximum": 1000, "minimum": 0, "multipleOf": 0.01 }, "unit": { "type": "string", "description": "Arbitrary measurement unit of the item, e.g. kg, litre, pieces.", "example": "piece", "maxLength": 255, "minLength": 0 } }, "required": [ "gross_unit_price", "name", "quantity", "tax_rate" ] }, "LegalDeclineDto": { "type": "object", "description": "Information about why transaction was not accepted and declined.", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "LEGAL" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "ANONYMIZED_BY_BUYER" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ], "example": "[\"ANONYMIZED_BY_BUYER\"]" } } }, "required": [ "category", "reasons" ] }, "LegalErrorResponseDto": { "type": "object", "properties": { "decline": { "$ref": "#/components/schemas/LegalDeclineDto" } }, "required": [ "decline" ] }, "LookupAllCancellationsFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of all cancellations.", "properties": { "_embedded": { "type": "object", "properties": { "cancellations": { "type": "array", "description": "Embedded list of cancellations.", "items": { "$ref": "#/components/schemas/CancellationFullResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupAllCancellationsMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay.", "properties": { "_embedded": { "type": "object", "properties": { "cancellations": { "type": "array", "description": "Embedded list of cancellations.", "items": { "$ref": "#/components/schemas/CancellationMinimalResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupAllCapturesFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of all captures.", "properties": { "_embedded": { "type": "object", "properties": { "captures": { "type": "array", "description": "Embedded list of captures.", "items": { "$ref": "#/components/schemas/CaptureFullResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupAllCapturesMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay.", "properties": { "_embedded": { "type": "object", "properties": { "captures": { "type": "array", "description": "Embedded list of captures.", "items": { "$ref": "#/components/schemas/CaptureMinimalResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupAllIncrementalAuthsFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of all incremental auths.", "properties": { "_embedded": { "type": "object", "properties": { "authorizations": { "type": "array", "description": "Embedded list of incremental auths.", "items": { "$ref": "#/components/schemas/IncrementalAuthorizationFullResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupAllIncrementalAuthsMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay.", "properties": { "_embedded": { "type": "object", "properties": { "authorizations": { "type": "array", "description": "Embedded list of incremental auths.", "items": { "$ref": "#/components/schemas/IncrementalAuthorizationMinimalResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupAllRefundsFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of all refunds.", "properties": { "_embedded": { "type": "object", "properties": { "refunds": { "type": "array", "description": "Embedded list of refunds.", "items": { "$ref": "#/components/schemas/RefundFullResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupAllRefundsMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay.", "properties": { "_embedded": { "type": "object", "properties": { "refunds": { "type": "array", "description": "Embedded list of refunds.", "items": { "$ref": "#/components/schemas/RefundMinimalResponseDto" } } } }, "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "ratepay_transaction_id" ] }, "LookupTransactionFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of transaction plus links to related resources. Note that in case of a declined transaction, all attributes are optional as they may have not been present in the original request due to syntax error.", "properties": { "_links": { "$ref": "#/components/schemas/LookupTransactionLinks" }, "authorization_expires": { "type": "string", "format": "date-time", "description": "The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2025-04-02T16:15:18.823+02:00" }, "buyer": { "$ref": "#/components/schemas/BuyerDto" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "currency": { "type": "string", "description": "The currency of all amounts pertaining to the transaction. Upper-case alphabetic code in accordance with [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).", "example": "EUR", "pattern": "[A-Z]{3}" }, "decline": { "$ref": "#/components/schemas/DeclineDto" }, "delivery": { "$ref": "#/components/schemas/DeliveryDto" }, "device": { "$ref": "#/components/schemas/DeviceLookupResponseDto" }, "options": { "$ref": "#/components/schemas/OptionsDto" }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "partner-operation-id-1234", "maxLength": 255 }, "partner_transaction_id": { "type": "string", "description": "The transaction ID generated by the partner. This field must be included in at least one of the following requests: authorization or capture. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "partner-transaction-id-1234", "maxLength": 50, "minLength": 1 }, "payment_details": { "$ref": "#/components/schemas/PaymentDetailsFullResponseDto" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethodDto" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "shop_baskets": { "type": "array", "description": "One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.", "items": { "$ref": "#/components/schemas/ShopBasketDto" } }, "shops": { "type": "array", "description": "Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop.", "items": { "$ref": "#/components/schemas/ShopLookupResponseDto" } } }, "required": [ "_links", "created", "ratepay_transaction_id" ] }, "LookupTransactionLinks": { "type": "object", "description": "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "properties": { "authorizations": { "type": "array", "description": "List of additional authorization resources belonging to this transaction.", "items": { "$ref": "#/components/schemas/IncrementalAuthorizationSelfLink" } }, "cancellations": { "type": "array", "description": "List of cancellation resources belonging to this transaction.", "items": { "$ref": "#/components/schemas/CancellationSelfLink" } }, "captures": { "type": "array", "description": "List of capture resources belonging to this transaction.", "items": { "$ref": "#/components/schemas/CaptureSelfLink" } }, "refunds": { "type": "array", "description": "List of refund resources belonging to this transaction.", "items": { "$ref": "#/components/schemas/RefundSelfLink" } }, "self": { "$ref": "#/components/schemas/TransactionSelfLink" } }, "required": [ "authorizations", "cancellations", "captures", "refunds", "self" ] }, "LookupTransactionMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes plus links to related resources.", "properties": { "_links": { "$ref": "#/components/schemas/LookupTransactionLinks" }, "authorization_expires": { "type": "string", "format": "date-time", "description": "The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "example": "2025-04-02T16:15:18.823+02:00" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "decline": { "$ref": "#/components/schemas/DeclineDto" }, "payment_details": { "$ref": "#/components/schemas/PaymentDetailsMinimalResponseDto" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "result": { "$ref": "#/components/schemas/TransactionStatus" } }, "required": [ "_links", "created", "ratepay_transaction_id", "result" ] }, "MerchantDto": { "type": "object", "description": "This section contains optional details about a merchant managing a shop. A single merchant may operate one or more shops. By connecting shops to a specific merchant, it becomes possible to configure a merchant-level set of settings in the Ratepay systems. These settings will then be applied to all the associated shops.", "properties": { "merchant_id": { "type": "string", "description": "This is the unique identifier for the merchant. Before using the merchant_id in the API payload request, it must be requested from Ratepay. Please refer to the [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details.", "example": "ratepay-merchant-id-123", "maxLength": 255, "minLength": 1 }, "merchant_name": { "type": "string", "description": "This refers to the name of the merchant. It may vary from both the shop name and the legal name of the shop, both of which are also present in the current shops object.", "example": "Merchant XYZ", "maxLength": 255, "minLength": 1 } } }, "OptionsDto": { "type": "object", "description": "The options controlling transaction processing.", "properties": { "sales_channel": { "type": "string", "description": "The sales channel the transaction originates from.", "enum": [ "WEBSHOP", "POINT_OF_SALE", "PHONE_OR_MAIL" ], "example": "POINT_OF_SALE" } } }, "PaymentDetailsFullResponseDto": { "type": "object", "description": "Provides details about the payment to be either executed by the buyer or Ratepay depending on selected payment method.", "properties": { "debit_bank_account": { "$ref": "#/components/schemas/BankDetailsRequestDto" }, "deposit_bank_account": { "$ref": "#/components/schemas/BankDetailsResponseDto" }, "ratepay_payment_references": { "type": "array", "description": "List of payment references and the shop they belong to.", "items": { "$ref": "#/components/schemas/PaymentReferenceDto" } } } }, "PaymentDetailsMinimalResponseDto": { "type": "object", "description": "Provides details about the payment to be either executed by the buyer or Ratepay depending on selected payment method.", "properties": { "deposit_bank_account": { "$ref": "#/components/schemas/BankDetailsResponseDto" }, "ratepay_payment_references": { "type": "array", "description": "List of payment references and the shop they belong to.", "items": { "$ref": "#/components/schemas/PaymentReferenceDto" } } } }, "PaymentDetailsMinimalResponseLegacyDto": { "type": "object", "description": "Provides details about the payment to be executed by the buyer (generated by Ratepay).", "properties": { "deposit_bank_account": { "$ref": "#/components/schemas/BankDetailsResponseDto" }, "ratepay_payment_reference": { "type": "string", "deprecated": true, "description": "Purpose to be indicated in the bank transfer (generated by Ratepay). This is deprecated in favor of ratepay_payment_references. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "ET1285368M8", "maxLength": 127, "minLength": 1, "pattern": "[A-Za-z0-9 /-+]{1,127}" }, "ratepay_payment_references": { "type": "array", "description": "List of payment references and the shop they belong to.", "items": { "$ref": "#/components/schemas/PaymentReferenceDto" } } } }, "PaymentDetailsRequestDto": { "type": "object", "description": "Provides details about the payment to be executed by Ratepay. Applicable only in case of transfer-type SEPA_DIRECT_DEBIT.", "example": null, "properties": { "debit_bank_account": { "$ref": "#/components/schemas/BankDetailsRequestDto" } }, "required": [ "debit_bank_account" ] }, "PaymentMethodDto": { "type": "object", "description": "The payment method selected by the buyer.", "properties": { "payment_option": { "type": "string", "description": "The payment option the buyer selected.", "enum": [ "OPEN_INVOICE", "PAY_NOW" ], "example": "OPEN_INVOICE" }, "transfer_type": { "type": "string", "description": "The transfer type the buyer selected.", "enum": [ "BANK_TRANSFER", "SEPA_DIRECT_DEBIT" ], "example": "BANK_TRANSFER" } }, "required": [ "payment_option", "transfer_type" ] }, "PaymentReferenceDto": { "type": "object", "description": "List of payment references and the shop they belong to.", "properties": { "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "ratepay_payment_reference": { "type": "string", "description": "Purpose to be indicated in the bank transfer (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "ET1285368M8", "maxLength": 127, "minLength": 1, "pattern": "[A-Za-z0-9 /-+]{1,127}" } }, "required": [ "partner_shop_id", "ratepay_payment_reference" ] }, "PersonDto": { "type": "object", "description": "The person that wants to place the transaction. This implies a B2C transaction. Either provide a person or company but not both.", "properties": { "date_of_birth": { "type": "string", "format": "date", "description": "The date of birth of the person. Must be in format `YYYY-MM-DD` conforming to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).", "example": "1971-05-19" }, "first_name": { "type": "string", "description": "The first name of the person.", "example": "Heinz", "maxLength": 100, "minLength": 1 }, "last_name": { "type": "string", "description": "The last name of the person.", "example": "Steeger", "maxLength": 100, "minLength": 1 }, "title": { "type": "string", "description": "The title of the person.", "example": "Dr.", "maxLength": 45, "minLength": 1 } }, "required": [ "date_of_birth", "first_name", "last_name" ] }, "PickUpBoxDto": { "type": "object", "description": "The information of the pick up box.", "example": null, "properties": { "carrier_name": { "type": "string", "description": "The name of the parcel carrier.", "example": "DHL", "maxLength": 127, "minLength": 1 }, "city": { "type": "string", "description": "The city of the address. Must be at least 2 non whitespace characters.", "example": "Berlin", "maxLength": 100, "minLength": 2 }, "country_code": { "type": "string", "description": "The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "example": "DE", "pattern": "[A-Z]{2}" }, "location_id": { "type": "string", "description": "The ID of pick up location with the carrier.", "example": "Packstation 985", "maxLength": 127, "minLength": 1 }, "recipient_account_id": { "type": "string", "description": "The ID of the receiver with the carrier. It is optional only for country_code AT, otherwise it is required.", "example": "445522299", "maxLength": 127, "minLength": 1 }, "zip_code": { "type": "string", "description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).", "example": "10439", "maxLength": 10, "minLength": 1 } }, "required": [ "city", "country_code", "location_id", "zip_code" ] }, "PickUpShopDto": { "type": "object", "description": "The information of the pick up shop.", "example": null, "properties": { "city": { "type": "string", "description": "The city of the address. Must be at least 2 non whitespace characters.", "example": "Berlin", "maxLength": 100, "minLength": 2 }, "country_code": { "type": "string", "description": "The country of the address. Must conform with [ISO 3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "example": "DE", "pattern": "[A-Z]{2}" }, "location_name": { "type": "string", "description": "The name of the pick up shop.", "example": "Kiosk am Stadtpark", "maxLength": 127, "minLength": 1 }, "street": { "type": "string", "description": "The name of the street.", "example": "Fichtenweg", "maxLength": 100, "minLength": 1 }, "street_addition": { "type": "string", "description": "Additional information about the address.", "maxLength": 50, "minLength": 1 }, "street_number": { "type": "string", "description": "The number describing where the building is located in the street.", "example": "2b", "maxLength": 30, "minLength": 1 }, "zip_code": { "type": "string", "description": "The zip or post code of the address. Must be valid according to zip format of given country code. See [list of postal codes](https://en.wikipedia.org/wiki/List_of_postal_codes).", "example": "10439", "maxLength": 10, "minLength": 1 } }, "required": [ "city", "country_code", "street", "zip_code" ] }, "RefundCreateRejectedDeclineDto": { "type": "object", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "UNPROCESSABLE_OPERATION" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "REFUND_AMOUNT_TOO_HIGH" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ], "example": "[\"REFUND_AMOUNT_TOO_HIGH\"]" } } }, "required": [ "category" ] }, "RefundCreateRejectedErrorResponseDto": { "type": "object", "properties": { "decline": { "$ref": "#/components/schemas/RefundCreateRejectedDeclineDto" } }, "required": [ "decline" ] }, "RefundFullResponseDto": { "type": "object", "description": "This response is returned if representation header is specified. Response includes all attributes of refund.", "properties": { "_links": { "$ref": "#/components/schemas/RefundLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "gross_amount": { "type": "number", "description": "Amount to refund given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of refunded items.", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "refund-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "ratepay_refund_id": { "type": "string", "description": "ID of confirmed refund (generated by Ratepay). Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "9FkZsddr-MaFFFx7gAs_", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "special_items": { "type": "array", "description": "List of refunded special items, e.g. shipping costs or discounts.", "items": { "$ref": "#/components/schemas/SpecialItemDto" } }, "vats": { "type": "array", "description": "List of value-added tax (VAT) amounts.", "items": { "$ref": "#/components/schemas/VatDto" } } }, "required": [ "_links", "created", "gross_amount", "ratepay_refund_id" ] }, "RefundLinks": { "type": "object", "description": "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "properties": { "self": { "$ref": "#/components/schemas/RefundSelfLink" } }, "required": [ "self" ] }, "RefundMinimalResponseDto": { "type": "object", "description": "Includes only minimal set of attributes generated by Ratepay during refund creation.", "properties": { "_links": { "$ref": "#/components/schemas/RefundLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "ratepay_refund_id": { "type": "string", "description": "ID of confirmed refund generated by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "9FkZsddr-MaFFFx7gAs_", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "created", "ratepay_refund_id" ] }, "RefundRequestDto": { "type": "object", "properties": { "gross_amount": { "type": "number", "description": "Amount to refund given in currency of original transaction.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of refunded items.", "items": { "$ref": "#/components/schemas/ItemDto" } }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "refund-id-1234", "maxLength": 255, "minLength": 0 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "special_items": { "type": "array", "description": "List of refunded special items, e.g. shipping costs or discounts.", "items": { "$ref": "#/components/schemas/SpecialItemDto" } }, "vats": { "type": "array", "description": "List of value-added tax (VAT) amounts.", "items": { "$ref": "#/components/schemas/VatDto" } } }, "required": [ "gross_amount" ] }, "RefundSelfLink": { "type": "object", "description": "The self relation identifying the refund resource itself.", "properties": { "href": { "type": "string", "description": "URI pointing to resource itself.", "example": "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/refunds/9FkZsddr-MaFFFx7gAs_" } }, "required": [ "href" ] }, "ResourceNotFoundDeclineDto": { "type": "object", "description": "Information about why transaction was not accepted and declined.", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "RESOURCE_NOT_FOUND" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "TRANSACTION_NOT_FOUND" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ], "example": "[\"TRANSACTION_NOT_FOUND\"]" } } }, "required": [ "category", "reasons" ] }, "ResourceNotFoundErrorResponseDto": { "type": "object", "properties": { "decline": { "$ref": "#/components/schemas/ResourceNotFoundDeclineDto" } }, "required": [ "decline" ] }, "RiskDto": { "type": "object", "description": "The risk associated with the buyer's device. Can be empty.", "properties": { "reasons": { "type": "array", "description": "List of reasons for the estimated risk.", "example": [ "HIGH_RISK_DEVICE_BEHAVIOR" ], "items": { "type": "string", "description": "List of reasons for the estimated risk.", "enum": [ "LOW_RISK_DEVICE", "LIMITED_TRUST", "HIGH_RISK_DEVICE_REPUTATION", "HIGH_RISK_DEVICE_BEHAVIOR", "HIGH_RISK_IP_REPUTATION", "HIGH_RISK_IP_BEHAVIOR" ], "example": "[\"HIGH_RISK_DEVICE_BEHAVIOR\"]", "maxLength": 255, "minLength": 1 } }, "score": { "type": "integer", "description": "A numerical value for the estimated risk.", "example": 123, "maximum": 1000, "minimum": 1 } } }, "ScreenDto": { "type": "object", "description": "The dimensions of the buyer's screen.", "properties": { "height": { "type": "integer", "description": "The height of the buyer's screen in pixel.", "example": 1080, "maximum": 2147483647, "minimum": 0 }, "width": { "type": "integer", "description": "The width of the buyer's screen in pixel.", "example": 1920, "maximum": 2147483647, "minimum": 0 } } }, "ShippingInformationLinks": { "type": "object", "description": "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "properties": { "self": { "$ref": "#/components/schemas/ShippingInformationSelfLink" } }, "required": [ "self" ] }, "ShippingInformationMinimalResponseDto": { "type": "object", "properties": { "_links": { "$ref": "#/components/schemas/ShippingInformationLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "ratepay_shipping_information_id": { "type": "string", "description": "ID of added shipping information generated by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "HR1iyZYradbGbvOQzZ79", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" } }, "required": [ "_links", "created", "ratepay_shipping_information_id" ] }, "ShippingInformationRequestDto": { "type": "object", "properties": { "carrier_name": { "type": "string", "description": "Name of carrier responsible for shipment.", "enum": [ "DHL", "POST_AUSTRIA", "UPS", "DPD", "SWISS_POST", "GLS", "ASENDIA", "HERMES_LOGISTICS", "FEDEX", "OTHER_WITH_TRACKING", "OTHER_WITHOUT_TRACKING" ], "example": "DHL" }, "tracking_number": { "type": "string", "description": "Tracking number for delivery. This field is mandatory for each carrier_name except: `OTHER_WITHOUT_TRACKING`", "example": "tracking-123456789", "maxLength": 127, "minLength": 1 } }, "required": [ "carrier_name" ] }, "ShippingInformationSelfLink": { "type": "object", "description": "The self relation identifying the shipping information resource itself.", "properties": { "href": { "type": "string", "description": "URI pointing to resource itself.", "example": "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN/shipping-information/HR1iyZYradbGbvOQzZ79" } }, "required": [ "href" ] }, "ShopBasketDto": { "type": "object", "description": "One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.", "properties": { "gross_amount": { "type": "number", "description": "The amount for the basket including VAT given in the currency of the transaction. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.", "example": 67.6, "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "items": { "type": "array", "description": "List of items contained in the transaction.", "items": { "$ref": "#/components/schemas/ItemDto" }, "maxItems": 2147483647, "minItems": 1 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 }, "shop_merchant_id": { "type": "string", "description": "This is the unique identifier for the merchant. Before using the merchant_id in the shop_baskets object, it must be requested from Ratepay and connected with a respective partner_shop_id in the Ratepay systems. Please refer to the [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in the payment API 2.0 for more details.", "example": "ratepay-merchant-id-123", "maxLength": 255, "minLength": 1 }, "shop_transaction_id": { "type": "string", "description": "The transaction ID generated by the shop. **This field must be included in at least one of the following requests: authorization or capture.** This ID must be known to the buyer and is used for buyer communication, e.g. correspondences and buyer support.\n", "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", "vats", "shop_transaction_id" ] }, "ShopDto": { "type": "object", "description": "Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop.", "properties": { "correspondence_settings": { "$ref": "#/components/schemas/CorrespondenceSettingsDto" }, "legal": { "$ref": "#/components/schemas/ShopLegalDto" }, "merchant": { "$ref": "#/components/schemas/MerchantDto" }, "merchant_category_code": { "type": "string", "description": "The branch of industry of the shop. Must conform to [ISO 18245](https://www.iso.org/standard/79450.html).", "example": "5499", "pattern": "[0-9]{4}" }, "name": { "type": "string", "description": "The name of the shop. May differ from legal name.", "example": "fruits and more", "maxLength": 255, "minLength": 2 }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 } }, "required": [ "legal", "merchant_category_code", "name", "partner_shop_id" ] }, "ShopLegalDto": { "type": "object", "description": "Legal information about the shop.", "properties": { "commercial_register_number": { "type": "string", "description": "The registration number the shop is filed under.", "example": "HRB 12345FF", "maxLength": 12, "minLength": 2 }, "legal_form": { "type": "string", "description": "The legal form as which the shop is registered, e.g. Ltd., GmbH, GbR, etc.", "example": "GmbH", "maxLength": 255, "minLength": 2 }, "name": { "type": "string", "description": "The name of the shop as which it is registered.", "example": "Fruits and more GmbH", "maxLength": 255, "minLength": 2 } }, "required": [ "name" ] }, "ShopLookupResponseDto": { "type": "object", "description": "Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop.", "properties": { "merchant_category_code": { "type": "string", "description": "The branch of industry of the shop. Must conform to [ISO 18245](https://www.iso.org/standard/79450.html).", "example": "5499", "pattern": "[0-9]{4}" }, "partner_shop_id": { "type": "string", "description": "The shop ID generated by the partner or provided upfront by Ratepay. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "partner-shop-id-1", "maxLength": 255, "minLength": 1 } }, "required": [ "merchant_category_code", "partner_shop_id" ] }, "SlangDto": { "type": "object", "properties": { "customer_service_contact": { "type": "array", "description": "List of 1 to 5 lines with correspondence information. Include how to reach customer support.", "example": [ "You can reach our customer service Mon - Sun 7 am to 8 pm", "by mail: customer-service@example.com", "by phone: 030 / 123 456 789", "contact form: example.com/contact" ], "items": { "type": "string", "description": "List of 1 to 5 lines with correspondence information. Include how to reach customer support.", "example": "[\"You can reach our customer service Mon - Sun 7 am to 8 pm\",\"by mail: customer-service@example.com\",\"by phone: 030 / 123 456 789\",\"contact form: example.com/contact\"]" }, "maxItems": 5, "minItems": 1 }, "formal_tone": { "type": "string", "description": "Formality level for the buyer correspondences.", "enum": [ "FORMAL", "INFORMAL" ], "example": "INFORMAL" }, "name_format": { "type": "string", "description": "Specifies how to visualize the buyer's name after the salutation in the buyer correspondences.", "enum": [ "EMPTY", "FIRST_NAME", "LAST_NAME", "FIRST_LAST_NAME" ], "example": "FIRST_LAST_NAME" }, "salutation": { "type": "string", "description": "Word for salutation in the buyer correspondences in this language, e.g. Hi, Hello, Hallo, Guten Tag, etc.", "example": "Hello", "maxLength": 2147483647, "minLength": 1 }, "transaction_type": { "type": "string", "description": "Specifies how to call the transaction in buyer correspondences.", "enum": [ "ORDER", "BOOKING" ], "example": "ORDER" } } }, "SlangsDto": { "type": "object", "description": "Language settings for buyer correspondences.", "properties": { "de": { "$ref": "#/components/schemas/SlangDto" }, "en": { "$ref": "#/components/schemas/SlangDto" }, "fr": { "$ref": "#/components/schemas/SlangDto" }, "nl": { "$ref": "#/components/schemas/SlangDto" } } }, "SpecialItemDto": { "type": "object", "description": "List of special items to add, e.g. shipping costs or discounts.", "properties": { "article_number": { "type": "string", "description": "The article number of the item, e.g. SKU. Not allowed to contain only whitespaces.", "example": "kitchen-utils-1", "maxLength": 255, "minLength": 1, "pattern": ".*[\\S].*" }, "category": { "type": "string", "description": "Category for the item.", "example": "household", "maxLength": 511, "minLength": 0 }, "description": { "type": "string", "description": "Description of the item.", "example": "fruit knife with curved blade, 8 cm", "maxLength": 511, "minLength": 0 }, "gross_total_price": { "type": "number", "description": "Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity", "example": 33.8, "multipleOf": 0.01 }, "gross_unit_discount": { "type": "number", "description": "Gross discount on one item after taxes. Needs to be a negative value.", "example": -1.55, "exclusiveMaximum": false, "maximum": 0, "multipleOf": 0.01 }, "gross_unit_price": { "type": "number", "description": "Gross value of one item before taxes. For the RETURN_FEE type, applicable only to the REFUND operation, the value must be negative.", "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, "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, "multipleOf": 1e-10 }, "tax_rate": { "type": "number", "description": "Tax rate applicable for the item given in percent.", "example": 19, "exclusiveMaximum": true, "exclusiveMinimum": false, "maximum": 1000, "minimum": 0, "multipleOf": 0.01 }, "type": { "type": "string", "description": "The special item type the buyer selected. RETURN_FEE type is applicable only for the REFUND operation. Click [here](/docs/developer/api_integration/payment_2.0/example_requests/for_merchants/#With-items-and-buyer-return-fee) for example about usage for merchants or [here](/docs/developer/api_integration/payment_2.0/example_requests/for_marketplaces/#With-items-and-buyer-return-fee) for marketplaces.", "enum": [ "RETURN_FEE" ], "example": "RETURN_FEE" }, "unit": { "type": "string", "description": "Arbitrary measurement unit of the item, e.g. kg, litre, pieces.", "example": "piece", "maxLength": 255, "minLength": 0 } }, "required": [ "gross_unit_price", "name", "quantity", "tax_rate" ] }, "TransactionBadRequestErrorDto": { "type": "object", "properties": { "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "decline": { "$ref": "#/components/schemas/BadRequestDeclineDto" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "result": { "type": "string", "description": "Indicates the outcome of the transaction request. Possible value : DECLINED – The transaction has been rejected; the merchant must not proceed with order fulfillment.", "example": "DECLINED" } }, "required": [ "_links", "created", "decline", "ratepay_transaction_id", "result" ] }, "TransactionCreateRejectedDeclineDto": { "type": "object", "description": "Information about why transaction was not accepted and declined.", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "CONTRACT" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "CURRENCY_NOT_ALLOWED" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED", "OTP_VERIFICATION_REQUIRED_BUT_FEATURE_NOT_ENABLED", "ORDER_WITH_PHONE_INTELLIGENCE_FRAUD_SUSPICION_BLOCKLISTED", "OTP_FAILED", "OTP_EXPIRED" ], "example": "[\"CURRENCY_NOT_ALLOWED\"]" } } }, "required": [ "category" ] }, "TransactionCreateRejectedErrorResponseDto": { "type": "object", "properties": { "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "decline": { "$ref": "#/components/schemas/TransactionCreateRejectedDeclineDto" }, "ratepay_transaction_id": { "type": "string", "description": "ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "scwBgARW-nE93I7_ywhp", "maxLength": 127, "minLength": 20, "pattern": "[A-Za-z0-9-_]{20,127}" }, "result": { "type": "string", "description": "Indicates the outcome of the transaction request. Possible value : DECLINED – The transaction has been rejected; the merchant must not proceed with order fulfillment.", "example": "DECLINED" } }, "required": [ "_links", "created", "decline", "ratepay_transaction_id", "result" ] }, "TransactionLinks": { "type": "object", "description": "Links related to the resource following specification by [IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "properties": { "self": { "$ref": "#/components/schemas/TransactionSelfLink" } }, "required": [ "self" ] }, "TransactionMinimalResponseDto": { "type": "object", "properties": { "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "authorization_expires": { "type": "string", "format": "date-time", "description": "The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "payment_details": { "$ref": "#/components/schemas/PaymentDetailsMinimalResponseLegacyDto" }, "result": { "$ref": "#/components/schemas/TransactionStatus" }, "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", "result" ] }, "AuthorizationTransactionMinimalResponseDto": { "type": "object", "properties": { "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "authorization_expires": { "type": "string", "format": "date-time", "description": "The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "payment_details": { "$ref": "#/components/schemas/PaymentDetailsMinimalResponseLegacyDto" }, "result": { "type": "string", "description": "Indicates the outcome of the transaction request. Possible value : ACCEPTED – The transaction has been successfully authorized and can proceed to capture.", "example": "ACCEPTED" }, "ratepay_transaction_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", "result" ] }, "TransactionMinimalResponseDtoOtpRequired": { "type": "object", "properties": { "_links": { "$ref": "#/components/schemas/TransactionLinks" }, "authorization_expires": { "type": "string", "format": "date-time", "description": "The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "created": { "type": "string", "format": "date-time", "description": "Timestamp with offset according to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "payment_details": { "$ref": "#/components/schemas/PaymentDetailsMinimalResponseLegacyDto" }, "result": { "type": "string", "description": "Indicates the outcome of the transaction request. Possible value : OTP_REQUIRED – The buyer must complete OTP verification before the transaction can be finalized.", "example": "OTP_REQUIRED" }, "otp_details": { "$ref": "#/components/schemas/OtpDetailsDto" }, "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", "result" ] }, "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": "2025-04-02T16:15:18.823+02:00" }, "buyer": { "$ref": "#/components/schemas/BuyerDto" }, "currency": { "type": "string", "description": "The currency of all amounts pertaining to the transaction. Upper-case alphabetic code in accordance with [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).", "example": "EUR", "pattern": "[A-Z]{3}" }, "delivery": { "$ref": "#/components/schemas/DeliveryDto" }, "device": { "$ref": "#/components/schemas/DeviceDto" }, "options": { "$ref": "#/components/schemas/OptionsDto" }, "partner_operation_id": { "type": "string", "description": "Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.", "example": "partner-operation-id-1234", "maxLength": 255, "minLength": 0 }, "partner_transaction_id": { "type": "string", "description": "The transaction ID generated by the partner. **This field must be included in at least one of the following requests: authorization or capture.** This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API.\n", "example": "partner-transaction-id-1234", "maxLength": 50, "minLength": 1 }, "payment_details": { "$ref": "#/components/schemas/PaymentDetailsRequestDto" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethodDto" }, "shop_baskets": { "type": "array", "description": "One basket for each shop contained in the transaction. The definition of multiple shops is only relevant for marketplace integrations. If items and special items are included in the basket, gross amount must match the sum of all items. See [basket amount validation page](/docs/developer/api_integration/payment_2.0/basket_validation/) for additional details.", "items": { "$ref": "#/components/schemas/ShopBasketDto" } }, "shops": { "type": "array", "description": "Enables eligible partners, usually PSPs (payment service providers), to submit necessary information for registering a new shop when processing their first transaction authorization or updating information for an already registered shop.", "items": { "$ref": "#/components/schemas/ShopDto" } } }, "required": [ "buyer", "currency", "payment_method", "shop_baskets" ] }, "TransactionSelfLink": { "type": "object", "description": "The self relation identifying the transaction resource itself.", "properties": { "href": { "type": "string", "description": "URI pointing to resource itself.", "example": "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp" } }, "required": [ "href" ] }, "UnprocessableOperationNotAllowedForDeclinedTransaction": { "type": "object", "properties": { "category": { "type": "string", "description": "Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details.", "enum": [ "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" ], "example": "UNPROCESSABLE_OPERATION" }, "reasons": { "type": "array", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "example": [ "NOT_ALLOWED_FOR_DECLINED_TRANSACTION" ], "items": { "type": "string", "description": "List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category.", "enum": [ "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "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, "multipleOf": 0.01 }, "tax_amount": { "type": "number", "description": "The tax amount for the given tax rate.", "example": 10.79, "exclusiveMinimum": false, "minimum": 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, "multipleOf": 0.01 } }, "required": [ "net_amount", "tax_amount", "tax_rate" ] }, "TransactionStatus": { "type": "string", "description": "Indicates the outcome of the transaction request. Possible values: ACCEPTED – The transaction has been successfully authorized and can proceed to capture. DECLINED – The transaction has been rejected; the merchant must not proceed with order fulfillment. OTP_REQUIRED – The buyer must complete OTP verification before the transaction can be finalized.", "enum": [ "ACCEPTED", "DECLINED", "OTP_REQUIRED" ], "example": "ACCEPTED" }, "OtpDetailsDto": { "type": "object", "description": "Present only when result = OTP_REQUIRED. Contains OTP validity, regeneration timing, localized messages, and verification endpoints.", "properties": { "regeneration_possible_in_seconds": { "type": "number", "description": "Time (in seconds) after which the buyer can request a new OTP if needed.", "example": 60 }, "time_to_live_in_seconds": { "type": "number", "description": "Duration (in seconds) for which the OTP remains valid before expiry.", "example": 120 }, "message": { "$ref": "#/components/schemas/MessageDto" }, "links": { "$ref": "#/components/schemas/LinksDto" } } }, "MessageDto": { "type": "object", "properties": { "en": { "type": "string", "description": "Buyer-facing message confirming OTP send, intended for display in the checkout experience.", "example": "The code has been sent to your phone number ." }, "de": { "type": "string", "description": "Buyer-facing message confirming OTP send, intended for display in the checkout experience.", "example": "Der Code wurde an Ihre Telefonnummer gesendet." } } }, "LinksDto": { "type": "object", "properties": { "regenerate": { "type": "string", "description": "Endpoint to request generation of a new OTP code.", "example": "/2fa/v1/public/regenerate/TKIZDYV_FU21Q0MSHDNN" }, "verify": { "type": "string", "description": "Endpoint to verify the OTP code entered by the buyer.", "example": "/2fa/v1/public/verify/TKIZDYV_FU21Q0MSHDNN" } } } }, "securitySchemes": { "Bearer Authentication": { "bearerFormat": "JWT", "description": "For each request, a valid access token must be provided in the Authorization header. See [Authentication API](/docs/developer/authentication/authentication) for obtaining a valid token and [Request OAuth token](/apis/authentication/openapi/authentication_api/createoauthtoken/) for details on the audience to use.", "scheme": "bearer", "type": "http" } } } }