Processing methods

Payment Methods Comparison

Orbital offers different payment methods to leverage their unique advantages and cater for all Merchant needs, which can then choose the one best suited for its business model, or to use all three at the same time on different products or different occasions.

It is important to notice that all payment methods use the exact same processing fees and are credited in the same way on the Merchant balance, enabling the usage of all in parallel or separately as the Merchant wishes. The Payment Methods are available through separate API endpoints, which makes it easier for integration and separation in case the Merchant needs to start or stop using any of them.

Please note that while we offer two different Payment Methods, each with its own unique advantages, it is not necessary for the Merchant to integrate with both, and most Merchants will find a single Payment Method more beneficial to their use cases.

For deciding which Payment Method is best suited for your business model, we have created a simple flow chart that you can use for initial thoughts, but please keep in mind that we highly suggest reading all the Knowledge Base articles and Payment Methods explanations so you can fully understand all the pros and cons of each Payment Method.

As you can see, there are different use cases for each of the Payment Methods, in summary, we can define it's pros and cons also on the below table:

Please find a more detailed explanation of each feature below.

Operational Costs: The Invoice Payment Method utilises smart strategies on the consolidation phase of a payment. Due to the nature of the workflow, Orbital is able to control which addresses are going to be used on each payment and consequently dramatically reduce the fees necessary to consolidate the funds received from customers into a central wallet that is attached to the Merchant. On the Channel Payment Method, as these addresses are unique and can be reused at any time by a customer, all funds transferred on a deposit need to be settled and consolidated instantly, which effectively can create big operational costs depending on the blockchain network that the cryptocurrency was transferred with. Please note that this is not valid for USDT TRC-20, as the network fees are so low that there is no advantage on optimising the sweeping phase consolidation costs.

Integration Complexity: The Channel Payment Method was signaled with a High complexity due to its total asynchronous nature, as a deposit can be made at any point in time by a customer that will trigger the events sent to the Merchant backend server, which in turn needs to be ready to process these deposits at the time of notification arrival with the Merchant specific business logic and the current conversion rates. The Invoice Payment method in turn, can be integrated with a more synchronous functionality, where they can generate a payment that has a specific time limit to be fulfilled by the customer, although the Invoice Method needs extra development effort from Merchant due to the necessity of selecting a specific amount in any supported currency that the payment should be created with

Configuration: The configuration aspect explained on this feature, relates to the ability of setting different routes and conversion settings (e.g. Receiving BTC, being credit with USD balance and receiving the equivalent current rate of CNY) on a given payment. On the Invoice Payment method, due to the necessity of entering into a new deposit workflow for every new payment generation, these settings can be changed or configured for every new payment/deposit that is created. On the Channel Payment Method, as the Merchant creates a unique address for a user only once that can be reused at any point in time on the future, these configurations are only available to be done at the moment of its creation, without possibility of changing the conversions and routing after a given address has already been created.

Time Constraint: One of the few limiters of the Invoice Payment method, are the time constraints and expiration time that a payment has after it has been generated, where a user needs to complete the transfer successfully within the retrieved expiration window; whereas on the Channel Payment Method no time constraint exists whatsoever, enabling a much friendlier and flexible approach for the user that can deposit whenever and any amount he wishes (even very small amounts).

Address Reusability: On the Invoice Payment Method, a new deposit workflow needs to be done and a new payment generated for every new transfer, when this happens, Orbital retrieves the merchant an address that should be used when transferring funds related to this payment, which in turn should be displayed to the customer; in this case, this address should not be reused after this payment as it is only valid until the expiration time of the aforementioned generated payment, and for the designated user. On Channel Payment Method, a Merchant generates a unique address for a user, that can be reused at any time, without the need of guiding the customer through a new deposit workflow and displaying new addresses to them, creating a better UX, where this unique address can be attached to his account on the Merchant platform and be always visible.

Amount of Control: On the Channel, the Merchant does not control how many funds are going to be sent by the customer to the designated address, which can lead to customers sending extremely small or big amounts. The Invoice Payment Method on the other side, give this control totally to the Merchant, which creates an invoice payment with Orbital with a pre-selected amount described in any currency, in this way, the Merchant ensures minimum and maximum amounts allowed in any currency through any desired component (e.g. Input box that the user types USD amount or list of pre-selected values in CNY).

