Finrax Integration Guide

Topics to be covered

• Introduction

  • Currencies

  • Network

  • Allocation Ratio

  • Overpayment

  • How to create a business

  • How to create API keys

  • Setting up

  • Testing

  • Authorization

• Payments

  • Rate Types

  • Payment Types

    • ONE_TIME

    • REUSABLE

  • Instant Deposits

    • FIXED

    • FLOATING

  • Deposit Flow

  • Deposit Initiation

    • Initiating payments with deposit amount

    • Initiating payments with display amount

    • Integration with Finrax Checkout

    • Integration without Finrax Checkout

    • Example requests

  • Callbacks

    • Important fields

    • Missed callback handling

• Withdrawals

  • Description

    • Currency and Network combinations

    • Target amount policy

  • Withdrawals UI

  • Metadata

  • Address Validation

  • Initiate withdrawals

  • Testing the integration

    • Deposits

    • Withdrawals

Introduction

HTTP response status codes indicate whether a specific request has been successfully completed or resulted in a failure

All timestamps are formatted in UNIX

Currencies

Display Currency - That's the currency used for denomination purposes. For example if you have customers in Japan it would be best to set the display currency as JPY or if your customers are in Switzerland then the display currency should be CHF. You can think of this currency as the one your customers understand.

Let's say that I am in the US and as your customer it would be best to denominate everything in USD. I can either say: I want to deposit 100 USD in BTC or I want to withdrawal 100 USD in BTC. In both cases my balance (the customer's balance) should be updated accordingly in USD.

Settlement Currency - This is the currency in which your business holds their balance. Once you receive a deposit by your customers we will exchange it into the settlement currency and update your balance. More on how to choose a settlement currency: https://blog.finrax.com/articles/why-choose-usdt-as-settlement-currency

Deposit Currency - The currency your customer deposits in.

Uniform Currency - This is always in EUR. It's usually used for accounting purposes.

For each of those currencies Finrax calculates the amounts so there will be - display amount, settlement amount, deposit amount, uniform amount.

Network

https://blog.finrax.com/guides/blockchain-network-selection

Allocation Ratio

Every business has two settlement currencies - one in crypto and one in fiat. During the business creation you can choose how to distribute you balance between the two currencies.

https://blog.finrax.com/guides/fiat-and-crypto-balance

Overpayment

In case a user deposits more than the expected amount then we will refund the overpayment. Example: User initiates payment for 120 USD in USDT (expected deposit amount 120 USDT) User sends the equivalent of 150 USD in USDT (for simplicity that would be 150 USDT). We will then refund 30 USDT back to the user and process only 120 USD. Also, in case someone deposits twice to the same ONE_TIME payment we will refund every follow-up deposit.

https://blog.finrax.com/guides/our-approach-to-overpayments

Business Creation

https://blog.finrax.com/guides/how-to-create-a-business

API Keys

https://docs.finrax.com/authorization/management

Set up

1. Create a new test business on the production environment or ask for a test workspace at https://dashboard.finrax.com/

2. Create a new API Key to create a separate integration, allowing you to almost fully emulate a test environment. Please note that if you create this new API Key,it will be permanently tied to your user, and you will be the only one to see it.

3. Setup callback URLs, allocation ratio and overpayment policy during business creation.

4. Ask a Finrax representative to top your account with 200 USDT / EUR so you can begin testing.

Testing

As soon as the funds are added to your business, you'll be able to create a payment link and then select BCH or LTC. Once you have the deposit address you can create a withdrawal and use deposit address as target address. This way the funds won't leave your account and the only amount that will be deducted is the blockchain fee. You can find out more about the blockchain fees and minimum withdrawable amounts here:

https://finrax.com/onchain-fees

This way you can create multiple tests and explore how our various business configurations work. We usually recommend BCH / LTC as they are the cheapest, but you can use any other currency. Check your business configuration, to adjust the currencies that will be available for deposit.

Authorization

"Request is outside of receive window" error

This is usually returned when the request header timestamp is older than 10 seconds. Please check:

• Is the timestamp recent?

• Is the timestamp in the correct format?

• is there a clock drift in your system?

"Invalid request signature" error

Due to one of the following reasons:

1. Wrong hashing function for HMAC. We use SHA-256.

2. Wrong API Secret.

3. Wrong sequence of the data in the signature payload. Proper sequence is - URI_PATH + TIMESTAMP + JSON_BODY

4. Improper formation of the URI_PATH. It should always start with a "/" and should not have a trailing "/". Having this in mind, "/api/v1/payments" is a valid URI_PATH, but those aren't: "api/v1/payments", "/api/v1/payments/"

5. Timestamp in the correct format - It should be in milliseconds

6. Encoding the redirectURL

