---
title: "Book the remainder to your platform"
description: "Learn how to convert the currency of a refund and book the remainder to your platform."
url: "https://docs.adyen.com/marketplaces/currency-conversion/refunds/your-platform"
source_url: "https://docs.adyen.com/marketplaces/currency-conversion/refunds/your-platform.md"
canonical: "https://docs.adyen.com/marketplaces/currency-conversion/refunds/your-platform"
last_modified: "2023-02-10T14:17:00+01:00"
language: "en"
---

# Book the remainder to your platform

Learn how to convert the currency of a refund and book the remainder to your platform.

[View source](/marketplaces/currency-conversion/refunds/your-platform.md)

**Limited availability**\
Currency conversion in currently in pilot phase. Some of the processes and documentation may change as the feature evolves. If you are interested in piloting currency conversion or have any feedback, reach out to your Adyen contact.

***

When you refund a payment with currency conversion, the refund amounts may not match the amounts in the original payment request, resulting in a remainder. For example, your user sold goods worth CZK 1000.00 to a customer who paid in PLN (PLN 201.74). Later, your user refunds the CZK 1000.00 to the customer, which results in a remainder of PLN 6.31. You can choose to book this remainder to your marketplace.

When you book the remainder amount to the customer:

* Your user is debited the exact amount they received in the payment.
* The customer is credited the exact amount they originally paid.
* The balance from the remainder is booked to your liable balance account.

## Requirements

| Requirement                                                          | Description                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                                 | You must have an Adyen [online payments integration and a checkout UI](/online-payments/build-your-integration).                                                                                                                                                                                                                                |
| **[API credentials](/development-resources/api-credentials)**        | You must have credentials for the following API:- [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview) (format: **ws\@Company.\[YourCompanyAccount]**)                                                                                                                                                                  |
| **[Webhooks](/development-resources/webhooks)**                      | Ensure that your server can receive and accept [standard webhooks](/development-resources/webhooks). Subscribe to any of the following webhooks:- [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview)
- [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) |
| **[Capabilities](/marketplaces/verification-overview/capabilities)** | Make sure that your account holders have the following capabilities:- **receivePayments**
- **receiveFromPlatformPayments**
- **sendToTransferInstrument**                                                                                                                                                                                      |
| **Setup steps**                                                      | Before you begin:- Ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to configure the required currencies for your merchant account.
- Your payment must be captured before you can initiate the refund.                                                                                               |

## How it works

You process a payment with currency conversion on behalf of your user. The customer is debited in the processing currency and your user is credited in the settlement currency. When refunding this payment, you want to book the remainder to your platform. To do this:

1. You send a refund request, specifying the original payment amounts in both currencies.
2. When Adyen receives the request, we credit the customer and debit your user in their respective currencies. Any remainder is booked to your liable balance account.

## Send a refund request

To book the remainder to your marketplace's liable balance account:

1. Make sure that you have the API key for the Checkout API. Your credential has the format **ws\@Company.\[YourCompanyAccount]**.