Channel Payment Method

Key characteristics:

• Customer receives a unique address that can be reused at any time
• Customer can deposit any amounts into such address
• Merchant generates one address per customer
• Payment currency conversion configuration is set only once when address is generated
• No need to guide user to a payment workflow on every new deposit
• User friendly and customer focused UX

On the Channel Payment Method, the merchant simply needs to provide a wallet address (requested from Orbital API) for the end-user to send their cryptocurrency coins to (this should not be considered a transaction or an order at this stage). The Merchant should then make sure to record in their system which end-user they requested this wallet address on behalf of, so they can later connect any payments received to that wallet with the corresponding end-user (i.e to credit their balance).

The second part of the process, is where the end-user actually makes a payment of some coins to the wallet address, please note that this can happen at any point in time, for any amount, and more than once. Because of these last three unknown variables, it’s important to note that generating the wallet is not assumed to be tied or associated to a single order_id or transaction_id like you would in regular synchronous payment flow.

The actual transaction is always generated from outside of the merchant system (initiated from Orbital API side via callback to merchant), whenever the end-user sends some coin to the previously provided wallet address. When this happens, Orbital will notify the merchant via API, and the merchant should trigger the process of creating and recording a transaction for the corresponding end-user on their platform, resulting in a credit of the end-users balance.

Invoice Payment Method

• Customer goes into a payment workflow for every new deposit.
• Addresses are not unique per customer and cannot be reused.
• Customer has 15 minutes to send funds after payment is generated.
• Locked conversion rates for 0 volatility exposure during payment time.
• Total Merchant control on Minimum and Maximum amounts allowed
• Ability to preemptively choose the value that will be received in any Merchant Balance currency (crypto or fiat), and converting to exact amount that user needs to deposit in chosen crypto.
• Greatly reduced and optimised network fees for settling funds.
• Payment currency conversion configuration flexible for every single payment.
• Optimised operational costs and configurable volatility exposure risk, Merchant Focused UX

On the Invoice Payment Method, the merchant needs to initiate a payment workflow with his user every time that he wishes to initiate a new deposit payment, similar to synchronous methods. When starting a new deposit workflow, the merchant will generate a new payment (requested from Orbital API) with a Merchant generated orderId/transactionId, the amount that the Merchant wishes to receive in any currency and the crypto currency that the customer wishes to send the payment in(Note that differently then the Channel Payment Method, this generated payment should already be considered a transaction or an order that can be successful or failed at this stage). Within the generated payment, the merchant will receive attached to it the address in which the coins should be sent to, the expiration time that marks when this payment will become invalid and the exact selected crypto currency amount equivalent to the previously Merchant chosen value that the customer should send to the address.

The second part of the process, is where the end-user actually makes a payment to the returned wallet address or the payment expires without any transaction after 15 minutes. If the user send funds to the retrieved wallet address in the same or greater value than the payment specified, the transaction will be successful and will be updated accordingly. For analogous payments, if after 15 minutes no transactions were broadcasted to this address, the payment will be marked as failed, or if a smaller amount was sent to it, the payment will be marked as rejected.

Note that for all payment status updates described above, Orbital will notify the merchant via an API notification with the latest updates and transactions information. This happens when they occur on the blockchain in real time, due to it’s asynchronous nature even with a time constraint, the merchant should only then trigger the process on their platform that results in crediting or not the end-user balance

Understanding Currencies Involved

Orbital understands that merchants may want to receive deposits in various cryptocurrencies (e.g Bicoin/BTC), and that they may want to credit their end-user’s balance in another fiat currency (e.g CNY, THB, INR, VND, etc), and they may even wish to convert the received cryptocurrency and be settled in a third currency (e.g USD/EUR/GBP) to avoid price volatility risk.

Orbital provides a very flexible system to accommodate any combination of currency needs the merchant may have. Orbital does this by allowing the merchant to specify three different currency parameters for each wallet or payment that is requested and generated independently of the payment method chosen.

"currency": "BTC",
"targetCurrency": "USD",
"cashierCurrency": "CNY",

“currency” - this required parameter is the cryptocurrency which you want to generate a wallet address for (e.g. Bitcoin, USDT, Ethereum, Bitcoin Cash, etc).