7. Ensure the you are sending all floating point numbers as string

We would advise you to make sure that the signature you are sending matches with the signature from our code snippet in the documentation:

https://docs.finrax.com/authorization/code-snippets

Payments

Rate Types

https://blog.finrax.com/guides/fixed-rates

There are certain requirements that need to be met for a payment to be treated as having FIXED rate type. Even if you initiate a payment with a FIXED rate type, it can revert to FLOATING in the case that the requirements are not met.

Payment Types

There are two different types of payments: ONE_TIME and REUSABLE. You can use either one, depending on the use case.

ONE_TIME payments are usually associated with a single deposit and they also have an expiration time. One of the advantages for ONE_TIME payments we can fix the rate for ~30 minutes. (Fixed rates are constrained by some limits). As the name of the payment type suggests, for each user transaction a new payment needs to be created. Please bear in mind that sometimes users can save the address in a note and still send to it, even if the payment is ONE_TIME. This is a scenario that we can't prevent, however as described above, you can control what happens to such payments to the OVERPAYMENT or FOLLOW-UP PAYMENT options configured in your business.

REUSABLE payments: If you expect to have multiple deposits against the same payment then you can use a one of type REUSABLE. REUSABLE payments don't have an expiration time. The exchange rate will be updated every 30 seconds. We will calculate the most recent exchange rate upon every deposit.

https://blog.finrax.com/guides/one-time-payments-vs.-recurring-payments

Instant Deposits

https://blog.finrax.com/guides/instant-deposits

Finrax Checkout Deposit Flow

https://blog.finrax.com/guides/deposit-flow

Deposit Initiation

Initiating payments with a deposit amount

Useful when the end user's balance is in crypto and you know the exact crypto amount the end user wants to deposit beforehand.

Initiating payments with display amount

Useful when the end user's balance is in fiat and you know the exact amount in display currency. Finrax will take care of every conversion and provide you with the expected deposit amount.

Integration with Finrax Checkout

By utilizing the Finrax checkout you would need to create the payment and leave the rest to our checkout deposit flow.

Integration without Finrax Checkout

• For such integration, please have a discussion with the Finrax team and we will guide you through the steps needed.

Here are a few key best practices:

• Have a page to gather all the necessary information (displayCurrency, depositCurrency, displayAmount / depositAmount etc)

• Request a Crypto Payment - The response will provide you with a deposit address, all the amounts etc.

• Display the information based on the response - expected display amount, expected deposit amount, rate, currency, network, address, destinationTag / memoId.

• In case the payment type is FLOATING you should refresh the rate shown every 30 seconds. This rate will be used only for estimation purposes and the amounts need to be recalculated.

• Given that payments change statuses to reflect the progress and update the user, the UI should reflect correctly when such changes to the status occur.

Example Requests

Initiate payment with display amount:

{
 "clientPaymentId": ${clientPaymentId},
 "locale": "en-US",
 "displayCurrency": "EUR",
 "displayAmount": 100,
 "businessId": ${businessId}
}

Submit payment details (Not needed if you use the Finrax checkout):

{
  "depositCurrency": "USDT",
  "network": "TRX",
  "displayAmount": "150"
}

Initiate payment with deposit amount:

{
 "clientPaymentId": ${clientPaymentId},
 "locale":"en-US",
 "depositCurrency":"USDT",
 "network": "TRX",
 "depositAmount":150,
 "displayCurrency":"EUR",
 "businessId": ${businessId}
}

Callbacks

Important fields

actualDepositAmount - What did the end user actually deposit actualDisplayAmount - What is the equivalent in the displayCurrency based on the actualDepositAmount settlementAmount - What is the merchants balance update in the Finrax system

Missed callback handling

We usually recommend that you have a reconciliation logic on your end. Developers should take care to ensure that their application successfully processes our notifications even in the cases of transient network error, or if they receive the same notification twice due to an improper acknowledgement.

Withdrawals

Description

Currency and Network combinations

​ Finrax currently supports the following currency and network combinations: ​

Currency	Network
USDC	Ethereum chain (ETH), Binance Smart Chain (BSC) and Solana (SOL)
ETH	Ethereum chain (ETH) and Binance Smart Chain (BSC)
USDT	Ethereum chain (ETH), Binance Smart Chain (BSC), Solana (SOL) and Tron Chain (TRX)
LINK	Ethereum chain (ETH)
SOL	Solana (SOL)
BTC	BTC
BCH	BCH
LTC	LTC
XRP	XRP
XLM	XLM

​

Target Amount Policy

The targetAmountPolicy field provides the means for specifying the withdrawal amount either in FIAT currency or CRYPTO currency.

When FIAT is selected as policy the resulting amount of the withdrawal in crypto will be calculated according to the fiat amount passed in targetAmount field.

