Integration Details

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

This page explains what to change in a direct Payment API 2.0 integration for CCD2. Only make these changes for in-scope transactions: consumer (B2C) purchases with an in-scope payment method. The rest of your integration stays the same.

The API sequence are the same for online shop, MOTO and point of sale. Only the buyers or staff interface and SECCI delivery differ. See sales channel notes below for details.

Before you start

• Confirm which of your payment method and transactions are in scope for CCD2

1. Present payment methods

In your checkout or staff interface:

• Do not pre-select an in-scope Ratepay payment method, or give it disproportionate emphasis than other payment methods.
• Show all available payment methods from the start, not only after a Ratepay decline.
• Let the buyer choose the payment method; staff must not choose a credit method without the buyer's instruction.

The broader advertising requirements, including relevant costs and risks outside checkout, are explained on Direct API: Your CCD2 responsibilities. Have your legal team approve the final buyer-facing wording.

Before you continue, check that:

• All available payment methods are visible from the start
• No in-scope method is pre-selected or emphasised
• The buyer makes the choice.

2. Inform the buyer about the SECCI

Before the payment is submitted, the buyer must be informed they will receive the Standard European Consumer Credit Information (SECCI) and the merchant must trigger the delivery of SECCI.

Online shop

Choose one variant:

Automatic email delivery (recommended)

Use this option when the buyer's email address is already captured and you want to reduce friction during checkout.

Screen	Stage	Implementation Notes
	Notice before payment-method selection	Show the SECCI notice above the payment methods. Name the in-scope methods and the buyer's email address, and keep the usual way to change the email.
	Confirmation after successful email request	• When the buyer selects an in-scope method, your backend sends an SECCI generation request with email as delivery.method (step 3). • After a successful response, show the confirmation and offer a PDF download option as well. Otherwise, give the buyer the option to retry or download SECCI as a PDF.

Suggested buyer-facing copy:

Note: Show the confirmation only after the email SECCI request succeeds.

Explicit SECCI Interaction

Use this when the buyer should choose the delivery method.

Screen	Stage	Implementation notes
	Notice after payment-method selection	• After the buyer selects an in-scope method, show the notice with two actions: Download PDF and Get by Email. • Ask for an email address only if the buyer chooses email and you don't have one.
	Confirmation shown after the PDF is downloaded or the email request completes successfully	Each action triggers the matching Secci generation request from your backend (step 3).

Suggested buyer-facing copy:

MOTO and point of sale

Before you continue, check that:

Online shop - Automatic email delivery:

• The SECCI notice appears above the payment method.

Online shop - Explicit SECCI delivery:

• The SECCI notice appears after an in-scope method is selected.

MOTO and point of sale:

• Staff sees the delivery actions before they can submit the order.

3. Generate and provide SECCI

Add the new SECCI generation endpoint POST /v2/compliance/secci to your backend. Ratepay generates the document from the supplied data.

• Backend only: the request contains your OAuth token, so send it from your backend, never from the browser.
• Matching data: the basket, payment method and amount must match the Authorize transaction request you send later.

Request an OAuth access token with client_credentials and the environment's audience. Send Authorization: Bearer YOUR_ACCESS_TOKEN and Content-Type: application/json.

Parameters in delivery

{
  "delivery": {
    "method": "email",
    "email": "buyer@example.com",
    "country_code": "DE",
    "language": "en"
  },
  "currency": "EUR",
  "payment_method": {
    "payment_option": "OPEN_INVOICE",
    "transfer_type": "BANK_TRANSFER"
  },
  "shop_baskets": [
    {
      "partner_shop_id": "INTEGRATION_TE_DACH",
      "shop_transaction_id": "shop-transaction-id-1234",
      "gross_amount": 200,
      "items": [
        {
          "article_number": "urban-pack",
          "category": "bags",
          "description": "Lightweight backpack with a padded laptop compartment",
          "gross_total_price": 180,
          "gross_unit_price": 180,
          "name": "Urban Pack",
          "net_total_price": 151.26,
          "net_unit_price": 151.26,
          "quantity": 1,
          "tax_rate": 19,
          "unit": "piece"
        }
      ],
      "special_items": [
        {
          "article_number": "SHIPPING_001",
          "category": "shipping",
          "description": "Standard shipping via DHL",
          "gross_total_price": 20,
          "gross_unit_price": 20,
          "name": "Shipping costs",
          "net_total_price": 16.81,
          "net_unit_price": 16.81,
          "quantity": 1,
          "tax_rate": 19,
          "unit": "shipment"
        }
      ],
      "vats": [
        {
          "net_amount": 168.07,
          "tax_amount": 31.93,
          "tax_rate": 19
        }
      ]
    }
  ]
}

Before continuing, check that:

• Your backend sends the right Secci generation request for each delivery action. The basket, payment method and amount must match the payment you'll submit.

4. Handle the SECCI response