“targetCurrency” - this optional parameter is the currency which you may want Orbital to automatically convert the received cryptocurrency coins into, in order to avoid any crypto price volatility risk. Bitcoin is well known for its high swings in value, and therefore merchants understandably do not want to hold on to Bitcoin for too long. Setting this parameter to either USDT or USD will automatically convert the received Bitcoin to this specified currency at the time of the transaction in real time. If this option is selected, the merchant will accumulate a positive balance on Orbital in the specified targetCurrency, as opposed to the original cryptocurrency received from the end-user.

“cashierCurrency” - this final optional parameter is used by the merchant to inform Orbital the local fiat currency in which the merchant intends to credit the end-users balance on the merchant system. For example, if the end-user is in China, and has a CNY balance on the merchant system, then you would pass a CNY value in this parameter to Orbital. Multiple global currencies are supported (THB, VND, INR, USD, etc). The result of providing this cashierCurrency is that Orbital can provide an indicative real time currency conversion value, in the local currency, back to the merchant, at the time the coins being received to the wallet address or at the payment generation time in an invoice scenario, so the merchant knows how much to credit the end-users balance by. Orbital calculates this amount by checking the live market value of the cryptocurrency received, or the amount in which the Invoice Payment was generated with (in case of Invoice Payment Method), converting it to USD at our institutional liquidity provider, and then uses XE.com to convert the USD value to the local cashierCurrency.

This value should be used for information purposes only and does not affect any settlement amounted owed to the merchant by Orbital. The merchant can use this exact amount to credit the end-user balance, or they can manipulate it by a few percentages to add some spread to cover their costs. Alternatively the merchant does not need to use this parameter or the info provided, and can make their own calculations about how much to credit their end-user in whichever local currency. N.B. please note, the CashierCurrency returned value is a conversion of the total amount of coins received or the total amount selected when generating an Invoice (in case of Invoice Payment Method), it does not take in to account Orbital fees. The merchant may want to manipulate the returned cashierCurrency amount to pass on the fees to the end-user.

Example Use Cases

Some common use case examples and recommendations that explains the currencies functionality on both payment methods:

Use Case 1 - Cashier balance in CNY, receive BTC, convert to USDT (or USD) for holding

In this use case the merchant has end-users in China, who normally deposit in CNY. The merchant now wants to accept Bitcoin (BTC) from those end-users. However, the merchant does not want to be exposed to the price volatility of Bitcoin, and should therefore automatically convert any received Bitcoin in to USDT which is far more stable. To achieve this, the merchant would use the following combination of currencies:

Channel Payment Method:

"currency": "BTC",
"targetCurrency": "USDT",
"cashierCurrency": "CNY",

1. Orbital will provide a BTC wallet address for the end-user to send coins to.
2. As soon as BTC coins are received, Orbital will automatically convert those coins to USDT in real time, and then credit the merchant balance in USDT.
3. Orbital will then send a notification to the merchant callback URL to inform about the received transaction. The merchant will then know how much BTC was received, how much USDT this was converted in to, and how much that is worth in CNY at live market rates (based on XE.com rate for USD/CNY). Merchant will then decide how much to credit the end-user balance in CNY.

Batch Payment Method:

"currency": "BTC",
"targetCurrency": "USDT",
"cashierCurrency": "CNY",

1. Orbital will provide a BTC wallet address for the end-user to send coins to that is valid only for this payment and for a specific amount of time (15 min currently).
2. As soon as BTC coins are received, Orbital will automatically convert those coins to USDT in real time and then credit the merchant balance in USDT.
3. Orbital will then send a notification to the merchant callback URL to inform about the successful payment. The merchant will then know how much BTC was received, how much USDT this was converted in to, and how much is the equivalent of CNY at live market rates (based on XE.com rate for USD/CNY). Merchant will then decide how much to credit the end-user balance in CNY.

Invoice Payment Method:

urrency": "BTC",
"targetCurrency": "USDT",
"targetAmount": 10000,
"cashierCurrency": "CNY",

1. Merchant will generate a Payment with a specific pre-determined amount in targetAmount (targetCurrency) and Orbital will retrieve the address and the exact amount to be deposited in BTC. The merchant will then know the rate used and the equivalent of 10,000.00 USDT in BTC and CNY with the live market rates( based on XE.com rate for USD/CNY) that will be locked for the next 15 minutes.
2. As soon as the specified BTC amount is received, Orbital will automatically convert those coins to USDT in real time, and then credit the merchant balance in USDT.
3. Orbital will then send a notification to the merchant callback URL to inform about the received transaction. Merchant will then decide how much to credit the end-user balance in CNY

