---
title: "Payout With FX"
source_url: https://docs.rapyd.net/en/payout-with-fx.html
lang: en
---

# Payout With FX

Pay your employees in the right currency. | `Enterprise`

Rapyd makes it easy for employers to pay their employees in a foreign currency. The employer has the option of confirming the [FX](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_fx "Foreign exchange") rate before the payout is completed.

Common use cases may include:

- A gig-platform pays a worker's overseas bank in their preferred currency for a completed project
- Your company begins hiring workers across borders and offers to pay in their currency

> **Note:**
>
> In the current example, we are showing an FX payout with a fixed [beneficiary](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_beneficiary "Beneficiary") amount. The Rapyd payout API also supports fixing the sender (Debit) amount.
>
> For example, the sender wants to pay 1000 USD and the beneficiary will get the equivalent amount of BGN (Bulgarian Lev), based on the current FX rate.

**Note**: To complete the payout with FX without requiring the second API call, you can set `confirm_automatically` to **true**.

### Payout With FX Workflow

Your gig-platform uses the Client Wallet, which is in USD (U.S. Dollars). One of the workers lives in Bulgaria and needs to be paid in BGN (Bulgarian Lev).

![payout-with-fx.jpg](image/img-edd475eed6767e8bd2e731eae2a6e743.jpg)

