Setting up Currency and Payment Protocol options for Pay-out

The currencyOptions object within the Create Payment payload, allows merchants to specify which currencies and associated protocols are available for the end user to receive payment. This object is not mandatory; however, if provided, it restricts the currencies and protocols that can be used for the transaction.

If currencyOptions is not specified, the end user will have the option to claim the payment in any of the 16 available currencies supported by our platform. A full list of supported currencies and protocols can be found at Supported Currencies API.

Example of the full JSON request payload:

{
  "merchantId": "MERCHANT_SETTLE_MID_WALLET",
  "amount": 2.0,
  "currency": "ETH",
  "reference": "REF777579",
  "type": "OUT",
  "returnUrl": "https://app.deel.training//transaction-history",
  "customerId": "1289702",
  "flow": "PAYROLL",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.2",
    "partyDetails": [
      {
        "type": "BENEFICIARY",
        "name": "John Marion Hardy Doe",
        "entityType": "INDIVIDUAL",
        "dateOfBirth": "1983-09-23"
      }
    ]
  },
  "currencyOptions": [
    {
      "code": "ETH",
      "protocols": [
  
      ]
    },
    {
      "code": "USDT",
      "protocols": [
        "ERC20",
        "TRC20"
      ]
    }
  ]
}

Detailed Field Explanation

Structure:

"currencyOptions": [
  {
    "code": "Currency code",
    "protocols": ["List of protocols"]
  }
]

The table below outlines and explains the attributes within the complianceDetails object specifically related to the beneficiary data, including examples for a better understanding:

Field	Description	Type	Mandatory	Example
`code`	The currency code. This is a string representing the cryptocurrency code (e.g., "ETH", "USDT").	string	Yes	ETH
`protocols`	An array of strings specifying the protocols supported for the specified currency. If this array is empty, all available protocols for that currency will be used. If the array contains one or more protocols, only those specified will be available for the transaction.	string	No	ERC20, TRC20

Payload Examples

Example of limiting the PayOut currencies and protocols

Below is an example of a currencyOptions object limiting the transaction to ETH and USDT (ERC20 protocol only):

"currencyOptions": [
  {
    "code": "ETH",
    "protocols": []
  },
  {
    "code": "USDT",
    "protocols": ["ERC20"]
  }
]

Example with Currency Options but No Specific Protocols

This example illustrates how to include the currencyOptions object in your payload to specify which currencies can be used for the payout, without limiting the protocols for those currencies.

When the protocols array is left empty for a currency, it signifies that all available protocols for that currency are permitted. This approach allows merchants to restrict payouts to certain currencies while still offering flexibility in the choice of protocols.

{
  "currencyOptions": [
    {
      "code": "ETH",
      "protocols": []
    },
    {
      "code": "USDT",
      "protocols": []
    }
  ]
}

Example without Specified Currency and Protocol Preferences

Below is an example payload for creating a payout without specifying the currencyOptions object. In this scenario, the end user will have the option to receive the payment in any of the supported currencies, along with any available protocols for those currencies.

This flexibility allows for a broader choice for the recipient but can be limited by providing the currencyOptions object, as detailed in the Configuring Currency and Protocol Preferences on PayOut section.

{
  "merchantId": "MERCHANT_SETTLE_MID_WALLET",
  "amount": 2.0,
  "currency": "ETH",
  "reference": "REF777579",
  "type": "OUT",
  "returnUrl": "https://app.deel.training//transaction-history",
  "customerId": "1289702",
  "flow": "PAYROLL",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.2",
    "partyDetails": [
      {
        "type": "BENEFICIARY",
        "name": "John Marion Hardy Doe",
        "entityType": "INDIVIDUAL",
        "dateOfBirth": "1983-09-23"
      }
    ]
  }
}