Use Case 2 - Cashier in THB, receive USDT, no conversion

In this use case the merchant has end-users in Thailand, who normally deposit in THB. The merchant now wants to accept USDT Tether from those end-users. As there is no price volatility risk with USDT, the merchant will not be auto-converting the received cryptocurrency. To achieve this, the merchant would use the following combination of currencies:

Channel Payment Method:

"currency": "USDT",
"cashierCurrency": "THB",

1. Orbital will provide an ERC-20 USDT wallet address for the end-user to send coins to.
2. As soon as USDT coins are received, Orbital will credit the merchant balance in USDT.
3. Orbital will then send a notification to the merchant callback URL to inform about the received transaction. The merchant will then know how much USDT was received, and how much that is worth in THB at live market rates (based on XE.com rate for USD/THB). Merchant will then decide how much to credit the end-user balance in THB.

Invoice Payment Method:

"currency": "USDT",
"cashierCurrency": "THB",
"cashierAmount": 5000

1. Merchant will generate a Payment with a specific pre-determined amount in cashierAmount in THB currency (cashierCurrency) and Orbital will retrieve the address and the exact amount to be deposited in USDT. The merchant will then know the rate used and the equivalent of 5,000.00 THB in USDT with the live market rates (based on XE.com rate for USD/THB and USDT/USD) that will be locked for the next 15 minutes.
2. As soon as the specified USDT amount is received, Orbital will instantly credit the merchant balance in USDT.
3. Orbital will then send a notification to the merchant callback URL to inform about the received transaction. Merchant will then decide how much to credit the end-user balance in THB.

Use Case 3 - Cashier in BTC, receive BTC, no conversion

In this use case the merchant has end-users around the world, and they run a cashier balance directly in BTC. The merchant now wants to use Orbital accept BTC from those end-users. As there everything is in the same currency, the merchant will not be auto-converting the received cryptocurrency. To achieve this, the merchant would use the following combination of currencies:

Channel Payment Method:

"currency": "BTC",

1. Orbital will provide a BTC wallet address for the end-user to send coins to.
2. As soon as BTC coins are received, Orbital will credit the merchant balance in BTC.
3. Orbital will then send a notification to the merchant callback URL to inform about the received transaction. The merchant will then know how much BTC was received, and how much to credit the end-user balance in BTC.

Invoice Payment Method:

"currency": "BTC",
"sourceAmount": 1.4

1. Merchant will generate a Payment with a specific pre-determined amount in sourceAmount (currency) and Orbital will retrieve the address and the exact amount to be deposited in BTC.
2. As soon as the specified BTC amount is received, Orbital will instantly credit the merchant balance in BTC.
3. Orbital will then send a notification to the merchant callback URL to inform about the received transaction. The merchant will then be able to credit the end-user balance in BTC or in any other currency he wishes.

Have another use case you would like explained? Don’t hesitate to contact your account manager and we will advise on the best setup (and get it added to the Knowledge Base)

Deposit Process

Channel Payment Method:

Step 1: Generate a wallet address

For initiating deposits through cryptocurrencies, the merchant would need to call the Orbital API to request a “wallet address” to which their end-user should send their cryptocurrency coins. This wallet is then displayed to the end-user on the merchant cashier page.

The Orbital system will generate a new unique wallet address for each API request received from the merchant. Once some coins hit the wallet address, the Orbital platform will send a notification to the merchant notification URL. The merchant’s system then uses this information to determine which end-user account to credit, and by how much. It’s important to note that end-users can send multiple separate payments to the same wallet address previously provided, in which case Orbital will provide a second, third, fourth, etc, notification to the merchant for each subsequent coin deposit transaction. Each time this happens, the merchant system should credit the corresponding end-user account. It is therefore important to generate a unique wallet address for each end-user as a bare minimum. However, to take this a step further, we encourage generating a unique wallet address for each deposit request on the cashier. The merchant should use the “External ID” parameter to link incoming funds to a corresponding end-user on their platform. It’s obviously important that the merchant record which user each External ID request is mapped to.