When CRYPTO is selected as policy the resulting amount of the withdrawal will be exactly the same as the amount passed in targetAmount field (subject to a negligible difference due to market conditions i.e. market step size)

Withdraw 20 EUR worth of XRP:

{
  "withdrawCurrency": "XRP",
  "displayCurrency": "EUR",
  "targetAmount": "20",
  "targetAmountPolicy": "FIAT"
}

Withdraw 200 XRP

{
  "withdrawCurrency": "XRP",
  "displayCurrency": "EUR",
  "targetAmount": "200",
  "targetAmountPolicy": "CRYPTO"
}

Withdrawals UI

​ The following input fields are required: display currency (could be omitted if already known) Amount (in displayCurrency) Wallet Address Crypto Currency (drop down menu) network (drop down menu - best if it's pre-populated when there are no other options) When working with XLM or XRP and additional field called memoId or destination Tag respectively should be displayed. ​​

Metadata

In order to get the supported networks for the currency it would be best to call the following endpoint: ​

GET https://payments.finrax.com/api/v1/withdrawals/metadata

This endpoint requires no authorization and is publicly available. Docs: https://docs.finrax.com/references/crypto-withdrawals/request-withdrawal-metadata ​ You can think of the response Type as a Map<Currency, Map<Network, Metadata>> ​ The metadata has the following information:

{
    "fee": String,
    "minAmount": String,
    "maxAmount": String,
    "precision": Integer,
    "available": Boolean
}

​ If the network is currently unavailable then it should be disabled on the new network drop down menu. ​ It would also be nice to check if amount selected is within the min and max limits. In terms of units the minAmount and maxAmount values depend on the Currency/Network combination. ​ Example:

"USDT": {
    "BSC": {
      "fee": "0.29",
      "minAmount": "13.0000",
      "maxAmount": "200000",
      "precision": 8,
      "available": true
    }
    ...
}

​ The minAmount is 13 USDT for USDT on the BSC network. The maxAmount is 200000 USDT for USDT on the BSC network. ​ The following endpoint can convert the min and max amounts to the correct currency.

GET https://payments.finrax.com/api/v1/exchange/rates/market?fromCurrency=${fromCurrency}&toCurrency=${toCurrency}

Example usage: https://payments.finrax.com/api/v1/exchange/rates/market?fromCurrency=BCH,BTC,ETH,LTC,LINK,USDT,XLM,XRP&toCurrency=EUR,GBP,USD This endpoint requires no authorization and is publicly available. Docs: https://docs.finrax.com/references/currencies-and-fees/get-exchange-rates-any-currency-to-any-currency ​ It would also be nice to display what would be the estimated fee for this withdrawal. The logic described above can be used to show the fee amount into the correct currency.

Address validation

​ GET https://payments.finrax.com/api/v1/currency/:currency/network/:network/address/:address/valid

Example: https://payments.finrax.com/api/v1/currency/BCH/network/BCH/address/0x5b3cd4c0230386f98582d8485c460d692167756d/valid

For XLM and XRP you can also validate the format of the memoID or the destination Tag. Url path parameter is called destinationTag for both currencies.

GET https://payments.finrax.com/api/v1/currency/:currency/network/:network/address/:address/destinationTag/:destinationTag/valid

Example: https://payments.finrax.com/api/v1/currency/XLM/network/XLM/address/GCXZDLDI4BO3RHIYBS22RZXB5LGRRLTZUSPG6ANQQ36TVL2ASHC4ONPP/destinationTag/2213123/valid

Docs: https://docs.finrax.com/references/crypto-addresses/validate-address ​

Initiate withdrawals

​ ​The following endpoint needs to be used to initiate a withdrawal:

POST https://payments.finrax.com/api/v1/withdrawals

Docs: https://docs.finrax.com/references/crypto-withdrawals/initiate-withdrawal-request

Initiate Withdrawal:

{
 "clientWithdrawalId": ${clientWithdrawalId},
 "displayCurrency": "JPY",
 "withdrawCurrency": "BTC",
 "recipientAddress": ${recipientAddress},
 "targetAmountPolicy": "FIAT",
 "targetAmount": "10000.00",
 "businessId": ${businessId}
}

Testing the integration

Deposits:

• XRP/XLM - how do you handle destinationTag / memoID

• How you handle ETH, BSC, TRX, SOL networks

• Underpayments, Overpayments -> How does your system handle it and what is the balance update to the end user

• Status changes - PENDING, DEPOSITED, EXPIRED etc

• Usability and Locale tests

Withdrawals:

• Invalid address

• XRP/XLM - how do you handle destinationTag / memoID

• How you handle ETH, BSC, TRX, SOL networks

• Status changes in your system