1. You request a salary payout from your wallet USD account to the employee's BGN bank account with [Create Payout](https://docs.rapyd.net/en/create-payout.md "Create Payout").
2. Rapyd processes the request and sends you the exchange rate.
3. You confirm the exchange rate with [Confirm Payout with FX](https://docs.rapyd.net/en/confirm-payout-with-fx.md "Confirm Payout with FX").
4. Rapyd processes the payout to the employees's bank account and sends you a response.
5. You receive the payout confirmation. When the bank confirms receipt of the funds, you also receive a webhook.

### Payout With FX Message Sequences

The message sequence diagrams below describe how information is exchanged between Rapyd, the merchant, and the beneficiary.

Create Payout With FX - Automatic Confirmation

![create-payout-with-automatic-confirmation-of-exchange-rate---success.svg](image/img-4d6c2f6c7557c3e7df3aa4d1e41b4e34.svg)

Create Payout With FX - Manual Confirmation

![create-payout-with-manual-confirmation-of-exchange-rate---success.svg](image/img-7791a4c3e3cf5652e044e09fe8db430a.svg)

### Payout With FX Statuses

The finite state diagram below summarizes the statuses for payouts with FX.

![payout.svg](image/img-0c4a34e85865b93674fa660b6d8192e8.svg)

Description of Statuses

| Status | Description |
| --- | --- |
| Created | The payout was created. |
| Pending | The payout is processing. The FX rate must be confirmed. |
| Confirmation | The beneficiary has received the payout funds. |
| Completed | The payout has been completed. The beneficiary has received the payout funds. |
| Canceled | The payout was canceled. |
| Error | The payout has not been created, or the payout has failed. |
| Expired | The payout has expired. |

### How Payout With FX Works

> **Note:**
>
> To run the examples of this use case, you must run the following API calls:
>
> - 'ewallet' - Run [Create Wallet](https://docs.rapyd.net/en/create-wallet.md "Create Wallet") for the wallet of the ride-sharing service. Use the 'id' you get in the response. For more information, see [Creating a Rapyd Wallet](https://docs.rapyd.net/en/creating-a-rapyd-wallet.md "Creating a Rapyd Wallet").
> - `payout_method_type` - Run [List Payout Method Types](https://docs.rapyd.net/en/list-payout-method-types.md "List Payout Method Types") to get the available payout method types for the country you want. In this example, we use Bulgaria (**BG**).
> - **Required fields** - Run [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields") to get the fields that are required for the beneficiary, the sender, and the payout itself. In this example, we use **bg_general_bank**.

**Note**: If no rate confirmation is required, you can perform the entire payout operation automatically. Set **automatic_confirmation** to true.

### Processing the Payout With FX

**Note**: You can check the current currency exchange rate with [Get FX Rate](https://docs.rapyd.net/en/get-fx-rate.md "Get FX Rate").

The payroll manager requests a payout in USD (U.S. Dollars) for sending 2000 BGN (Bulgarian Lev) to the employee's bank account.

For that, you use [Create Payout](https://docs.rapyd.net/en/create-payout.md "Create Payout") with the following parameters:

Description of Body Parameters

| Body Parameter | Description |
| --- | --- |
| beneficiary | Fill out the 'beneficiary' object with the following details:  `payment_type` - **priority**  `address` - **456 Second Street**  `city` - **Plovdiv**  `first_name` - **Test**  `last_name` - **Employee**  `iban` - **BG80BNBG96611020345678**  `bic_swift` - **BUINBGSF** |
| beneficiary_country | Enter **BG** as the country code of the beneficiary. |
| beneficiary_entity _type | Enter **individual** as the type of entity for the beneficiary. |
| confirm_automatically | Enter **false** to indicate that manual confirmation is required. |
| description | Enter **Salary** as the description. |
| ewallet | Enter the wallet 'id' that you received when you created the wallet in your sandbox. For purposes of this use case lesson, we are using **ewallet_82dd0417a86aebb564da2f96936ce2d2**, which is the ID of the wallet we created in our sandbox. |
| payout_amount | Enter **2000** as the amount of currency to buy, in units of the **buy_currency**. |
| payout_currency | Enter **BGN** as the payout currency. A three-letter ISO 4217 code for the currency to buy. |
| payout_method_type | Enter **bg_general_bank** as the method type. Use [List Payout Method Types](https://docs.rapyd.net/en/list-payout-method-types.md "List Payout Method Types") and [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields"). |
| sender | Fill out the 'sender' object with the following details:  `first name` - **Test**  `last_name` - **Manager**  `address` - **123 First Street**  `city` - **Sofia**  `date_of_birth` - **22/02/1980** |
| sender_country | Enter **BG** as the country code for Bulgaria. |
| sender_currency | Enter **USD** as the sender's currency. |
| sender_entity_type | Enter **company** as the sender entity type. |

### Create Payout

You ask Rapyd to process the payroll manager's payout of 2,000 BGN (Bulgarian Lev) to the employees bank account.

### Create Payout Request

- - Request

    - ```
      // Request URL: POST https://sandboxapi.rapyd.net/v1/payouts

      // Message body: 
      {
          "beneficiary": {
              "payment_type": "priority",
              "address": "456 Second Street",
              "city": "Plovdiv",
              "first_name": "Test",
              "last_name": "Employee",
              "iban": "DE3376599444263666923298",
              "bic_swift": "BUINBGSF"
          },
          "beneficiary_country": "BG",
          "beneficiary_entity_type": "individual",
          "confirm_automatically": false,
          "description": "Salary",
          "ewallet": "ewallet_82dd0417a86aebb564da2f96936ce2d2",
          "payout_amount": "2000",
          "payout_currency": "BGN",
          "payout_method_type": "bg_general_bank",
          "sender": {
              "first_name": "Test",
              "last_name": "Manager",
              "address": "123 First Street",
              "city": "Sofia",
              "date_of_birth": "22/02/1980"
          },
          "sender_country": "BG",
          "sender_currency": "USD",
          "sender_entity_type": "company"
      }
      ```
- - .NET Core

    - ```
      using System;
      using System.Text.Json;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      var requestObj = new
                      {
                          beneficiary = new
                          {
                              payment_type = "priority",
                              address = "456 Second Street",
                              city = "Plovdiv",
                              first_name = "John",
                              last_name = "Doe",
                              iban = "DE3376599444263666923298",
                              bic_swift = "BUINBGSF"
                          },
                          beneficiary_country = "BG",
                          beneficiary_entity_type = "individual",
                          confirm_automatically = false,
                          description = "Salary",
                          ewallet = "ewallet_82dd0417a86aebb564da2f96936ce2d2",
                          payout_amount = "2000",
                          payout_currency = "BGN",
                          payout_method_type = "bg_general_bank",
                          sender = new
                          {
                              first_name = "Jane",
                              last_name = "Doe",
                              address = "123 First Street",
                              city = "Sofia",
                              date_of_birth = "22/02/1980"
                          },
                          sender_country = "BG",
                          sender_currency = "USD",
                          sender_entity_type = "company"
                      };

                      string request = JsonSerializer.Serialize(requestObj);

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payouts", request);

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;
      async function main() {
        try {
          const body = {
            beneficiary: {
              payment_type: 'priority',
              address: '456 Second Street',
              city: 'Plovdiv',
              first_name: 'John',
              last_name: 'Doe',
              iban: 'DE3376599444263666923298',
              bic_swift: 'BUINBGSF'
            },
            beneficiary_country: 'BG',
            beneficiary_entity_type: 'individual',
            confirm_automatically: false,
            description: 'Salary',
            ewallet: 'ewallet_82dd0417a86aebb564da2f96936ce2d2',
            payout_amount: '2000',
            payout_currency: 'BGN',
            payout_method_type: 'bg_general_bank',
            sender: {
              first_name: 'Jane',
              last_name: 'Doe',
              address: '123 First Street',
              city: 'Sofia',
              date_of_birth: '22/02/1980'
            },
            sender_country: 'BG',
            sender_currency: 'USD',
            sender_entity_type: 'company'
          };
          const result = await makeRequest('POST', '/v1/payouts', body);
          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```
      <?php

      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      $body = [
          "beneficiary" => array(
              "payment_type" => "priority",
              "address" => "456 Second Street",
              "city" => "Plovdiv",
              "first_name" => "John",
              "last_name" => "Doe",
              "iban" => "DE3376599444263666923298",
              "bic_swift" => "BUINBGSF"
          ),
          "beneficiary_country" => "BG",
          "beneficiary_entity_type" => "individual",
          "confirm_automatically" => false,
          "description" => "Salary",
          "ewallet" => "ewallet_82dd0417a86aebb564da2f96936ce2d2",
          "payout_amount" => "2000",
          "payout_currency" => "BGN",
          "payout_method_type" => "bg_general_bank",
          "sender" => array(
              "first_name" => "Jane",
              "last_name" => "Doe",
              "address" => "123 First Street",
              "city" => "Sofia",
              "date_of_birth" => "22/02/1980"
          ),
          "sender_country" => "BG",
          "sender_currency" => "USD",
          "sender_entity_type" => "company"
      ];

      try {
          $object = make_request('post', '/v1/payouts', $body);
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      beneficiary_fields = {
          "payment_type": "priority",
          "address": "456 Second Street",
          "city": "Plovdiv",
          "first_name": "John",
          "last_name": "Doe",
          "iban": "DE3376599444263666923298",
          "bic_swift": "BUINBGSF"
      }

      sender_fields = {
          "first_name": "Jane",
          "last_name": "Doe",
          "address": "123 First Street",
          "city": "Sofia",
          "date_of_birth": "22/02/1980"
      }

      payout_body = {
          "beneficiary": beneficiary_fields,
          "beneficiary_country": "BG",
          "beneficiary_entity_type": "individual",
          "confirm_automatically": False,
          "description": "Salary",
          "ewallet": "ewallet_82dd0417a86aebb564da2f96936ce2d2",
          "payout_amount": "2000",
          "payout_currency": "BGN",
          "payout_method_type": "bg_general_bank",
          "sender": sender_fields,
          "sender_country": "BG",
          "sender_currency": "USD",
          "sender_entity_type": "company"
      }
      result = make_request(method='post', path='/v1/payouts', body=payout_body)
      pprint(result)
      ```

### Create Payout Response

Let's take a look at the response.

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "77745716-89fc-4313-abbe-162a4d25f12f"
          },
          "data": {
              "id": "payout_56010c333d71789b6110fd36bc5066ca",
              "payout_type": "bank",
              "payout_method_type": "bg_general_bank",
              "amount": 2000,
              "payout_currency": "BGN",
              "sender_amount": 1191.1,
              "sender_currency": "USD",
              "status": "Confirmation",
              "sender_country": "BG",
              "sender": {
                  "last_name": "Manager",
                  "first_name": "Test",
                  "country": "BG",
                  "entity_type": "company",
                  "address": "123 First Street",
                  "name": "Test Manager",
                  "date_of_birth": "22/02/1980",
                  "city": "Sofia",
                  "currency": "USD"
              },
              "beneficiary_country": "BG",
              "beneficiary": {
                  "last_name": "Employee",
                  "first_name": "Test",
                  "country": "BG",
                  "entity_type": "individual",
                  "address": "456 Second Street",
                  "name": "Test Employee",
                  "city": "Plovdiv",
                  "currency": "BGN",
                  "bic_swift": "BUINBGSF",
                  "iban": "DE3376599444263666923298",
                  "payment_type": "priority"
              },
              "fx_rate": 0.59555,
              "instructions": {
                        
      //              ...       
                
              },
              "ewallets": [
                  {
                      "ewallet_id": "ewallet_82dd0417a86aebb564da2f96936ce2d2",
                      "amount": 1191.1,
                      "percent": 100
                  }
              ],
              "metadata": {},
              "description": "Salary"
                
      //              ...       
                
         }
      }
      ```

The `data` section of this response shows:

- The `id` of the 'payout' object is **payout_56010c333d71789b6110fd36bc5066ca**. When you run this example in your own sandbox, you will get a different ID, which you will need for a later step in this use case.
- The `fx_rate` is **0.59555**.

### Confirm Payout

When you receive the response, you have a short time to approve the exchange rate. The exact amount of time varies from payout method to payout method.

### Confirm Payout Request

To confirm the payout, use [Confirm Payout with FX](https://docs.rapyd.net/en/confirm-payout-with-fx.md "Confirm Payout with FX") with the following parameters:

Description of Path Parameters

| Path Parameter | Description |
| --- | --- |
| Payout ID | Enter the payout 'id' that you received when you created the payout in your sandbox. For purposes of this use case lesson, we are using **payout_56010c333d71789b6110fd36bc5066ca**, which is the ID of the payout we created in our sandbox. |

- - Request

    - ```
      // Request URL: POST https://sandboxapi.rapyd.net/v1/payouts/confirm/payout_56010c333d71789b6110fd36bc5066ca

      // Message body absent.
      ```
- - .NET Core

    - ```
      using System;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {

                      string payout = "payout_56010c333d71789b6110fd36bc5066ca";

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/payouts/confirm/{payout}");

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const body = {};
          const result = await makeRequest(
            'POST',
            '/v1/payouts/confirm/payout_56010c333d71789b6110fd36bc5066ca',
            body
          );
          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```
      <?php

      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);

      try {
          $object = make_request('post', '/v1/payouts/confirm/payout_56010c333d71789b6110fd36bc5066ca');
          var_dump($object);
      } catch (Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```
      from pprint import pprint

      from utilities import make_request

      payout = 'payout_56010c333d71789b6110fd36bc5066ca'
      results = make_request(method='post',
                             path=f'/v1/payouts/confirm/{payout}')
      pprint(results)
      ```

### Confirm Payout Response

Let's take a look at the response.

- - Response

    - ```
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "bb05d0a9-295d-4cad-958c-e20dd8dbe461"
          },
          "data": {
              "id": "payout_89a8df5e8716b9785f4f1de42e453bac",
              "payout_type": "bank",
              "payout_method_type": "bg_general_bank",
              "amount": 2000,
              "payout_currency": "BGN",
              "sender_amount": 1191.1,
              "sender_currency": "USD",
              "status": "Created",
              "sender_country": "BG",
              "sender": {
                  "id": "sender_4bc400c5c08fd6e6d4655d5ddef73e4e",
                  "last_name": "Manager",
                  "first_name": "Test",
                  "country": "BG",
                  "entity_type": "company",
                  "address": "123 First Street",
                  "name": "Test Manager",
                  "date_of_birth": "22/02/1980",
                  "city": "Sofia",
                  "currency": "USD"
              },
              "beneficiary_country": "BG",
              "beneficiary": {
                  "id": "beneficiary_97f8a3c6955967280a11223f7c3114ca",
                  "last_name": "Employee",
                  "first_name": "Test",
                  "country": "BG",
                  "entity_type": "individual",
                  "address": "456 Second Street",
                  "name": "Test Employee",
                  "city": "Plovdiv",
                  "currency": "BGN",
                  "bank_name": "Test Employee",
                  "bic_swift": "BUINBGSF",
                  "iban": "DE3376599444263666923298",
                  "payment_type": "priority"
              },
              "fx_rate": 0.59555,
              "instructions": {
                
      //              ...       
                
                 }
              ],
              "ewallets": [
                  {
                      "ewallet_id": "ewallet_82dd0417a86aebb564da2f96936ce2d2",
                      "amount": 1191.1,
                      "percent": 100
                  }
              ],
              "metadata": {},
              "description": "Salary",
              "created_at": 1583676917,
                
      //              ...       
                
          }
      }
      ```

The `data` section of this response shows:

- `status` - **Created** - This indicates that the payout process has begun.
- `amount` - The amount of money that will be transferred into the employee's bank account, **2000 BGN**.
- `payout_currency` - The currency sent to the employee's bank account, **BGN**.
- `sender_currency` - The currency of your eWallet account, **USD**.
- `created at` - The time the payout was created, in Unix time.

The `ewallets` object shows the following information:

- `ewallet_id` - The ID of your company wallet.
- `amount` - The amount of **USD** taken from your wallet, **1191.10 USD**.

### Closing the Transaction

> **Note:**
>
> The [sandbox](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_sandbox "Sandbox") does not directly simulate the action of the beneficiary receiving the payout funds. You can simulate this action with the procedure described in [Complete Payout](https://docs.rapyd.net/en/complete-payout.md "Complete Payout"). For this, you will need the payout ID and payout amount that you generated in your sandbox.
>
> When a payout completion is simulated, Rapyd sends a webhook. Configure your system to receive webhooks with the procedure described in [Defining a Webhook Endpoint](https://docs.rapyd.net/en/defining-a-webhook-endpoint.md "Defining a Webhook Endpoint")

After you simulate that the employee's bank finalizes receipt of his salary, Rapyd sends you [Webhook - Payout Completed](https://docs.rapyd.net/en/payout-completed-webhook.md "Payout Completed Webhook"). To indicate that the payout was completed, the `status` field changes to **Completed**.

> **Note:**
>
> Want to see the Rapyd API methods and objects that you'll use? Visit the [Merchant API Reference](https://docs.rapyd.net/en/merchant-api-reference.md "Merchant API Reference") for more technical details.