To request a unique wallet address, the merchant should call the “Create Receiving Address” API endpoint: https://api-docs.paymero.io/?version=latest#e7a51be8-9ff7-48e6-9c96-1239bc4f74fd

The merchant should submit their API request with the following parameters:

1. currency – Mandatory field. This will be the cryptocurrency you want to receive from the end-user. Supported values are: BTC, USDT, LTC, ETH, BCH, BSV
2. targetCurrency – Optional field. This will be the currency to which you want to auto-convert the received cryptocurrency in to. Can be USD/EUR/GBP. If this option is selected, the converted amount will be credited to the merchant balance in the Orbital backoffice. The merchant would use this option if they want to avoid the price volatility risk in cryptocurrencies such as BTC. Generally, if you are processing USDT, as there is no price volatility risk, you would not use this option. Supported values are: USD, EUR, GBP. Please note that depending on the cryptocurrency being sent, there are minimum volumes to be converted: 0.0005 BTC, 0.005 ETH, 0.01 BCH, 0.1 LTC.
3. cashierCurrency – Optional field. This field is to let the Orbital platform know which currency you intend to credit your end customers balance in. By specifying this field, Orbital will calculate the live conversion rate (e.g from BTC->USD->CNY), and provide this information back to the merchant at the time that the transaction is successful. It is then up to the merchant to decide whether to credit the consumer balance with this amount, or modify it by a few percent to make a margin. This value will only be stored alongside payment information and will not reflect in the Financial Balances in Orbital platform. Supported values are any ISO currency codes, including CNY, THB, VND, MYR, IDR, INR, BRL, KRW, etc.
4. externalID – this is a unique reference ID generated from the Merchant's system which will allow the Merchant's system to match an asynchronous incoming transaction to a specific user on their system. We suggest the Merchant generate this address in one of two ways:

1. Generate one “External ID” per User on the merchant's system - this means when coins are received at the wallet address generated, and Orbital notifies the merchant, the merchant will know which User account to credit.
2. Generate a new “External ID” for each new Deposit request on the merchant's system - in this case, the External ID would be something like an Order_ID or Tranaction_ID on the merchant’s platform. This ID would then need to be mapped to a corresponding User account on the merchant system, so that when Orbital notifies the merchant system about some incoming coins, the merchant system knows which user account to credit.

5. notifyUrl – The webhook URL which Orbital will send the the change of transaction status notification to (I.e. when an end user has sent some coin to the wallet address).

Step 2: Displaying the Wallet to the User

1. Once the request is sent, Orbital will generate receiving wallet address to which the selected cryptocurrency deposit has to be made.
2. Merchant would need to display the wallet address to the user. We recommend displaying this with a QR code (for scanning), and also the wallet address itself for end-users to be able to copy and paste in to their own wallet. Read more on suggested UX/UI here.
3. Alongside the wallet address we recommend the merchant displays the live conversion rate of what the depositing crypto currency is worth in local market currency. I.e if receiving BTC in China, then we recommend display how many CNY each Bitcoin deposited will be worth when credited to their balance.
4. The end-user would then need to make the payment from their own crypto wallet to the wallet address provided. Important: End-users should be explicitly informed that they must make sure to send the correct crypto currency to the wallet address provided. Sending USDT to a BTC wallet address could result in loss of funds.

Step 3: Awaiting successful transaction confirmation

As soon as the cryptocurrency transaction is created on the blockchain (this happens as soon as the end-user sends their coin to the wallet address provided), Orbital will wait for the necessary number of confirmations. This can take anywhere from 10 seconds to 30 minutes, depending on the cryptocurrency involved.

Once the necessary number of confirmations appears on the blockchain, Orbital will send a callback to the Notification URL provided by the merchant. This callback will not include any sensitive information about the transaction as a deliberate security measure to prevent spoofing type hack attempts.

Step 4: Requesting the successful transaction information

As previously mentioned, Orbital does not send sensitive data in the callback notification to Merchant. we require the merchant to “Get” the Payment information from the Orbital API in order to prevent any potential spoofing.

Using the Orbital unique transaction ID shared on the callback notification, the Merchant would need to do a query Get Payment API to get the complete details of the transaction, including details like transaction hash, source currency + amount, target currency + amount, cashier currency + amount, blockchain confirmation details, etc. Full details can be viewed in the Example Response here.

Step 5: Create a Transaction and then Credit the end-user balance

