Setting up Currency options for Pay-ins and Pay-outs

The currencyOptions object within the Create Payment payload, allows merchants to specify which currencies are available for the end user to receive payment. This object is not mandatory; however, if provided, it restricts the currencies 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://your-website-url.com/status",
  "customerId": "1289702",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.2",
    "partyDetails": [
      {
        "type": "BENEFICIARY",
        "firstName": "John",
        "lastName": "Doe",
        "entityType": "INDIVIDUAL",
        "dateOfBirth": "1983-09-23",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE"
      }
    ]
  },
  "currencyOptions": [
    {
      "code": "ETH"
    },
    {
      "code": "USDT"
    }
  ]
}

{
  "merchantId": "MERCHANT_SETTLE_MID_WALLET",
  "amount": 2.0,
  "currency": "ETH",
  "reference": "REF777579",
  "type": "IN",
  "returnUrl": "https://your-website-url.com/status",
  "customerId": "1289702",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.2",
    "partyDetails": [
      {
        "type": "ORIGINATOR",
        "firstName": "John",
        "lastName": "Doe",
        "entityType": "INDIVIDUAL",
        "dateOfBirth": "1983-09-23",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE"
      }
    ]
  },
  "currencyOptions": [
    {
      "code": "ETH"
    },
    {
      "code": "USDT"
    }
  ]
}

Detailed Field Explanation

Structure:

"currencyOptions": [
  {
    "code": "Currency code"
  }
]

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

Payload Examples

Example of limiting the Payment currencies:

Below is an example of a currencyOptions object limiting the transaction to ETH and USDT:

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

Example without Specified Currency Preferences

Below is an example payload for creating a payment 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://your-website-url.com/status",
  "customerId": "1289702",
  "flow": "PAYROLL",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.2",
    "partyDetails": [
      {
        "type": "BENEFICIARY",
        "firstName": "John",
        "lastName": "Doe",
        "entityType": "INDIVIDUAL",
        "dateOfBirth": "1983-09-23",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE"
      }
    ]
  }
}

"merchantId": "MERCHANT_SETTLE_MID_WALLET",
  "amount": 2.0,
  "currency": "ETH",
  "reference": "REF777579",
  "type": "IN",
  "returnUrl": "https://your-website-url.com/status",
  "customerId": "1289702",
  "complianceDetails": {
    "requesterIpAddress": "172.16.254.2",
    "partyDetails": [
      {
        "type": "ORIGINATOR",
        "firstName": "John",
        "lastName": "Doe",
        "entityType": "INDIVIDUAL",
        "dateOfBirth": "1983-09-23",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE"
      }
    ]
  }
}