# 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 Documentation:
[https://docs.avarda.com](https://docs.avarda.com/)
- Ratepay Checkout Integration in Avarda:
[https://docs.avarda.com/checkout-3/more-features/ratepay/](https://docs.avarda.com/checkout-3/more-features/ratepay/)


## 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:

- Generate fingerprint during checkout and include it in the payment request.
- Follow Ratepay’s guide: [Device Fingerprinting Documentation](https://docs.ratepay.com/docs/developer/device_fingerprinting/device_fingerprinting)



```json
{
  "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 Type | Meaning |
|  --- | --- |
| `Authorised` | Payment accepted, proceed with order |
| `Refused` | Payment declined; reason provided in `refusalReasonRaw` |
| `Cancelled` | Buyer 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:


```json
{
  "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

- **Avarda Authorization API — Error Codes & Rejections**
[https://docs.avarda.com/authorization-api/api-reference/create-credit-authorization/](https://docs.avarda.com/authorization-api/api-reference/create-credit-authorization/)
- **Avarda Checkout 3 Troubleshooting** (client‑side callbacks)
[https://docs.avarda.com/checkout-3/troubleshooting/](https://docs.avarda.com/checkout-3/troubleshooting/)
- **Ratepay Device Fingerprinting (for direct API integrations)**
[https://docs.ratepay.com/docs/developer/device_fingerprinting/device_fingerprinting](https://docs.ratepay.com/docs/developer/device_fingerprinting/device_fingerprinting)