Based on the information previously provided in the payment transaction information response, it is only at this point that we know how much cryptocurrency the end-user actually sent. It is for this reason that we recommend that the merchant only creates a new transaction within their system at this point, and records the details, and then credit the end-user balance the corresponding amount in local currency.

When crediting the end-user, we recommend taking in to careful consideration about how much to credit their balance by. As mentioned above, Orbital provides an easy way for the merchant to calculate the amount of crypto received converted in to the local currency used on the cashier balance. However, it is up to the merchant to truly decide how much to credit the end-user. Most merchants will add a percentage or two spread to the amount to cover their fees. It’s worth noting that in most cases the price of crypto is generally a few percent higher than what it is in the unrestricted market, so there is not a commonly accepted price for crypto in these markets, which means the end-user might not have a clear idea of how much it is worth.

However the merchant decides to calculate the final amount they intend to credit the end-user, we recommend that the merchant uses this same calculation when displaying the live conversion rate next to the wallet in step 2.

Invoice Payment Method:

Step 1: Generate a payment

For initiating a new cryptocurrency invoice payment workflow, the merchant will need to guide the user through the deposit process, to gather the information on how much the deposit value will be in their selected currency. With this information, the merchant would need to call the Orbital API to request a new invoice payment, which would retrieve the wallet address and the exact amount in the selected cryptocurrency that is equivalent to the value selected for payment after conversion. This wallet address and the amount to be transferred is then displayed to the end-user on the merchant cashier page .

Orbital system will return a different wallet address for each API request received from the merchant, which are managed by Orbital. This provides maximum optimisation on settlement fees related to the network costs for moving the funds to a central wallet. Once the exact amount of coins hit that wallet address, the Orbital platform will send a notification to the merchant notification URL. The merchant’s system then uses this information to determine which end-user account to credit, and by how much. It is therefore important to generate a unique “orderID” or “paymentID” for each deposit request on the cashier, as these addresses cannot be treated in the same way as the channel payment method due to them not being unique. With that said, the merchant should use this “External ID” parameter to link incoming funds for a payment, to a corresponding end-user on their platform. It’s obviously important that the merchant records which user each External ID request is mapped to.

To request a new payment, the merchant should call the “Create Invoice Payment” API endpoint: https://api-docs.paymero.io/?version=latest#74cb3cc4-4ab7-4064-a6e3-beba11570d28

The merchant should submit their API request with the following parameters:

currency – This is a mandatory field. The currency field represents which crypto currency this payment will receive funds from. Note that creating an invoice payment using currency as BTC will create a totally different address than using currency as ETH, and even when creating new payments for the same currency, each request will return an unexpected address. Supported receivable crypto currencies are: BTC, USDT, LTC, ETH, BCH.

mainCurrency – This field is optional and currently only in use for payments that are created using currency as USDT, which in this case, mainCurrency can be ETH or TRX. This will be the blockchain in which the given currency runs; note that mainCurrency on USDT by default is ETH, and for TRC-20 version of USDT usage, mainCurrency need to be set as TRX. Therefore supported values are: ETH, TRX.

targetCurrency – Optional field. This will be the currency to which you want to auto-convert the received cryptocurrency in to. Can be USD/EUR/GBP. If this option is selected, the converted amount will be credited to the merchant balance in the Orbital back-office. The merchant would use this option if they want to avoid the price volatility risk in cryptocurrencies such as BTC. Generally, if you are processing USDT, as there is no price volatility risk, you would not use this option. Supported values are: USD, EUR, GBP, USDT. Please note that depending on the cryptocurrency being sent, there are minimum volumes to be converted: 0.0005 BTC, 0.005 ETH, 0.01 BCH, 0.1 LTC.

targetAmount - Optional field. This field is to let the Orbital platform know the amount in which the invoice payment should convert into of the targetCurrency, so the value of currency can reflect the necessary equivalent funds. (eg. targetCurrency: USD, targetAmount: 500, currency: BTC → will generate an invoice for BTC transfer that will return the corresponding value that should be sent in BTC to credit the merchant balance with 500USD)

