---
title: "Ratepay for API only"
description: "Add Ratepay to an existing API-only integration."
url: "https://docs.adyen.com/payment-methods/ratepay/api-only"
source_url: "https://docs.adyen.com/payment-methods/ratepay/api-only.md"
canonical: "https://docs.adyen.com/payment-methods/ratepay/api-only"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# Ratepay for API only

Add Ratepay to an existing API-only integration.

[View source](/payment-methods/ratepay/api-only.md)

Accept Ratepay payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.

When making a Ratepay payment, you need to [capture](#capture-the-payment) the payment after the goods have been sent. This triggers the invoice to be sent to the shopper.

## Requirements

| Requirement          | Description                                                                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type** | Make sure that you have built an [API-only integration](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=API%20only). |
| **Setup steps**      | Before you begin, [add in your test Customer Area](/payment-methods/add-payment-methods).                                                            |

## Preparation

Implement [Ratepay's device fingerprinting](https://docs.ratepay.com/docs/developer/device_fingerprinting/device_fingerprinting/) to collect the shopper's device fingerprint for risk evaluation.

## Build your payment form for Ratepay

If you are using the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) endpoint to show which payment methods are available to the shopper, in your request specify one of the following combinations of [countryCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) and [amount.currency](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods#request-amount):

| Country/region  | `countryCode` | `amount.currency` |
| --------------- | ------------- | ----------------- |
| Austria         | **AT**        | **EUR**           |
| Germany         | **DE**        | **EUR**           |
| The Netherlands | **NL**        | **EUR**           |
| Switzerland     | **CH**        | **CHF**           |

The response indicates the available payment types:

* `paymentMethod.type`: **ratepay** (Ratepay Open invoice) and **ratepay\_directdebit** (Ratepay Direct debit). Note that Ratepay Direct debit is not available in Switzerland.

When the shopper selects a payment type, you will need to specify the corresponding `paymentMethod.type` value in your [payment request](#make-a-payment).

We provide a Ratepay logo which you can use in your payment form. For more information, refer to [Downloading logos](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only#downloading-logos).

## Collect shopper details

To make a Ratepay payment, you also need to collect the following shopper details:

| Name              | Description                                                                   |
| ----------------- | ----------------------------------------------------------------------------- |
| `firstName`       | Shopper's first name.                                                         |
| `lastName`        | Shopper's last name.                                                          |
| `dateOfBirth`     | Shopper's date of birth.                                                      |
| `telephoneNumber` | Shopper's phone number.                                                       |
| `shopperEmail`    | Shopper's email address.                                                      |
| `billingAddress`  | The address where to send the invoice.                                        |
| `deliveryAddress` | Only required if the delivery address is not the same as the billing address. |

## Calculate the device fingerprint

Before making a payment you need to implement [Ratepay's device fingerprinting](https://docs.ratepay.com/docs/developer/device_fingerprinting/device_fingerprinting/). Send the calculated device fingerprint when making a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request.

## Make a payment

From your server, make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, specifying the following parameters:

### Tab: Open invoice

| Parameter               | Required                                                                                    | Description                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `paymentMethod.type`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **ratepay**.                                                                                                         |
| `shopperName.firstName` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's first name.                                                                                                       |
| `shopperName.lastName`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's last name.                                                                                                        |
| `telephoneNumber`       | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's telephone number.                                                                                                 |
| `shopperEmail`          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's email address.                                                                                                    |
| `dateOfBirth`           | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's date of birth. Format [ISO-8601](https://www.w3.org/TR/NOTE-datetime): YYYY-MM-DD                                 |
| `billingAddress`        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The address where to send the invoice.                                                                                      |
| `deviceFingerprint`     | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A string containing the shopper's [device fingerprint](#calculate-device-fingerprint).                                      |
| `deliveryAddress`       | ![-x-](/user/data/smileys/emoji/x.png "-x-")                                                | Only required if the delivery address is not the same as the billing address.                                               |
| `lineItems`             | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Price and product information about the purchased items. This is included on the invoice that Ratepay sends to the shopper. |

#### curl

```bash
curl https://checkout-test.adyen.com/v68/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
    "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
    "reference": "YOUR_ORDER_REFERENCE",
    "paymentMethod": {
        "type": "ratepay"
    },
    "amount": {
        "currency": "EUR",
        "value": "1000"
    },
    "deviceFingerprint": "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
    "countryCode": "NL",
    "dateOfBirth": "1970-07-10",
    "telephoneNumber": "+31858888138",
    "shopperEmail": "s.hopper@example.com",
    "shopperName": {
        "firstName": "Simon",
        "lastName": "Hopper"
    },
    "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
    "billingAddress": {
        "city": "Amsterdam",
        "country": "NL",
        "houseNumberOrName": "6-50",
        "postalCode": "1011 DJ",
        "street": "Simon Carmiggeltstraat"
    },
    "lineItems": [
        {
            "quantity": "1",
            "amountExcludingTax": "331",
            "taxPercentage": "2100",
            "description": "Shoes",
            "id": "Item #1",
            "taxAmount": "69",
            "amountIncludingTax": "400",
            "taxCategory": "High"
        },
        {
            "quantity": "2",
            "amountExcludingTax": "248",
            "taxPercentage": "2100",
            "description": "Socks",
            "id": "Item #2",
            "taxAmount": "52",
            "amountIncludingTax": "300",
            "taxCategory": "High"
        }
    ]
}'
```

#### Java

```java
// Adyen Java API Library v27.0.0
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.model.checkout.*;
import java.time.OffsetDateTime;
import java.util.*;
import com.adyen.model.RequestOptions;
import com.adyen.service.checkout.*;

// For the live environment, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

LineItem lineItem1 = new LineItem()
  .quantity(1L)
  .amountExcludingTax(331L)
  .taxPercentage(2100L)
  .description("Shoes")
  .id("Item #1")
  .taxAmount(69L)
  .amountIncludingTax(400L);

LineItem lineItem2 = new LineItem()
  .quantity(2L)
  .amountExcludingTax(248L)
  .taxPercentage(2100L)
  .description("Socks")
  .id("Item #2")
  .taxAmount(52L)
  .amountIncludingTax(300L);

Name name = new Name()
  .firstName("Simon")
  .lastName("Hopper");

RatepayDetails ratepayDetails = new RatepayDetails()
  .type(RatepayDetails.TypeEnum.RATEPAY);

BillingAddress billingAddress = new BillingAddress()
  .country("NL")
  .city("Amsterdam")
  .houseNumberOrName("6-50")
  .street("Simon Carmiggeltstraat")
  .postalCode("1011 DJ");

PaymentRequest paymentRequest = new PaymentRequest()
  .amount(amount)
  .telephoneNumber("+31858888138")
  .deviceFingerprint("eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...")
  .dateOfBirth(OffsetDateTime.parse("1970-07-10"))
  .shopperEmail("s.hopper@example.com")
  .reference("YOUR_ORDER_REFERENCE")
  .lineItems(Arrays.asList(lineItem1, lineItem2))
  .shopperName(name)
  .merchantAccount("ADYEN_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .paymentMethod(new CheckoutPaymentMethod(ratepayDetails))
  .billingAddress(billingAddress)
  .shopperReference("YOUR_UNIQUE_SHOPPER_ID");

// Send the request
PaymentsApi service = new PaymentsApi(client);
PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\LineItem;
use Adyen\Model\Checkout\Name;
use Adyen\Model\Checkout\CheckoutPaymentMethod;
use Adyen\Model\Checkout\BillingAddress;
use Adyen\Model\Checkout\PaymentRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$lineItem1 = new LineItem();
$lineItem1
  ->setQuantity(1)
  ->setAmountExcludingTax(331)
  ->setTaxPercentage(2100)
  ->setDescription("Shoes")
  ->setId("Item #1")
  ->setTaxAmount(69)
  ->setAmountIncludingTax(400);

$lineItem2 = new LineItem();
$lineItem2
  ->setQuantity(2)
  ->setAmountExcludingTax(248)
  ->setTaxPercentage(2100)
  ->setDescription("Socks")
  ->setId("Item #2")
  ->setTaxAmount(52)
  ->setAmountIncludingTax(300);

$name = new Name();
$name
  ->setFirstName("Simon")
  ->setLastName("Hopper");

$checkoutPaymentMethod = new CheckoutPaymentMethod();
$checkoutPaymentMethod
  ->setType("ratepay");

$billingAddress = new BillingAddress();
$billingAddress
  ->setCountry("NL")
  ->setCity("Amsterdam")
  ->setHouseNumberOrName("6-50")
  ->setStreet("Simon Carmiggeltstraat")
  ->setPostalCode("1011 DJ");

$paymentRequest = new PaymentRequest();
$paymentRequest
  ->setAmount($amount)
  ->setTelephoneNumber("+31858888138")
  ->setDeviceFingerprint("eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...")
  ->setDateOfBirth("1970-07-10")
  ->setShopperEmail("s.hopper@example.com")
  ->setReference("YOUR_ORDER_REFERENCE")
  ->setLineItems(array($lineItem1, $lineItem2))
  ->setShopperName($name)
  ->setMerchantAccount("ADYEN_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setPaymentMethod($checkoutPaymentMethod)
  ->setBillingAddress($billingAddress)
  ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->payments($paymentRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

LineItem lineItem1 = new LineItem
{
  Quantity = 1,
  AmountExcludingTax = 331,
  TaxPercentage = 2100,
  Description = "Shoes",
  Id = "Item #1",
  TaxAmount = 69,
  AmountIncludingTax = 400
};

LineItem lineItem2 = new LineItem
{
  Quantity = 2,
  AmountExcludingTax = 248,
  TaxPercentage = 2100,
  Description = "Socks",
  Id = "Item #2",
  TaxAmount = 52,
  AmountIncludingTax = 300
};

Name name = new Name
{
  FirstName = "Simon",
  LastName = "Hopper"
};

RatepayDetails ratepayDetails = new RatepayDetails
{
  Type = RatepayDetails.TypeEnum.Ratepay
};

BillingAddress billingAddress = new BillingAddress
{
  Country = "NL",
  City = "Amsterdam",
  HouseNumberOrName = "6-50",
  Street = "Simon Carmiggeltstraat",
  PostalCode = "1011 DJ"
};

PaymentRequest paymentRequest = new PaymentRequest
{
  Amount = amount,
  TelephoneNumber = "+31858888138",
  DeviceFingerprint = "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  DateOfBirth = DateTime.Parse("1970-07-10"),
  ShopperEmail = "s.hopper@example.com",
  Reference = "YOUR_ORDER_REFERENCE",
  LineItems = new List<LineItem>{ lineItem1, lineItem2 },
  ShopperName = name,
  MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  PaymentMethod = new CheckoutPaymentMethod(ratepayDetails),
  BillingAddress = billingAddress,
  ShopperReference = "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const paymentRequest = {
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  reference: "YOUR_ORDER_REFERENCE",
  paymentMethod: {
    type: "ratepay"
  },
  amount: {
    currency: "EUR",
    value: "1000"
  },
  deviceFingerprint: "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  countryCode: "NL",
  dateOfBirth: new Date("1970-07-10"),
  telephoneNumber: "+31858888138",
  shopperEmail: "s.hopper@example.com",
  shopperName: {
    firstName: "Simon",
    lastName: "Hopper"
  },
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID",
  billingAddress: {
    city: "Amsterdam",
    country: "NL",
    houseNumberOrName: "6-50",
    postalCode: "1011 DJ",
    street: "Simon Carmiggeltstraat"
  },
  lineItems: [ {
    quantity: "1",
    amountExcludingTax: "331",
    taxPercentage: "2100",
    description: "Shoes",
    id: "Item #1",
    taxAmount: "69",
    amountIncludingTax: "400",
    taxCategory: "High"
  }, {
    quantity: "2",
    amountExcludingTax: "248",
    taxPercentage: "2100",
    description: "Socks",
    id: "Item #2",
    taxAmount: "52",
    amountIncludingTax: "300",
    taxCategory: "High"
  } ]
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.0
import (
  "context"
  "time"
  "github.com/adyen/adyen-go-api-library/v9/src/common"
  "github.com/adyen/adyen-go-api-library/v9/src/adyen"
  "github.com/adyen/adyen-go-api-library/v9/src/checkout"
)
// For the live environment, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

lineItem1 := checkout.LineItem{
  Quantity: common.PtrInt64(1),
  AmountExcludingTax: common.PtrInt64(331),
  TaxPercentage: common.PtrInt64(2100),
  Description: common.PtrString("Shoes"),
  Id: common.PtrString("Item #1"),
  TaxAmount: common.PtrInt64(69),
  AmountIncludingTax: common.PtrInt64(400),
}

lineItem2 := checkout.LineItem{
  Quantity: common.PtrInt64(2),
  AmountExcludingTax: common.PtrInt64(248),
  TaxPercentage: common.PtrInt64(2100),
  Description: common.PtrString("Socks"),
  Id: common.PtrString("Item #2"),
  TaxAmount: common.PtrInt64(52),
  AmountIncludingTax: common.PtrInt64(300),
}

name := checkout.Name{
  FirstName: "Simon",
  LastName: "Hopper",
}

ratepayDetails := checkout.RatepayDetails{
  Type: "ratepay",
}

billingAddress := checkout.BillingAddress{
  Country: "NL",
  City: "Amsterdam",
  HouseNumberOrName: "6-50",
  Street: "Simon Carmiggeltstraat",
  PostalCode: "1011 DJ",
}

paymentRequest := checkout.PaymentRequest{
  Amount: amount,
  TelephoneNumber: common.PtrString("+31858888138"),
  DeviceFingerprint: common.PtrString("eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ..."),
  DateOfBirth:  func() *time.Time { t, _ := time.Parse(time.RFC3339, "1970-07-10"); return &t }(),
  ShopperEmail: common.PtrString("s.hopper@example.com"),
  Reference: "YOUR_ORDER_REFERENCE",
  LineItems: []checkout.LineItem{
      lineItem1, lineItem2,
  },
  ShopperName: &name,
  MerchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  PaymentMethod: checkout.RatepayDetailsAsCheckoutPaymentMethod(&ratepayDetails),
  BillingAddress: &billingAddress,
  ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"),
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest)
res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "reference": "YOUR_ORDER_REFERENCE",
  "paymentMethod": {
    "type": "ratepay"
  },
  "amount": {
    "currency": "EUR",
    "value": "1000"
  },
  "deviceFingerprint": "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  "countryCode": "NL",
  "dateOfBirth": "1970-07-10",
  "telephoneNumber": "+31858888138",
  "shopperEmail": "s.hopper@example.com",
  "shopperName": {
    "firstName": "Simon",
    "lastName": "Hopper"
  },
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "billingAddress": {
    "city": "Amsterdam",
    "country": "NL",
    "houseNumberOrName": "6-50",
    "postalCode": "1011 DJ",
    "street": "Simon Carmiggeltstraat"
  },
  "lineItems": [ {
    "quantity": "1",
    "amountExcludingTax": "331",
    "taxPercentage": "2100",
    "description": "Shoes",
    "id": "Item #1",
    "taxAmount": "69",
    "amountIncludingTax": "400",
    "taxCategory": "High"
  }, {
    "quantity": "2",
    "amountExcludingTax": "248",
    "taxPercentage": "2100",
    "description": "Socks",
    "id": "Item #2",
    "taxAmount": "52",
    "amountIncludingTax": "300",
    "taxCategory": "High"
  } ]
}

# Send the request
result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'ADYEN_MERCHANT_ACCOUNT',
  :reference => 'YOUR_ORDER_REFERENCE',
  :paymentMethod => {
    :type => 'ratepay'
  },
  :amount => {
    :currency => 'EUR',
    :value => '1000'
  },
  :deviceFingerprint => 'eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...',
  :countryCode => 'NL',
  :dateOfBirth => '1970-07-10',
  :telephoneNumber => '+31858888138',
  :shopperEmail => 's.hopper@example.com',
  :shopperName => {
    :firstName => 'Simon',
    :lastName => 'Hopper'
  },
  :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID',
  :billingAddress => {
    :city => 'Amsterdam',
    :country => 'NL',
    :houseNumberOrName => '6-50',
    :postalCode => '1011 DJ',
    :street => 'Simon Carmiggeltstraat'
  },
  :lineItems => [ {
    :quantity => '1',
    :amountExcludingTax => '331',
    :taxPercentage => '2100',
    :description => 'Shoes',
    :id => 'Item #1',
    :taxAmount => '69',
    :amountIncludingTax => '400',
    :taxCategory => 'High'
  }, {
    :quantity => '2',
    :amountExcludingTax => '248',
    :taxPercentage => '2100',
    :description => 'Socks',
    :id => 'Item #2',
    :taxAmount => '52',
    :amountIncludingTax => '300',
    :taxCategory => 'High'
  } ]
}

# Send the request
result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const lineItem1: Types.checkout.LineItem = {
  quantity: 1,
  amountExcludingTax: 331,
  taxPercentage: 2100,
  description: "Shoes",
  id: "Item #1",
  taxAmount: 69,
  amountIncludingTax: 400
};

const lineItem2: Types.checkout.LineItem = {
  quantity: 2,
  amountExcludingTax: 248,
  taxPercentage: 2100,
  description: "Socks",
  id: "Item #2",
  taxAmount: 52,
  amountIncludingTax: 300
};

const name: Types.checkout.Name = {
  firstName: "Simon",
  lastName: "Hopper"
};

const ratepayDetails: Types.checkout.RatepayDetails = {
  type: Types.checkout.RatepayDetails.TypeEnum.Ratepay
};

const billingAddress: Types.checkout.BillingAddress = {
  country: "NL",
  city: "Amsterdam",
  houseNumberOrName: "6-50",
  street: "Simon Carmiggeltstraat",
  postalCode: "1011 DJ"
};

const paymentRequest: Types.checkout.PaymentRequest = {
  amount: amount,
  telephoneNumber: "+31858888138",
  deviceFingerprint: "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  dateOfBirth: new Date("1970-07-10"),
  shopperEmail: "s.hopper@example.com",
  reference: "YOUR_ORDER_REFERENCE",
  lineItems: [lineItem1, lineItem2],
  shopperName: name,
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  countryCode: "NL",
  paymentMethod: ratepayDetails,
  billingAddress: billingAddress,
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" });
```

### Tab: Direct debit

| Parameter                 | Required                                                                                    | Description                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `paymentMethod.type`      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **ratepay\_directdebit**. Unavailable in Switzerland.                                                                |
| `shopperName.firstName`   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's first name.                                                                                                       |
| `shopperName.lastName`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's last name.                                                                                                        |
| `telephoneNumber`         | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's telephone number.                                                                                                 |
| `shopperEmail`            | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's email address.                                                                                                    |
| `dateOfBirth`             | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's date of birth. Format [ISO-8601](https://www.w3.org/TR/NOTE-datetime): YYYY-MM-DD.                                |
| `billingAddress`          | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The address where to send the invoice.                                                                                      |
| `deviceFingerprint`       | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A string containing the shopper's [device fingerprint](#calculate-device-fingerprint).                                      |
| `deliveryAddress`         | ![-x-](/user/data/smileys/emoji/x.png "-x-")                                                | Only required if the delivery address is not the same as the billing address.                                               |
| `lineItems`               | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Price and product information about the purchased items. This is included on the invoice that Ratepay sends to the shopper. |
| `bankAccount.countryCode` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's country/region. Format: [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).                   |
| `bankAccount.iban`        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Shopper's International Bank Account Number (IBAN).                                                                         |
| `bankAccount.ownerName`   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Name of the bank account holder.                                                                                            |

#### curl

```bash
curl https://checkout-test.adyen.com/v68/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
    "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
    "countryCode": "NL",
    "amount": {
        "currency": "EUR",
        "value": 1000
    },
    "bankAccount": {
        "countryCode": "NL",
        "iban": "NL87123456781234567890",
        "ownerName": "Simon Hopper"
    },
    "deviceFingerprint": "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
    "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
    "reference": "YOUR_ORDER_NUMBER",
    "paymentMethod": {
        "type": "ratepay"
    },
    "shopperName": {
        "firstName": "Simon",
        "lastName": "Hopper"
    },
    "telephoneNumber": "+31858888138",
    "shopperEmail": "s.shopper@example.com",
    "dateOfBirth": "1970-07-10",
    "billingAddress": {
        "street": "Simon Carmiggeltstraat",
        "houseNumberOrName": "136",
        "city": "Amsterdam",
        "postalCode": "1011DJ",
        "country": "NL"
    },
    "lineItems": [
        {
            "quantity": "1",
            "amountExcludingTax": "331",
            "taxPercentage": "2100",
            "description": "Shoes",
            "id": "Item #1",
            "taxAmount": "69",
            "amountIncludingTax": "400",
            "taxCategory": "High"
        },
        {
            "quantity": "2",
            "amountExcludingTax": "248",
            "taxPercentage": "2100",
            "description": "Socks",
            "id": "Item #2",
            "taxAmount": "52",
            "amountIncludingTax": "300",
            "taxCategory": "High"
        }
    ]
}'
```

#### Java

```java
// Adyen Java API Library v27.0.0
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.model.checkout.*;
import java.time.OffsetDateTime;
import java.util.*;
import com.adyen.model.RequestOptions;
import com.adyen.service.checkout.*;

// For the live environment, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
Amount amount = new Amount()
  .currency("EUR")
  .value(1000L);

LineItem lineItem1 = new LineItem()
  .quantity(1L)
  .amountExcludingTax(331L)
  .taxPercentage(2100L)
  .description("Shoes")
  .id("Item #1")
  .taxAmount(69L)
  .amountIncludingTax(400L);

LineItem lineItem2 = new LineItem()
  .quantity(2L)
  .amountExcludingTax(248L)
  .taxPercentage(2100L)
  .description("Socks")
  .id("Item #2")
  .taxAmount(52L)
  .amountIncludingTax(300L);

Name name = new Name()
  .firstName("Simon")
  .lastName("Hopper");

RatepayDetails ratepayDetails = new RatepayDetails()
  .type(RatepayDetails.TypeEnum.RATEPAY);

BillingAddress billingAddress = new BillingAddress()
  .country("NL")
  .city("Amsterdam")
  .street("Simon Carmiggeltstraat")
  .houseNumberOrName("136")
  .postalCode("1011DJ");

PaymentRequest paymentRequest = new PaymentRequest()
  .amount(amount)
  .telephoneNumber("+31858888138")
  .deviceFingerprint("eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...")
  .shopperEmail("s.shopper@example.com")
  .dateOfBirth(OffsetDateTime.parse("1970-07-10"))
  .reference("YOUR_ORDER_NUMBER")
  .lineItems(Arrays.asList(lineItem1, lineItem2))
  .shopperName(name)
  .merchantAccount("ADYEN_MERCHANT_ACCOUNT")
  .countryCode("NL")
  .paymentMethod(new CheckoutPaymentMethod(ratepayDetails))
  .billingAddress(billingAddress)
  .shopperReference("YOUR_UNIQUE_SHOPPER_ID");

// Send the request
PaymentsApi service = new PaymentsApi(client);
PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\LineItem;
use Adyen\Model\Checkout\Name;
use Adyen\Model\Checkout\CheckoutPaymentMethod;
use Adyen\Model\Checkout\BillingAddress;
use Adyen\Model\Checkout\PaymentRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$amount = new Amount();
$amount
  ->setCurrency("EUR")
  ->setValue(1000);

$lineItem1 = new LineItem();
$lineItem1
  ->setQuantity(1)
  ->setAmountExcludingTax(331)
  ->setTaxPercentage(2100)
  ->setDescription("Shoes")
  ->setId("Item #1")
  ->setTaxAmount(69)
  ->setAmountIncludingTax(400);

$lineItem2 = new LineItem();
$lineItem2
  ->setQuantity(2)
  ->setAmountExcludingTax(248)
  ->setTaxPercentage(2100)
  ->setDescription("Socks")
  ->setId("Item #2")
  ->setTaxAmount(52)
  ->setAmountIncludingTax(300);

$name = new Name();
$name
  ->setFirstName("Simon")
  ->setLastName("Hopper");

$checkoutPaymentMethod = new CheckoutPaymentMethod();
$checkoutPaymentMethod
  ->setType("ratepay");

$billingAddress = new BillingAddress();
$billingAddress
  ->setCountry("NL")
  ->setCity("Amsterdam")
  ->setStreet("Simon Carmiggeltstraat")
  ->setHouseNumberOrName("136")
  ->setPostalCode("1011DJ");

$paymentRequest = new PaymentRequest();
$paymentRequest
  ->setAmount($amount)
  ->setTelephoneNumber("+31858888138")
  ->setDeviceFingerprint("eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...")
  ->setShopperEmail("s.shopper@example.com")
  ->setDateOfBirth("1970-07-10")
  ->setReference("YOUR_ORDER_NUMBER")
  ->setLineItems(array($lineItem1, $lineItem2))
  ->setShopperName($name)
  ->setMerchantAccount("ADYEN_MERCHANT_ACCOUNT")
  ->setCountryCode("NL")
  ->setPaymentMethod($checkoutPaymentMethod)
  ->setBillingAddress($billingAddress)
  ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->payments($paymentRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
Amount amount = new Amount
{
  Currency = "EUR",
  Value = 1000
};

LineItem lineItem1 = new LineItem
{
  Quantity = 1,
  AmountExcludingTax = 331,
  TaxPercentage = 2100,
  Description = "Shoes",
  Id = "Item #1",
  TaxAmount = 69,
  AmountIncludingTax = 400
};

LineItem lineItem2 = new LineItem
{
  Quantity = 2,
  AmountExcludingTax = 248,
  TaxPercentage = 2100,
  Description = "Socks",
  Id = "Item #2",
  TaxAmount = 52,
  AmountIncludingTax = 300
};

Name name = new Name
{
  FirstName = "Simon",
  LastName = "Hopper"
};

RatepayDetails ratepayDetails = new RatepayDetails
{
  Type = RatepayDetails.TypeEnum.Ratepay
};

BillingAddress billingAddress = new BillingAddress
{
  Country = "NL",
  City = "Amsterdam",
  Street = "Simon Carmiggeltstraat",
  HouseNumberOrName = "136",
  PostalCode = "1011DJ"
};

PaymentRequest paymentRequest = new PaymentRequest
{
  Amount = amount,
  TelephoneNumber = "+31858888138",
  DeviceFingerprint = "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  ShopperEmail = "s.shopper@example.com",
  DateOfBirth = DateTime.Parse("1970-07-10"),
  Reference = "YOUR_ORDER_NUMBER",
  LineItems = new List<LineItem>{ lineItem1, lineItem2 },
  ShopperName = name,
  MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
  CountryCode = "NL",
  PaymentMethod = new CheckoutPaymentMethod(ratepayDetails),
  BillingAddress = billingAddress,
  ShopperReference = "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const paymentRequest = {
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  countryCode: "NL",
  amount: {
    currency: "EUR",
    value: 1000
  },
  bankAccount: {
    countryCode: "NL",
    iban: "NL87123456781234567890",
    ownerName: "Simon Hopper"
  },
  deviceFingerprint: "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID",
  reference: "YOUR_ORDER_NUMBER",
  paymentMethod: {
    type: "ratepay"
  },
  shopperName: {
    firstName: "Simon",
    lastName: "Hopper"
  },
  telephoneNumber: "+31858888138",
  shopperEmail: "s.shopper@example.com",
  dateOfBirth: new Date("1970-07-10"),
  billingAddress: {
    street: "Simon Carmiggeltstraat",
    houseNumberOrName: "136",
    city: "Amsterdam",
    postalCode: "1011DJ",
    country: "NL"
  },
  lineItems: [ {
    quantity: "1",
    amountExcludingTax: "331",
    taxPercentage: "2100",
    description: "Shoes",
    id: "Item #1",
    taxAmount: "69",
    amountIncludingTax: "400",
    taxCategory: "High"
  }, {
    quantity: "2",
    amountExcludingTax: "248",
    taxPercentage: "2100",
    description: "Socks",
    id: "Item #2",
    taxAmount: "52",
    amountIncludingTax: "300",
    taxCategory: "High"
  } ]
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.0
import (
  "context"
  "time"
  "github.com/adyen/adyen-go-api-library/v9/src/common"
  "github.com/adyen/adyen-go-api-library/v9/src/adyen"
  "github.com/adyen/adyen-go-api-library/v9/src/checkout"
)
// For the live environment, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
amount := checkout.Amount{
  Currency: "EUR",
  Value: 1000,
}

lineItem1 := checkout.LineItem{
  Quantity: common.PtrInt64(1),
  AmountExcludingTax: common.PtrInt64(331),
  TaxPercentage: common.PtrInt64(2100),
  Description: common.PtrString("Shoes"),
  Id: common.PtrString("Item #1"),
  TaxAmount: common.PtrInt64(69),
  AmountIncludingTax: common.PtrInt64(400),
}

lineItem2 := checkout.LineItem{
  Quantity: common.PtrInt64(2),
  AmountExcludingTax: common.PtrInt64(248),
  TaxPercentage: common.PtrInt64(2100),
  Description: common.PtrString("Socks"),
  Id: common.PtrString("Item #2"),
  TaxAmount: common.PtrInt64(52),
  AmountIncludingTax: common.PtrInt64(300),
}

name := checkout.Name{
  FirstName: "Simon",
  LastName: "Hopper",
}

ratepayDetails := checkout.RatepayDetails{
  Type: "ratepay",
}

billingAddress := checkout.BillingAddress{
  Country: "NL",
  City: "Amsterdam",
  Street: "Simon Carmiggeltstraat",
  HouseNumberOrName: "136",
  PostalCode: "1011DJ",
}

paymentRequest := checkout.PaymentRequest{
  Amount: amount,
  TelephoneNumber: common.PtrString("+31858888138"),
  DeviceFingerprint: common.PtrString("eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ..."),
  ShopperEmail: common.PtrString("s.shopper@example.com"),
  DateOfBirth:  func() *time.Time { t, _ := time.Parse(time.RFC3339, "1970-07-10"); return &t }(),
  Reference: "YOUR_ORDER_NUMBER",
  LineItems: []checkout.LineItem{
      lineItem1, lineItem2,
  },
  ShopperName: &name,
  MerchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  CountryCode: common.PtrString("NL"),
  PaymentMethod: checkout.RatepayDetailsAsCheckoutPaymentMethod(&ratepayDetails),
  BillingAddress: &billingAddress,
  ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"),
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest)
res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "bankAccount": {
    "countryCode": "NL",
    "iban": "NL87123456781234567890",
    "ownerName": "Simon Hopper"
  },
  "deviceFingerprint": "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "ratepay"
  },
  "shopperName": {
    "firstName": "Simon",
    "lastName": "Hopper"
  },
  "telephoneNumber": "+31858888138",
  "shopperEmail": "s.shopper@example.com",
  "dateOfBirth": "1970-07-10",
  "billingAddress": {
    "street": "Simon Carmiggeltstraat",
    "houseNumberOrName": "136",
    "city": "Amsterdam",
    "postalCode": "1011DJ",
    "country": "NL"
  },
  "lineItems": [ {
    "quantity": "1",
    "amountExcludingTax": "331",
    "taxPercentage": "2100",
    "description": "Shoes",
    "id": "Item #1",
    "taxAmount": "69",
    "amountIncludingTax": "400",
    "taxCategory": "High"
  }, {
    "quantity": "2",
    "amountExcludingTax": "248",
    "taxPercentage": "2100",
    "description": "Socks",
    "id": "Item #2",
    "taxAmount": "52",
    "amountIncludingTax": "300",
    "taxCategory": "High"
  } ]
}

# Send the request
result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'ADYEN_MERCHANT_ACCOUNT',
  :countryCode => 'NL',
  :amount => {
    :currency => 'EUR',
    :value => 1000
  },
  :bankAccount => {
    :countryCode => 'NL',
    :iban => 'NL87123456781234567890',
    :ownerName => 'Simon Hopper'
  },
  :deviceFingerprint => 'eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...',
  :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID',
  :reference => 'YOUR_ORDER_NUMBER',
  :paymentMethod => {
    :type => 'ratepay'
  },
  :shopperName => {
    :firstName => 'Simon',
    :lastName => 'Hopper'
  },
  :telephoneNumber => '+31858888138',
  :shopperEmail => 's.shopper@example.com',
  :dateOfBirth => '1970-07-10',
  :billingAddress => {
    :street => 'Simon Carmiggeltstraat',
    :houseNumberOrName => '136',
    :city => 'Amsterdam',
    :postalCode => '1011DJ',
    :country => 'NL'
  },
  :lineItems => [ {
    :quantity => '1',
    :amountExcludingTax => '331',
    :taxPercentage => '2100',
    :description => 'Shoes',
    :id => 'Item #1',
    :taxAmount => '69',
    :amountIncludingTax => '400',
    :taxCategory => 'High'
  }, {
    :quantity => '2',
    :amountExcludingTax => '248',
    :taxPercentage => '2100',
    :description => 'Socks',
    :id => 'Item #2',
    :taxAmount => '52',
    :amountIncludingTax => '300',
    :taxCategory => 'High'
  } ]
}

# Send the request
result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const amount: Types.checkout.Amount = {
  currency: "EUR",
  value: 1000
};

const lineItem1: Types.checkout.LineItem = {
  quantity: 1,
  amountExcludingTax: 331,
  taxPercentage: 2100,
  description: "Shoes",
  id: "Item #1",
  taxAmount: 69,
  amountIncludingTax: 400
};

const lineItem2: Types.checkout.LineItem = {
  quantity: 2,
  amountExcludingTax: 248,
  taxPercentage: 2100,
  description: "Socks",
  id: "Item #2",
  taxAmount: 52,
  amountIncludingTax: 300
};

const name: Types.checkout.Name = {
  firstName: "Simon",
  lastName: "Hopper"
};

const ratepayDetails: Types.checkout.RatepayDetails = {
  type: Types.checkout.RatepayDetails.TypeEnum.Ratepay
};

const billingAddress: Types.checkout.BillingAddress = {
  country: "NL",
  city: "Amsterdam",
  street: "Simon Carmiggeltstraat",
  houseNumberOrName: "136",
  postalCode: "1011DJ"
};

const paymentRequest: Types.checkout.PaymentRequest = {
  amount: amount,
  telephoneNumber: "+31858888138",
  deviceFingerprint: "eyJ2ZXJzaW9uIjoiMS4wLjAiLCJkZXZ...",
  shopperEmail: "s.shopper@example.com",
  dateOfBirth: new Date("1970-07-10"),
  reference: "YOUR_ORDER_NUMBER",
  lineItems: [lineItem1, lineItem2],
  shopperName: name,
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  countryCode: "NL",
  paymentMethod: ratepayDetails,
  billingAddress: billingAddress,
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" });
```

The [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response contains:

* `additionalData.openinvoicedata.descriptor`: The purpose of the payment which you should print on the invoice. The shopper provides it when making a bank transfer, so Ratepay can match the payment to the transaction.
* `resultCode`: Use this to [present the payment](#present-the-payment-result) result to your shopper.
* `pspReference`: Our unique reference for the payment.
* `merchantReference`: Your `reference` from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request.

**/payments response**

```json
{
  "additionalData": {
        "openinvoicedata.descriptor": "DN0099661Y8"
    },
  "pspReference":"881567437271705K",
  "resultCode":"Authorised",
  "merchantReference":"YOUR_ORDER_NUMBER"
}
```

## Present the payment result

Use the  [resultCode](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-resultCode) that you received in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response to present the payment result to your shopper.

The `resultCode` values you can receive for Ratepay are:

| resultCode     | Description                              | Action to take                                                                                                                                                                                                                                            |
| -------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorised** | The payment was successfully authorised. | Inform the shopper that the payment was successful. You can also add a message, for example: *Thank you for your order. Your purchase order number is XYZ.* After the goods have been sent, you also need to [capture](#capture-the-payment) the payment. |
| **Cancelled**  | The shopper cancelled the payment.       | Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.                                                                                                                                           |
| **Refused**    | The payment was refused by Ratepay.      | Ask the shopper to try the payment again using a different payment method.                                                                                                                                                                                |

## Capture the payment

This section only applies to Ratepay Open invoice.

After the goods have been sent, you also need to [capture](#capture-the-payment) the payment. All Ratepay Open invoice payments must be [manually captured](/online-payments/capture#manual-capture), even if you have enabled automatic capture for other payment methods. Capturing the payment is what triggers the invoice to be sent to the shopper.

### Partial captures

To [partially capture](/online-payments/capture) a Ratepay Open invoice payment, specify in your [/capture](https://docs.adyen.com/api-explorer/#/Payment/capture) request:

* `modificationAmount`: The amount that the shopper should pay. 
* `additionalData.openinvoicedata`: Price and product information for the items that the shopper should pay for.

Although the field names are different, the information in `additionalData.openinvoicedata` is the same as what you provided in `lineItems` when making a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request:

| openinvoicedata     | lineItems            | Description                                                                                       |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| `itemAmount`        | `amountExcludingTax` | The price for one item, without the tax, in [minor units](/development-resources/currency-codes). |
| `itemVatAmount`     | `taxAmount`          | The tax amount for one item, in minor units.                                                      |
| `itemVatPercentage` | `taxPercentage`      | The tax percentage, in minor units.                                                               |

The following example shows how to make a partial capture request if the shopper only kept one pair of socks from the two included in the [original payment request](#make-a-payment).

**/capture request**

```json
{
   "originalReference":"COPY_PSP_REFERENCE_FROM_AUTHORISE_RESPONSE",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "modificationAmount":{
      "currency":"EUR",
      "value":"700"
   },
   "additionalData":{
      "openinvoicedata.numberOfLines":"2",
      "openinvoicedata.line1.currencyCode":"EUR",
      "openinvoicedata.line1.description":"Shoes",
      "openinvoicedata.line1.itemAmount":"331",
      "openinvoicedata.line1.itemVatAmount":"69",
      "openinvoicedata.line1.itemVatPercentage":"2100",
      "openinvoicedata.line1.numberOfItems":"1",
      "openinvoicedata.line1.vatCategory":"High",
      "openinvoicedata.line1.itemId":"Item #1",
      "openinvoicedata.line2.currencyCode":"EUR",
      "openinvoicedata.line2.description":"Socks",
      "openinvoicedata.line2.itemAmount":"248",
      "openinvoicedata.line2.itemVatAmount":"52",
      "openinvoicedata.line2.itemVatPercentage":"2100",
      "openinvoicedata.line2.numberOfItems":"1",
      "openinvoicedata.line2.vatCategory":"High",
      "openinvoicedata.line2.itemId":"Item #2",
   },
   "reference":"YOUR_CAPTURE_REFERENCE"
}
```

Any unclaimed amount that is left after partially capturing a payment should be [manually cancelled](#refunds-and-cancellations).

To set up multiple partial captures, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). Multiple partial captures will create a new invoice for each capture.

## Refunds and cancellations

If a Ratepay payment has not yet been captured, you can [cancel](/online-payments/cancel) it. If the Ratepay payment has already been captured and you want to return the funds to the shopper, you need to [refund](/online-payments/refund) it.

### Partial refunds

To [partially refund](/online-payments/refund) a Ratepay payment, specify in your [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request:

* `modificationAmount`: The amount to be refunded to the shopper.
* `additionalData.acquirerReference`: The `acquirerReference` of the capture. This is needed if there are multiple partial captures available for the payment. When refunding in your [Customer Area](https://ca-test.adyen.com/), you can add the `acquirerReference` manually as well.
* (Only for Open invoice payments)`additionalData.openinvoicedata`: Price and product information about the returned items.

Although the field names are different, the information in `additionalData.openinvoicedata` is the same as what you provided in `lineItems` when making a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request:

| openinvoicedata     | lineItems            | Description                                                                                       |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| `itemAmount`        | `amountExcludingTax` | The price for one item, without the tax, in [minor units](/development-resources/currency-codes). |
| `itemVatAmount`     | `taxAmount`          | The tax amount for one item, in minor units.                                                      |
| `itemVatPercentage` | `taxPercentage`      | The tax percentage, in minor units.                                                               |

The following example shows how to make a partial refund request if the shopper returned the shoes included in the [original payment request](#make-a-payment).

**/refund request**

```json
{
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "originalReference":"COPY_PSP_REFERENCE_FROM_AUTHORISE_RESPONSE",
   "modificationAmount":{
      "currency":"EUR",
      "value":"400"
   },
   "additionalData":{
      "openinvoicedata.numberOfLines":"1",
      "openinvoicedata.line1.currencyCode":"EUR",
      "openinvoicedata.line1.description":"Shoes",
      "openinvoicedata.line1.itemAmount":"331",
      "openinvoicedata.line1.itemVatAmount":"69",
      "openinvoicedata.line1.itemVatPercentage":"2100",
      "openinvoicedata.line1.numberOfItems":"1",
      "openinvoicedata.line1.vatCategory":"High"
   },
   "reference":"YOUR_REFUND_REFERENCE"
}
```

## Test and go live

Before you can accept live Ratepay payments, you need to [submit a request for Ratepay](/payment-methods/add-payment-methods) in your [live Customer Area](https://ca-live.adyen.com/), and provide us your Ratepay live credentials.

Ratepay provides detailed [error codes](https://docs.ratepay.com/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/overview_result_codes/) as well as [test data](https://docs.ratepay.com/docs/developer/testing/test_data/) and recommendations on how to test some of the [most common scenarios](https://docs.ratepay.com/docs/developer/testing/test_cases/direct_api_integration/).

You can check the status of the test payments in your [Customer Area](https://ca-test.adyen.com/) > **Transactions** > **Payments**.

## See also

* [API only integration guide](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=API%20only)
* [API Explorer](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview)