Check for a successful response before allowing the buyer to finalize the order.

x-attestation-token: RETURNED_ATTESTATION_TOKEN
Content-Type: application/json

{
  "result": "SUCCESS",
  "secci_id": "SCCMS8BH-27092026"
}

SECCI Status Handling Guideline

If SECCI is successful:

• Store the x-attestation-token value with the current checkout or order attempt. You need it in step 5. The x-attestation-token is valid for 7 days. If it expires before the Authorize transaction request, request a SECCI again and use the new token.
• If the basket or payment method changes, discard the token and request a new SECCI.

If SECCI request fails: Suggested buyer-facing copy:

Before continuing, check that:

• Each response is checked and the document reaches the buyer by the chosen method
• The attestation token is stored against the order attempt
• A SECCI delivery success message is implemented
• A SECCI delivery failure message and retry workflow is implemented
• Pending, failed and timed-out requests block payment

5. Submit payment

Keep your existing Authorize transaction request at POST /v2/transactions.

New for CCD2: Add the value from the successful SECCI response header x-attestation-token as compliance_details.attestation_token. This is part of your existing authorization request, not a new request.

{
  "compliance_details": {
    "attestation_token": "STORED_X_ATTESTATION_TOKEN"
  },
  ...
}

Matching data: the basket, payment method and amount must match the successful SECCI generation request. Otherwise Ratepay rejects the payment with HTTP status code 422:

{
    "type": "https://api.ratepay.com/transaction/management/v2/validation/unprocessable_operation",
    "ratepay_transaction_id": "RATEPAY_TRANSACTION_ID",
    "created": "2026-10-07T11:10:36.534+02:00",
    "result": "DECLINED",
    "decline": {
        "category": "UNPROCESSABLE_OPERATION",
        "reasons": [
            "COMPLIANCE_ATTESTATION_TOKEN_VALIDATION_FAILED"
        ]
    },
    "_links": {
        "self": {
            "href": "https://api-integration.ratepay.com/transaction/management/v2/transactions/RATEPAY_TRANSACTION_ID"
        }
    }
}

If anything changed, request a new SECCI.

When to allow order submission:

• Online shop: Enable order submission after a successful email SECCI request; or after the returned PDF has been provided to the buyer.
• MOTO: Complete the SECCI provision process described for the selected MOTO option in step 2 before submitting the payment.
• Point of sale: keep the submit action disabled until the email is sent, or until the PDF is printed and handed over.

Before continuing, check that:

• in-scope payments are submitted only after successful document provision, with the stored attestation-token and matching basket and payment method

6. Handle credit declines

When Ratepay declines a payment for credit-risk reasons under CCD2, the response will have the HTTP status code 422, with CREDIT_RISK as decline.category.

• Use the returned decline.message for the buyer's language when present.
• The text can contain named placeholders; match each placeholder to an entry in links by rel.
• Render its supplied label and URL as a link in your frontend.

Note:

• Its content differs by country and language.
• Do not replace the full explanation with a generic decline text.
• Other decline categories can have different response shapes.

{
  "_links": {
    "self": {
      "href": "https://api-integration.ratepay.com/transaction/management/v2/transactions/EXAMPLE_TRANSACTION_ID"
    }
  },
  "created": "2026-09-27T14:15:22Z",
  "decline": {
    "category": "CREDIT_RISK",
    "message": {
      "en": {
        "text": "Our partner Ratepay ran a credit check with SCHUFA Holding AG, using your name, address and, if provided, date of birth. The score came back at 5700, below what this transaction requires. To exercise your {data_protection_rights} or to request a human review of the decision, {contact_ratepay}.",
        "links": [
          {
            "rel": "data_protection_rights",
            "href": "https://www.ratepay.com/en/ratepay-data-privacy-statement",
            "label": "Data Protection Rights"
          },
          {
            "rel": "contact_ratepay",
            "href": "https://www.ratepay.com/en/shoppers/contact",
            "label": "Contact Ratepay"
          }
        ]
      }
    }
  },
  "ratepay_transaction_id": "EXAMPLE_TRANSACTION_ID",
  "result": "DECLINED"
}

Showing the message:

• Online shop: Show the message and links on the buyer's result screen. Keep another available payment method accessible.
• MOTO: Show the message and links in the staff order-entry flow so the employee can communicate them and offer another method.
• POS: Show them in the staff result so the employee can explain the decision and review options.

Illustrative buyer-facing credit decline

Before continuing, check that:

• The full message, with working links, appears in the buyer or staff result view
• Other payment methods stay available
• A declined transaction can't be processed as an accepted order.

7. After the purchase

No action needed. Continue your normal order process.

When you capture the transaction, Ratepay sends the Credit Contract Information to the buyer. If the amount increases later, Ratepay provides any updated credit information. There is no new SECCI generation request or token after checkout.

Test your integration

Before going live, run the test scenarios in the integration environment.