cashierCurrency – Optional field. This field is to let the Orbital platform know which currency you intend to credit your end customers balance in. By specifying this field, Orbital will calculate the live conversion rate (e.g from BTC->USD->CNY), and provide this information back to the merchant at the time that the transaction is successful. It is then up to the merchant to decide whether to credit the consumer balance with this amount, or modify it by a few percent to make a margin. This value will only be stored alongside payment information and will not reflect in the Financial Balances in Orbital platform. Supported values are any ISO currency codes, including CNY, THB, VND, MYR, IDR, INR, BRL, KRW, etc.

cashierAmount - Optional field. This field is to let the Orbital platform know the amount in which the invoice should be equivalent to, from the native merchant platform currency, so the value of currency being transferred can reflect the necessary equivalent funds. (eg. cashierCurrency: CNY, cashierAmount: 1000, currency: BTC → will generate invoice for BTC transfer that will return the corresponding value that should be sent in BTC with the current conversion rate from 1000CNY/BTC )

externalId – this is a unique reference ID generated from the merchant's system which will allow the merchant's system to match an incoming transaction to a specific payment, or order on the merchant system.

notifyUrl – The webhook URL which Orbital will send the the change of transaction status notification to (I.e. when an end user has sent some coin to the wallet address that was generated for a certain invoice and transaction statuses have been changed).

redirectUrl - Optional field. Only used in case the merchant integrates with the self hosted pages. This URL is used to redirect the user on the self hosted pages after a successful payment.

Step 2: Displaying the wallet and the amount for deposit to the User:

1. Once the request is sent, Orbital will retrieve the receiving wallet address to which the selected cryptocurrency deposit has to be made, alongside the exact equivalent amount that the payment was generated for, and the expiration date of when this payment will not be valid anymore.
2. Merchant would need to display the wallet address to the user, the exact amount to be transferred and the amount of minutes remaining for the payment. We recommend displaying this with a QR code (for scanning), and also the wallet address itself for end-users to be able to copy and paste in to their own wallet. Read more on suggested UX/UI here.
3. Alongside the wallet address we recommend that the merchant displays how many funds will be credited to the end-user balance once the payment is completed successfully and a timer showing how many more minutes this payment is valid for.
4. The end-user would then need to make the payment from their own crypto wallet to the wallet address provided within the expiration time with the exact amount provided. Important: End-users should be explicitly informed that they must make sure to send the correct crypto currency to the wallet address provided, the correct amount and within the expiration time. Sending USDT to a BTC wallet address will result in loss of funds. Sending coins to a payment that has already expired will result in loss of funds. Sending a different amount of coins than provided will result in loss of funds.

Step 3: Awaiting successful transaction confirmation

As soon as the cryptocurrency transaction is created on the blockchain (this happens as soon as the end-user sends their coin to the wallet address provided), Orbital will send a call-back Notification URL provided by the merchant with the status update that this payment is pending. This call-back will not include any sensitive information about the transaction as a deliberate security measure to prevent spoofing type hack attempts.

Orbital will wait for the necessary number of confirmations. This can take anywhere from 10 seconds to 30 minutes, depending on the cryptocurrency involved. Once the necessary number of confirmations appears on the blockchain, Orbital will also send a call-back Notification URL provided by the merchant with the status update that this payment is confirmed or credited.

Step 4: Requesting the successful transaction information:

As previously mentioned, Orbital does not send sensitive data in the call-back notification to the Merchant. We require the merchant to "Get" the Payment information from the Orbital API in order to prevent any potential spoofing.

Using the Orbital unique payment ID shared on the call-back notification, the Merchant would need to do a query Get Payment API to get the complete details of the transaction, including details like transaction hash, source currency + amount, target currency + amount, cashier currency + amount, blockchain confirmation details etc. Full details can be viewed in the Example Response here.

Step 5: Credit the end-user balance

Based on the information previously provided in the payment transaction information response, it is only at this point that we know if the payment was completely successful or not, and then credit the end-user balance the corresponding amount in local currency.

When crediting the end-user, we recommend taking in to careful consideration how much to credit their balance by. As mentioned above, for the Invoice Payment Method, Orbital provides the possibility for the Merchant to setup the amount to be received by the user preemptively, which will be credited in his merchant balance on the backoffice in any currency, however, it is up to the merchant to truly decide how much to credit the end-user. Most merchants will add a percentage or two, to spread the amount and cover their fees.

However the merchant decides to calculate the final amount they intend to credit the end-user, we recommend that the merchants uses this same calculation when displaying the amount to be deposited next to the wallet in step 2.