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
Create a new test business on the production environment or ask for a test workspace at https://dashboard.finrax.com/
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.
Setup callback URLs, allocation ratio and overpayment policy during business creation.
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:
Wrong hashing function for HMAC. We use SHA-256.
Wrong API Secret.
Wrong sequence of the data in the signature payload. Proper sequence is - URI_PATH + TIMESTAMP + JSON_BODY
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/"
Timestamp in the correct format - It should be in milliseconds
Encoding the redirectURL
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:
Submit payment details (Not needed if you use the Finrax checkout):
Initiate payment with deposit amount:
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:
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:
Withdraw 200 XRP
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:
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:
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
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
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:
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
Last updated