Set up Currency for Payments

The currencyOptions object within the Create Payment payload, allows merchants to specify the currencies that 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. For the complete list of supported currencies and protocols, refer to the Supported Currencies API.

{
  "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": [
      {
        ...
      }
    ]
  },
  "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": [
      {
        ...
      }
    ]
  },
  "currencyOptions": [
    {
      "code": "ETH"
    },
    {
      "code": "USDT"
    }
  ]
}

The currency object has the following structure:

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

Field	Type	Description	Mandatory	Example
`code`	string	String value representing the cryptocurrency code.	Yes	`ETH`

Payload Examples

Limitation of the payment currencies

Below is an example of the currencyOptions object limiting the transaction in ETH and USDT cryptocurrencies:

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

Currency not set

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 in the 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"
      }
    ]
  }
}