{
  "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/compliance/secci": {
      "post": {
        "description": "\n            Generate a Standard European Consumer Credit Information (SECCI) document for CCD2 compliance.\n\n            **Delivery Methods:**\n            - **PDF**: Returns the PDF document content. Use `action: download` for eCom flows or `action: print` for POS flows.\n            - **EMAIL**: Sends the SECCI document via email. \n\n            **Response:**\n            - For PDF delivery: Returns `application/pdf` binary content\n             - For EMAIL delivery: Returns a JSON payload containing the email trigger result and SECCI ID.\n\n             All responses include the compliance JWT in the `X-Attestation-Token` header. It must be passed with the subsequent Payment API transaction request in the [attestation_token](https://ratepay--ccd2.preview.redocly.app/apis/payment/openapi/payment_api/transaction-management/createtransaction#transaction-management/createtransaction/t=request&path=compliance_details/attestation_token) field.\n        ",
        "operationId": "generateSecci",
        "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
            }
          },
          {
            "in": "header",
            "name": "Prefer",
            "description": "According to RFC 7240: Provide `return=representation` if you prefer that the response to a request includes the current state of the resource.",
            "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"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SecciApiRequestDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecciEmailResponseDto"
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "PDF document (for pdf delivery method)"
                }
              }
            },
            "description": "SECCI document generated successfully",
            "headers": {
              "X-Attestation-Token": {
                "description": "RS256 JWT attestation token to be passed with the transaction request",
                "schema": {
                  "type": "string"
                },
                "style": "simple"
              }
            }
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorResponseDto"
                }
              }
            },
            "description": "Bad request"
          },
          "451": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/LegalErrorResponseDto"
                }
              }
            },
            "description": "Legally not allowed"
          }
        },
        "summary": "Generate SECCI document"
      }
    }
  },
  "components": {
    "schemas": {
      "BadRequestDeclineDto": {
        "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": "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"
        ]
      },
      "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"
        ]
      },
      "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"
        ]
      },
      "Problem": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "SecciApiDeliveryDto": {
        "type": "object",
        "description": "Delivery method configuration",
        "properties": {
          "action": {
            "type": "string",
            "description": "Action for PDF delivery (required when method is 'pdf')",
            "enum": [
              "download",
              "print"
            ],
            "example": "download",
            "pattern": "download|print"
          },
          "country_code": {
            "type": "string",
            "description": "Country code of the buyer's billing address. This is required to generate a legally   compliant SECCI document for the relevant European jurisdiction. Must be a 2-letter ISO 3166-1 alpha-2 country code.",
            "example": "DE",
            "pattern": "[A-Z]{2}"
          },
          "email": {
            "type": "string",
            "description": "Email address (required when method is 'email')",
            "example": "max.mustermann@example.com",
            "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])?"
          },
          "language": {
            "type": "string",
            "description": "Language used for generating the SECCI document",
            "example": "de",
            "pattern": "[a-z]{2}"
          },
          "method": {
            "type": "string",
            "description": "Delivery method",
            "enum": [
              "email",
              "pdf"
            ],
            "example": "pdf",
            "pattern": "email|pdf"
          }
        },
        "required": [
          "method"
        ]
      },
      "SecciApiItemDto": {
        "type": "object",
        "description": "Basket item",
        "properties": {
          "gross_unit_price": {
            "type": "number",
            "description": "Gross unit price",
            "example": 20.03,
            "multipleOf": 0.01
          },
          "name": {
            "type": "string",
            "description": "Item name",
            "example": "fruit knife"
          },
          "quantity": {
            "type": "number",
            "description": "Item quantity",
            "example": 2,
            "exclusiveMinimum": false,
            "minimum": 0
          },
          "tax_rate": {
            "type": "number",
            "description": "Tax rate",
            "example": 19,
            "exclusiveMaximum": true,
            "exclusiveMinimum": false,
            "maximum": 1000,
            "minimum": 0,
            "multipleOf": 0.01
          }
        },
        "required": [
          "gross_unit_price",
          "name",
          "quantity",
          "tax_rate"
        ]
      },
      "SecciApiPaymentMethodDto": {
        "type": "object",
        "description": "Payment method details",
        "properties": {
          "payment_option": {
            "type": "string",
            "description": "Payment option",
            "enum": [
              "OPEN_INVOICE"
            ],
            "example": "OPEN_INVOICE"
          },
          "transfer_type": {
            "type": "string",
            "description": "Transfer type",
            "example": "BANK_TRANSFER"
          }
        }
      },
      "SecciApiRequestDto": {
        "type": "object",
        "description": "Request to generate SECCI document",
        "properties": {
          "currency": {
            "type": "string",
            "description": "Currency code",
            "example": "EUR",
            "pattern": "[A-Z]{3}"
          },
          "delivery": {
            "$ref": "#/components/schemas/SecciApiDeliveryDto"
          },
          "payment_method": {
            "$ref": "#/components/schemas/SecciApiPaymentMethodDto"
          },
          "shop_baskets": {
            "type": "array",
            "description": "Shop basket",
            "items": {
              "$ref": "#/components/schemas/SecciApiShopBasketDto"
            }
          }
        },
        "required": [
          "currency",
          "delivery",
          "payment_method",
          "shop_baskets"
        ]
      },
      "SecciApiShopBasketDto": {
        "type": "object",
        "description": "Shop basket",
        "properties": {
          "gross_amount": {
            "type": "number",
            "description": "Gross amount",
            "example": 100,
            "exclusiveMinimum": true,
            "minimum": 0
          },
          "items": {
            "type": "array",
            "description": "Basket items (optional - if not provided, a single item will be generated from gross_amount)",
            "items": {
              "$ref": "#/components/schemas/SecciApiItemDto"
            }
          },
          "partner_shop_id": {
            "type": "string",
            "description": "Partner shop identifier"
          },
          "special_items": {
            "type": "array",
            "description": "Special items (discounts, shipping, etc.)",
            "items": {
              "$ref": "#/components/schemas/SecciApiSpecialItemDto"
            }
          }
        },
        "required": [
          "gross_amount",
          "partner_shop_id"
        ]
      },
      "SecciApiSpecialItemDto": {
        "type": "object",
        "description": "Special item (discounts, shipping, etc.)",
        "properties": {
          "gross_unit_price": {
            "type": "number",
            "description": "Gross unit price",
            "example": 20.03,
            "multipleOf": 0.01
          },
          "name": {
            "type": "string",
            "description": "Item name",
            "example": "shipping costs"
          },
          "quantity": {
            "type": "number",
            "description": "Item quantity",
            "example": 2,
            "exclusiveMinimum": false,
            "minimum": 0
          },
          "tax_rate": {
            "type": "number",
            "description": "Tax rate",
            "example": 19,
            "exclusiveMaximum": true,
            "exclusiveMinimum": false,
            "maximum": 1000,
            "minimum": 0,
            "multipleOf": 0.01
          }
        },
        "required": [
          "gross_unit_price",
          "name",
          "quantity",
          "tax_rate"
        ]
      },
      "SecciEmailResponseDto": {
        "type": "object",
        "description": "Response for email delivery of SECCI document",
        "properties": {
          "message": {
            "type": "string",
            "description": "Additional message (e.g., error details)"
          },
          "result": {
            "type": "string",
            "description": "Result of the email trigger",
            "enum": [
              "SUCCESS",
              "ERROR"
            ],
            "example": "SUCCESS"
          },
          "secci_id": {
            "type": "string",
            "description": "Unique SECCI document identifier",
            "example": "SCABC123-11072026"
          }
        },
        "required": [
          "result"
        ]
      }
    },
    "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"
      }
    }
  }
}