2. Send a POST [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request.

   * Use the values from the original payment for the [amount](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-amount) and [splits.amount](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-splits-amount) objects of the request. For our example refund, this is PLN 201.74 as the `amount` and CZK 1000.00 as the `splits.amount`.
   * In the splits array, add another split item for the remainder, with type **Remainder**. Enter your liable balance account ID in the [account](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds#request-splits-account) field of this split item. You do not need to specify the amount of the remainder.

   **Refund request where the remainder is booked to your marketplace**

   #### curl

   ```bash
   curl https://checkout-test.adyen.com/v72/payments/{paymentPspReference}/refunds \
   -H 'x-api-key: ADYEN_API_KEY' \
   -H 'content-type: application/json' \
   -X POST \
   -d '{
       "amount":{
           "value":20174,
           "currency":"PLN"
       },
       "reference":"YOUR_REFUND_REFERENCE",
       "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
       "splits":[
           {
               "amount":{
                   "value":100000,
                   "currency":"CZK"
               },
               "type":"BalanceAccount",
               "account":"BA00000000000000000000001",
               "reference":"YOUR_SPLIT_REFERENCE",
               "description":"YOUR_SPLIT_DESCRIPTION"
           },
           {
               "type":"Remainder",
               "account":"YOUR_LIABLE_ACCOUNT_ID",
               "reference":"YOUR_REMAINDER_REFERENCE",
               "description":"YOUR_REMAINDER_DESCRIPTION"
           }
       ]
   }'
   ```

   #### Java

   ```java
   // Adyen Java API Library v40.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, also include your liveEndpointUrlPrefix.
   Client client = new Client("ADYEN_API_KEY", Environment.TEST);

   // Create the request object(s)
   SplitAmount splitAmount1 = new SplitAmount()
     .currency("CZK")
     .value(100000L);

   Amount amount = new Amount()
     .currency("PLN")
     .value(20174L);

   Split split1 = new Split()
     .reference("YOUR_SPLIT_REFERENCE")
     .amount(splitAmount1)
     .description("YOUR_SPLIT_DESCRIPTION")
     .type(Split.TypeEnum.BALANCEACCOUNT)
     .account("BA00000000000000000000001");

   Split split2 = new Split()
     .reference("YOUR_REMAINDER_REFERENCE")
     .description("YOUR_REMAINDER_DESCRIPTION")
     .type(Split.TypeEnum.REMAINDER)
     .account("YOUR_LIABLE_ACCOUNT_ID");

   PaymentRefundRequest paymentRefundRequest = new PaymentRefundRequest()
     .reference("YOUR_REFUND_REFERENCE")
     .amount(amount)
     .splits(Arrays.asList(split1, split2))
     .merchantAccount("YOUR_MERCHANT_ACCOUNT");

   // Send the request
   ModificationsApi service = new ModificationsApi(client);
   PaymentRefundResponse response = service.refundCapturedPayment("paymentPspReference", paymentRefundRequest, new RequestOptions().idempotencyKey("UUID"));
   ```

   #### PHP

   ```php
   <?php
   // Adyen PHP API Library v28.3.0
   use Adyen\Client;
   use Adyen\Environment;
   use Adyen\Model\Checkout\Amount;
   use Adyen\Model\Checkout\Split;
   use Adyen\Model\Checkout\SplitAmount;
   use Adyen\Model\Checkout\PaymentRefundRequest;
   use Adyen\Service\Checkout\ModificationsApi;

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


   // Create the request object(s)
   $splitAmount1 = new SplitAmount();
   $splitAmount1
     ->setCurrency("CZK")
     ->setValue(100000);

   $amount = new Amount();
   $amount
     ->setCurrency("PLN")
     ->setValue(20174);

   $split1 = new Split();
   $split1
     ->setReference("YOUR_SPLIT_REFERENCE")
     ->setAmount($splitAmount1)
     ->setDescription("YOUR_SPLIT_DESCRIPTION")
     ->setType("BalanceAccount")
     ->setAccount("BA00000000000000000000001");

   $split2 = new Split();
   $split2
     ->setReference("YOUR_REMAINDER_REFERENCE")
     ->setDescription("YOUR_REMAINDER_DESCRIPTION")
     ->setType("Remainder")
     ->setAccount("YOUR_LIABLE_ACCOUNT_ID");

   $paymentRefundRequest = new PaymentRefundRequest();
   $paymentRefundRequest
     ->setReference("YOUR_REFUND_REFERENCE")
     ->setAmount($amount)
     ->setSplits(array($split1, $split2))
     ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT");

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

   // Send the request
   $service = new ModificationsApi($client);
   $response = $service->refundCapturedPayment('paymentPspReference', $paymentRefundRequest, $requestOptions);
   ```

   #### C\#

   ```cs
   // Adyen .NET API Library v32.2.1
   using Adyen;
   using Environment = Adyen.Model.Environment;
   using Adyen.Model;
   using Adyen.Model.Checkout;
   using Adyen.Service.Checkout;

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

   // Create the request object(s)
   SplitAmount splitAmount1 = new SplitAmount
   {
     Currency = "CZK",
     Value = 100000
   };

   Amount amount = new Amount
   {
     Currency = "PLN",
     Value = 20174
   };

   Split split1 = new Split
   {
     Reference = "YOUR_SPLIT_REFERENCE",
     Amount = splitAmount1,
     Description = "YOUR_SPLIT_DESCRIPTION",
     Type = Split.TypeEnum.BalanceAccount,
     Account = "BA00000000000000000000001"
   };

   Split split2 = new Split
   {
     Reference = "YOUR_REMAINDER_REFERENCE",
     Description = "YOUR_REMAINDER_DESCRIPTION",
     Type = Split.TypeEnum.Remainder,
     Account = "YOUR_LIABLE_ACCOUNT_ID"
   };

   PaymentRefundRequest paymentRefundRequest = new PaymentRefundRequest
   {
     Reference = "YOUR_REFUND_REFERENCE",
     Amount = amount,
     Splits = new List<Split>{ split1, split2 },
     MerchantAccount = "YOUR_MERCHANT_ACCOUNT"
   };

   // Send the request
   var service = new ModificationsService(client);
   var response = service.RefundCapturedPayment("paymentPspReference", paymentRefundRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
   ```

   #### NodeJS (JavaScript)

   ```js
   // Adyen Node API Library v30.0.0
   const { Client, CheckoutAPI } = require('@adyen/api-library');

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   const config = new Config({
     apiKey: "ADYEN_API_KEY",
     environment: EnvironmentEnum.TEST
   });

   const client = new Client(config);

   // Create the request object(s)
   const paymentRefundRequest = {
     amount: {
       value: 20174,
       currency: "PLN"
     },
     reference: "YOUR_REFUND_REFERENCE",
     merchantAccount: "YOUR_MERCHANT_ACCOUNT",
     splits: [ {
       amount: {
         value: 100000,
         currency: "CZK"
       },
       type: "BalanceAccount",
       account: "BA00000000000000000000001",
       reference: "YOUR_SPLIT_REFERENCE",
       description: "YOUR_SPLIT_DESCRIPTION"
     }, {
       type: "Remainder",
       account: "YOUR_LIABLE_ACCOUNT_ID",
       reference: "YOUR_REMAINDER_REFERENCE",
       description: "YOUR_REMAINDER_DESCRIPTION"
     } ]
   }

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.ModificationsApi.refundCapturedPayment("paymentPspReference", paymentRefundRequest, { idempotencyKey: "UUID" });
   ```

   #### Go

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

   // Create the request object(s)
   splitAmount1 := checkout.SplitAmount{
     Currency: common.PtrString("CZK"),
     Value: 100000,
   }

   amount := checkout.Amount{
     Currency: "PLN",
     Value: 20174,
   }

   split1 := checkout.Split{
     Reference: common.PtrString("YOUR_SPLIT_REFERENCE"),
     Amount: &splitAmount1,
     Description: common.PtrString("YOUR_SPLIT_DESCRIPTION"),
     Type: "BalanceAccount",
     Account: common.PtrString("BA00000000000000000000001"),
   }

   split2 := checkout.Split{
     Reference: common.PtrString("YOUR_REMAINDER_REFERENCE"),
     Description: common.PtrString("YOUR_REMAINDER_DESCRIPTION"),
     Type: "Remainder",
     Account: common.PtrString("YOUR_LIABLE_ACCOUNT_ID"),
   }

   paymentRefundRequest := checkout.PaymentRefundRequest{
     Reference: common.PtrString("YOUR_REFUND_REFERENCE"),
     Amount: amount,
     Splits: []checkout.Split{
         split1, split2,
     },
     MerchantAccount: "YOUR_MERCHANT_ACCOUNT",
   }

   // Send the request
   service := client.Checkout()
   req := service.ModificationsApi.RefundCapturedPaymentInput("paymentPspReference").IdempotencyKey("UUID").PaymentRefundRequest(paymentRefundRequest)
   res, httpRes, err := service.ModificationsApi.RefundCapturedPayment(context.Background(), req)
   ```

   #### Python

   ```py
   # Adyen Python API Library v14.0.0
   import Adyen

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

   # Create the request object(s)
   json_request = {
     "amount": {
       "value": 20174,
       "currency": "PLN"
     },
     "reference": "YOUR_REFUND_REFERENCE",
     "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
     "splits": [ {
       "amount": {
         "value": 100000,
         "currency": "CZK"
       },
       "type": "BalanceAccount",
       "account": "BA00000000000000000000001",
       "reference": "YOUR_SPLIT_REFERENCE",
       "description": "YOUR_SPLIT_DESCRIPTION"
     }, {
       "type": "Remainder",
       "account": "YOUR_LIABLE_ACCOUNT_ID",
       "reference": "YOUR_REMAINDER_REFERENCE",
       "description": "YOUR_REMAINDER_DESCRIPTION"
     } ]
   }

   # Send the request
   result = adyen.checkout.modifications_api.refund_captured_payment(request=json_request, paymentPspReference="paymentPspReference", idempotency_key="UUID")
   ```

   #### Ruby

   ```rb
   # Adyen Ruby API Library v11.0.0
   require "adyen-ruby-api-library"

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

   # Create the request object(s)
   request_body = {
     :amount => {
       :value => 20174,
       :currency => 'PLN'
     },
     :reference => 'YOUR_REFUND_REFERENCE',
     :merchantAccount => 'YOUR_MERCHANT_ACCOUNT',
     :splits => [ {
       :amount => {
         :value => 100000,
         :currency => 'CZK'
       },
       :type => 'BalanceAccount',
       :account => 'BA00000000000000000000001',
       :reference => 'YOUR_SPLIT_REFERENCE',
       :description => 'YOUR_SPLIT_DESCRIPTION'
     }, {
       :type => 'Remainder',
       :account => 'YOUR_LIABLE_ACCOUNT_ID',
       :reference => 'YOUR_REMAINDER_REFERENCE',
       :description => 'YOUR_REMAINDER_DESCRIPTION'
     } ]
   }

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

   #### NodeJS (TypeScript)

   ```ts
   // Adyen Node API Library v30.0.0
   import { Client, CheckoutAPI, Types } from "@adyen/api-library";

   // For the LIVE environment, also include your liveEndpointUrlPrefix.
   const config = new Config({
     apiKey: "ADYEN_API_KEY",
     environment: EnvironmentEnum.TEST
   });

   const client = new Client(config);

   // Create the request object(s)
   const splitAmount1: Types.checkout.SplitAmount = {
     currency: "CZK",
     value: 100000
   };

   const amount: Types.checkout.Amount = {
     currency: "PLN",
     value: 20174
   };

   const split1: Types.checkout.Split = {
     reference: "YOUR_SPLIT_REFERENCE",
     amount: splitAmount1,
     description: "YOUR_SPLIT_DESCRIPTION",
     type: Types.checkout.Split.TypeEnum.BalanceAccount,
     account: "BA00000000000000000000001"
   };

   const split2: Types.checkout.Split = {
     reference: "YOUR_REMAINDER_REFERENCE",
     description: "YOUR_REMAINDER_DESCRIPTION",
     type: Types.checkout.Split.TypeEnum.Remainder,
     account: "YOUR_LIABLE_ACCOUNT_ID"
   };

   const paymentRefundRequest: Types.checkout.PaymentRefundRequest = {
     reference: "YOUR_REFUND_REFERENCE",
     amount: amount,
     splits: [split1, split2],
     merchantAccount: "YOUR_MERCHANT_ACCOUNT"
   };

   // Send the request
   const checkoutAPI = new CheckoutAPI(client);
   const response = checkoutAPI.ModificationsApi.refundCapturedPayment("paymentPspReference", paymentRefundRequest, { idempotencyKey: "UUID" });
   ```

3. You receive the following response:

   **Response**

   ```json
   {
      "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
      "paymentPspReference":"MNTQFKBDG3RZNN82",
      "pspReference":"NZK8QPBDG3RZNN82",
      "reference":"YOUR_REFUND_REFERENCE",
      "status":"received",
      "amount":{
         "currency":"PLN",
         "value":20174
      },
      "splits":[
         {
            "account":"BA00000000000000000000001",
            "amount":{
               "currency":"CZK",
               "value":100000
            },
            "description":"YOUR_SPLIT_DESCRIPTION",
            "reference":"YOUR_SPLIT_REFERENCE",
            "type":"BalanceAccount"
         },
         {
            "account":"YOUR_LIABLE_ACCOUNT_ID",
            "description":"YOUR_REMAINDER_DESCRIPTION",
            "reference":"YOUR_REMAINDER_REFERENCE",
            "type":"Remainder"
         }
      ]
   }
   ```