Skip to content

Ratepay via Avarda - Developer Guide

This guide explains how merchants can integrate Ratepay payment methods via Avarda Checkout. All links point to official documentation, ensuring the page stays up to date.

Official References

Avarda & Ratepay Overview

Avarda acts as a checkout platform and PSP for Ratepay methods, enabling merchants to offer:

  • Ratepay Open Invoice (Rechnungskauf / Buy Now Pay Later)
  • Ratepay SEPA Direct Debit

Avarda handles all communication with Ratepay’s APIs, including credit checks and risk evaluation. Merchants interact only with the Avarda Checkout API, which encapsulates Ratepay logic.

Supported markets include DACH and the Netherlands, with region-specific configuration handled by Avarda.

Currently available per default: Germany

Integration Options

1. Avarda Checkout 3 (Recommended)

  • Use Avarda Checkout API to render Ratepay options dynamically.
  • Supports both Open Invoice and Direct Debit.
  • Configuration for Ratepay payment types is controlled in your Avarda merchant account.

2. Custom Frontend + Avarda API

  • Build a custom checkout form.
  • Submit payment requests to the Avarda API endpoint.
  • Include all required buyer information and optional Ratepay parameters.

All Ratepay-specific data (e.g., device fingerprint, billing/delivery addresses) must be provided according to the Ratepay documentation.

Technical Requirements

HTTPS & Content Security Policy (CSP)

Avarda Checkout + Ratepay requires secure loading of scripts and CSS:

Content-Security-Policy:
script-src 'self' https://d.ratepay.com https://*.avarda.com;
style-src 'self' https://d.ratepay.com;
  • Ensures external resources for Ratepay and Avarda are correctly loaded.
  • Avoids CSP-related runtime errors during checkout.

Buyer data

Required for all Ratepay methods:

  • First & Last Name
  • Date of Birth
  • Email & Phone Number
  • Billing Address
  • Delivery Address (if different from billing)

Missing or invalid fields may cause the payment to be Refused.

Device Fingerprinting

Unlike some PSPs, Avarda Checkout encapsulates the device fingerprinting step in its frontend flow, and you do not need to generate or send a fingerprint manually for Avarda’s standard checkout (Checkout 3).

The merchant backend will receive the result via Avarda APIs without adding a separate fingerprint parameter.

However, if you are implementing a custom Authorization API integration outside of Avarda Checkout 3 (e.g., directly calling Avarda’s backend APIs for credit authorization), you must follow Ratepay's own implementation pattern for any device/fraud signals required by that API configuration.

Ratepay Open Invoice requires device fingerprinting for risk evaluation:

{
  "paymentMethod": { "type": "ratepay" },
  "deviceFingerprint": "<generated_fingerprint>",
  "shopperEmail": "shopper@example.com",
  "billingAddress": { ... },
  "deliveryAddress": { ... }
}

Payment Flow

  1. Retrieve available payment methods from Avarda Checkout API.
  • Returns ratepay_open_invoice and/or ratepay_direct_debit if enabled.
  1. Render Ratepay options in your frontend checkout.
  2. Submit payment request via Avarda API. Include:
  • Buyer info
  • Device fingerprint (for Open Invoice)
  • Payment method identifier
  • Shopping basket
  1. Process payment response:
Response TypeMeaning
AuthorisedPayment accepted, proceed with order
RefusedPayment declined; reason provided in refusalReasonRaw
CancelledBuyer cancelled the transaction
  1. Capture Open Invoice payments after shipment.
  2. Refunds / cancellations handled via Avarda API.

Rejection & Error Handling (Avarda)

Avarda Authorization Response

When integrating Ratepay via Avarda, the payment and credit authorization process uses Avarda’s Authorization API or Checkout 3 flow. Avarda returns standard REST API status codes and structured error bodies rather than a generic Refused event with “RefusalReasonRaw”.

Authorization (Credit) Responses Avarda returns different HTTP status codes depending on the authorization outcome:

  • 202 Accepted – Credit authorization accepted (may require ID validation)
  • 200 OK – Credit approved and complete
  • 422 Unprocessable Entity – Credit Authorization Rejected
  • 400 Bad Request – Invalid request data
  • 500 Internal Server Error – Technical error

In case of a rejection (HTTP 422), the response body contains:

{
  "errorCode": 2,
  "errorMessage": "Credit not approved please try different payment method",
  "authorizationId": "3b2309d4565446b1996dcb92fe40f332"
}
  • errorCode – Avarda-specific rejection code
  • errorMessage – Localized (customer language) explanation
  • authorizationId – Authorization identifier (useful for logging and support)

Action for developers:

  • Map Avarda error codes to your application logic.
  • Communicate the reason back to the shopper where appropriate.
  • If needed, log the authorizationId and errorCode for operational support or debugging.

See Avarda’s Authorization API docs for more details: https://docs.avarda.com/authorization-api/api-reference/create-credit-authorization/

Avarda Checkout Flow Rejections

When using Avarda Checkout 3, the checkout interface handles client‑side event callbacks and may reflect errors directly in the frontend (e.g., user validation, required fields). The backend should still validate transaction completeness and surface any errors returned by the API.

Avarda Checkout 3 provides debug logging and callbacks (e.g., beforeSubmitCallback) that can help identify issues client‑side before payment submission.

For troubleshooting and client‑side debugging: https://docs.avarda.com/checkout-3/troubleshooting/

Summary - Developer Tips

Rejection Handling

  • Avarda uses standard HTTP statuses (e.g., 422 for rejection) with structured JSON error bodies.
  • Inspect errorCode and errorMessage for rejection reasons and implement corresponding logic.

Device Fingerprint

  • In the Avarda Checkout 3 frontend, device fingerprinting and risk signals are handled by the Avarda widget.
  • You do not need to manually implement Ratepay device fingerprint logic unless you’re building a non‑Checkout API integration that specifically requires it.

Helpful References