# Introduction ![](/files/qRjzk4dIlNAKOkAak618) Aquapay is an integration platform that enables digital asset processing functions for payments service providers. Our platform handles the conversion between cryptocurrency and fiat currencies. Aquapay is a product offered by Aquanow, leading digital assets liquidity and infrastructure provider trusted by the world’s fastest growing financial institutions, internet platforms, and progressive businesses. Aquapay users benefit from cryptocurrency conversions executed with deep liquidity consolidated across global markets through the Aquanow infrastructure. Fiat can be settled efficiently into preferred currencies and service provider bank accounts through our global banking network. We work closely with our clients to optimize settlement times through banking and inter-company processes. Settlement is offered in three convenient ways: * **Request** – withdrawal instruction made through Aquapay or client support * **Schedule** – withdrawal processed on a predetermined schedule (ex: daily, weekly) * **Threshold** – withdrawal processed when your balance exceeds a set amount We support various electronic payment methods including SWIFT, SEPA, and EFT. We also support the following fiat currencies & cryptocurrencies: ### Supported Fiat Currencies * Euro ( EUR ) * United States Dollar ( USD ) * Canadian Dollar ( CAD ) ### Supported Cryptocurrencies * Bitcoin ( BTC ) * Ethereum ( ETH ) * Bitcoin Cash ( BCH ) * USD Coin ( USDC ) * Tether USD (USDT-ERC20, USDT-TRC20 ) * Litecoin ( LTC ) * Matic Token ( MATIC-ERC20 ) * Solana ( SOL ) For more information, please reach out to to set up a test account. # Payments Facilitation ![](/files/Si9c8RKe2HGXSUGjvXVP) # Web Portal ![](/files/8HncbEYKgRWhtNCZyUqf) Aquapay web portal provides an easy way for user to monitor the transaction activities, user balance and API management. The web portal for the sandbox environment is: ``` https://pay-staging.aquanow.io ``` The web portal for the production environment is: ``` https://pay.aquanow.io ``` # Account Management The Account Management section contains the Balances page, which has information about the crypto and fiat account balances. ![](/files/itIGbsZl5zjjVsZUOSQa) ![](/files/bdkAZkgiyFkVMBDTz3qp) Aside from viewing the account balance, through this section, users also have the options to Manage Withdrawal Info and Withdraw. Manage Withdrawal Info refers to whitelisting the banking info for fiat and withdrawal addresses for crypto. ![](/files/dSvQ2ucfgLUnyWfVoVbD) ![](/files/ja54xj7JQnqgNChdIJiG) Once withdrawal info is created, users can initiate withdrawal. ![](/files/ljAm2WpgkuMMLg6xJb0i) # Payments and Payouts ## Payments The Payments page displays a table with all your payments. By default, it shows payments in descending creation order. ![](/files/lcXnqwN092uYcCE3RqE3) You may choose to sort by a different parameter instead by hovering over any other table header and clicking on the arrow that appears. Clicking it will cycle through sort by ascending, descending, and none/clear sort. ![](/files/rnQPC2O44WX4aAlygafr) You can also choose to narrow down the table data shown by a date range of your choosing via the Date Range picker above the table. ![](/files/bdVwzju1oz182KQbroOE) Status is a filter you can utilize to customize your table view. You may select as few or as many statuses you would like to see on the table. ![](/files/8gye3Rdn4rMP3EJaVqFl) The table updates as you select Status parameters to filter. ![](/files/BGKPgY9Flm7Ag0HwTIoX) The Payouts page displays a table ![](/files/lCpoLn8vcF9UPrao2jgI) # Crypto Conversion AquaPay provides a convenient way to convert the residue amount of Crypto to Fiat in each bill. We provide both UI and API access for the conversion. On AquaPay web portal, go to "Create Conversion" from the sidebar to start the workflow. {% hint style="info" %} Each conversion can only use 1 trading pair. To convert multiple crypto types, please create multiple conversion invoices. {% endhint %} ![](/files/hMmVn86ym4XfhwAMzSSI) Each quote is valid for a limited time, usually around 8 seconds and will automatically refresh until executed. A quote can only be executed when it's valid. Balances used in the conversion invoice will be locked and cannot be used for creating another conversion invoice. ![](/files/adRiaS2eiRTpQ14xoLCt) You can see the conversion invoice history in the sidebar "Conversions" > "History" page. Each conversion item is also shown under the billing record. ![](/files/UxQxBPpjQIZA0OABIgvd) # Address Whitelisting {% hint style="info" %} This page of the documentation details whitelisting for IP Addresses. If you would like to learn to whitelist currency addresses, see [Account Management](/features/account-management) {% endhint %} IP Whitelisting is a security feature to ensure maximum security of your trading account. Using this feature, only IP addresses you specify will be able to access your account on Aquanow services. You can whitelist a maximum of 5 IP addresses To access this feature, go to the user account dropdown at the top right corner of the screen and select "IP Whitelist". ![](/files/4t3cWCKr8zUVckOmasVQ) Within the IP Whitelist page, you can view and edit your whitelisted IP addresses. There are no addresses by default. ![](/files/uuT02ES99eCyD6DJEtlY) Enter the IP address you would like to whitelist. Note that **inputted addresses must be in the IPv4 format.** ![](/files/xKM1P82zW5mIUC6I3HLV) Double-check the address, then confirm the dialog. ![](/files/zE5Hf4uZk0QedHiK1O2X) Now your IP address is whitelisted and appears on the table. You may whitelist additional addresses, up to a maximum of 5 in total. You may also delete addresses from the whitelist. ![](/files/zCXABizyQTqNuMIvRjNs) # CSV Exports On both the Payments and Payouts pages, if you wish to have your table data in CSV form, there is a download button in the top right corner of the screen. Clicking will export and download a .CSV file to your computer. ![](/files/yZdri0v2O3EZbok5KWik) # API Key ## Base URL for API Endpoints AquaPay provides a production environment and a sandbox environment. The API endpoint for the **sandbox** environment is: ``` https://api-staging.aquanow.io ``` The API endpoint for the **production** environment is: ``` https://api.aquanow.io ``` ## Generating API Key For programmatic access or API integration, users can create an API key through the following steps: Go to the "API Keys" section of the navigation panel ![](/files/qHaZlEOH5IYr24HCASZg) Click on "Create New API Key" ![](/files/t7MkooFXU2knLaEjQgHE) ![](/files/YatFJScb45UFiN2ys2GR) # Authorization ## API Authentication Authentication is done using an API key and a secret key. To generate this pair, read [API Setup](/integration-guide/api-setup). As an example, we will use the "/payment/v1/requestPaymentAddress" endpoint to show how to authenticate. This can be used for all endpoints that requires authentication. These are encoded as HTTP headers named: * x-nonce * x-api-key * x-signature ### Code Example {% tabs %} {% tab title="Javascript" %} ```javascript require("isomorphic-fetch"); const crypto = require("crypto"); async function sendRequest() { const apiKey = "YOUR_API_KEY"; const apiSecret = "YOUR_API_SECRET"; const path = "/payment/v1/requestPaymentAddress"; const nonce = Date.now().toString(); const httpMethod = "POST"; const signatureContent = JSON.stringify({ httpMethod, path, nonce, }); const sig = crypto .createHmac("sha384", apiSecret) .update(signatureContent) .digest("hex"); try { const res = await fetch(`https://api-staging.aquanow.io${path}`, { method: httpMethod, headers: { "x-nonce": nonce, "x-api-key": apiKey, "x-signature": sig, }, body: JSON.stringify({ cryptoType: "BTC", fiat: "CAD", fiatReceivable: 5, subaccount: "YOUR_CUSTOM_PAYMENT_ID", }), }); if (res.status !== 200) { throw new Error(`${(await res.json()).message} status ${res.status}`); } const result = await res.json(); console.log("Result: ", result); } catch (error) { console.log("error", error); } } sendRequest(); ``` {% endtab %} {% tab title="PHP" %} ```php $method, 'path' => $endpoint, 'nonce' => (string) $nonce, ]; $json = json_encode($content, JSON_UNESCAPED_SLASHES); $signature = hash_hmac('sha384', $json, $apiSecret); $client = new Client([ 'base_uri' => 'https://api-staging.aquanow.io', 'headers' => [ 'x-nonce' => $nonce, 'x-api-key' => $apiKey, 'x-signature' => $signature, ], ]); try { $response = $client->request('GET', $endpoint, [ 'query' => [ 'startTime' => 1628654316000, 'endTime' => 1628654346000, ], ]); echo $response->getBody(); } catch (RequestException $error) { echo $error ->getResponse() ->getBody() ->getContents(); } catch (\Exception $error) { echo $error->getResponse()->getBody(); } ``` {% endtab %} {% endtabs %} ### Common Auth Errors #### 401 HTTP401 usually happens when invalid auth credentials are in the request auth headers. You will also receive 401 when `nonce` in calculating auth credentials are outdated. #### 403 HTTP403 usually happens when a request is blocked by IP whitelist or an incorrect URL/HTTP method. # Adding Webhook URLs The Webhooks menu allows you to enter a webhook to use with our API. ![](/files/ERe1piuVPohb7W7KIBRw) You can add webhooks for both Payments and Transactions ![](/files/XbexehfoBDznTj2b10Xx) To add your webhook, type in your webhook URL and use the check boxes to select what types of messages you would like to receive. Some selections are already set and not configurable. ![](/files/hlvQ90GjVxc5FmcqUHOR) Once a webhook is added, several actions become available: You may send a test message, edit the webhook's URL, or delete it entirely. ![](/files/wWEmss7ZhcHeS1U49y6n) Sending a test message allows you to test if messages can be sent properly. A success notification will appear if it works. Please check your own webhook to make sure you have received the message. ![](/files/1ryweNZl6p89GfTO2lbO) # Webhooks We offer webhook callbacks for clients that want to be updated when a deposit is detected on-chain or finalized. ## Webhook payload examples {% hint style="info" %} AquaPay guarantees at-least-once delivery of our webhook messages, and to avoid duplicates, you can utilize txHash and adminApproval as deduplication IDs. {% endhint %} {% tabs %} {% tab title="Unconfirmed" %} Unconfirmed webhook is disabled by default. You can enable it on AquaPay web portal "Webhooks" page. ```json { "address": "mzczAqqqNqtozbaT7oJEzYML814Wg7d999", "adminApproval": "UNCONFIRMED", "confirmation": 0, "executableQuantity": 0.00002159, "fiatReceivable": 1, "quantity": 0.00002159, "strategy" : "RFQ", "sourceAddress": "tb1qx3r63vymgvp0ln5na022zzh7cv6xu3rs94g6ca", "subaccount": "deedddff", "symbol": "BTC", "tradePrice": 46319.1759999501, "transactionType": "DEPOSIT", "txHash": "14a8cbac6973374573326ab97891c9fe13eec03143e538e1a3e92987140ab04a", "txId": "3e06c4eb-b134-4a93-a78f-a979e1d3a803", "paymentId": "4618d63b-ea56-4f9f-920a-932faac40c4b", "username": "woojchung" } ``` {% endtab %} {% tab title="Done" %} ```javascript { "quantity": 0.003223, "subaccount": "deedddff", "fiatReceivable": 12.347, "executableQuantity": 0.003223, "txId": "14ea698f-96b6-468d-8b1f-c52a695ee627", "paymentId": "4618d63b-ea56-4f9f-920a-932faac40c4b", "symbol": "ETH", "strategy" : "RFQ", "txHash": "0xf62f9fe6c90e85792fef676ddaa711916d9abb6b6b600e3c5b1d4bdcb1a38ec1", "txTime": 1632204599177, "address": "0xc08377dF1eF026aeb12dcc57D254173CB6b0A1aA", "fiatReceived": 12.347, "transactionType": "DEPOSIT", "tradePrice": 3831.0226, "username": "woojchung", "adminApproval": "DONE" } ``` {% endtab %} {% tab title="Rejected" %} ```json { "quantity": 0.00009989, "sourceAddress": "tb1qwmxjsq283elnzsd306c6h3z08fucyhl565a4s2", "subaccount": "deedddff", "txId": "e09fef5d-6ab4-4da1-bed6-5a7d6416162d", "paymentId": "4618d63b-ea56-4f9f-920a-932faac40c4b", "symbol": "BTC", "strategy" : "RFQ", "txHash": "7f9e94c800079ed7ff71da6d02e16885e9ae39cb8c79473649fb00254f20fe1b", "txTime": 1649259696838, "address": "mtTu1NHfgbWQH2u4iXCfSYnohbQw1w1AJj", "transactionType": "DEPOSIT", "expired": true, "tradePrice": 57045.14521362, "username": "woojchung", "adminApproval": "REJECTED", "reason": "Expired" } ``` {% endtab %} {% tab title="Failed" %} ```javascript { "quantity": 0.00009989, "sourceAddress": "tb1qwmxjsq283elnzsd306c6h3z08fucyhl565a4s2", "strategy": "ACA", "subaccount": "test", "fiatReceivable": 4.3, "txId": "ca03390e-8d72-482b-a95a-946796c46ad8", "symbol": "BTC", "txHash": "72bf9e87407ade9ba38b7584987de66cba8fbb1e7e9bd1964af138_jdeg6i", "address": "mp2HCxb2f69hiGgti5XvWu2Z8yLkoLi6jk", "transactionType": "DEPOSIT", "confirmation": 0, "tradePrice": 43073.6, "username": "deposit_test_user_jdeg6i", "adminApproval": "FAILED", "expired": false, "paymentId": "8ac5c3af-f663-4da1-9683-2d160b3e4e43", "feeModel": "EXPLICIT" } ``` {% endtab %} {% endtabs %} ## Callback parameter values
parameterdescription
ParameterTypeDescription
paymentIdstringBill Id provided by aquapay, can be used for query a bill status or doing conversions
txIdstringDeposit Id provided by AquaPay
addressstringAddress of the deposit
sourceAddressstringSource address of the deposit
adminApproval'UNCONFIRMED'|'DONE' | 'REJECTED' | 'FAILED'

Status of Transaction.

UNCONFIRMED: a deposit is detected and waiting for further confirmation

DONE: Successfully deposited and converted

REJECTED: Successfully deposited but no conversion occurred
FAILED: a deposit is failed on blockchain

executableQuantitynumberThe amount of crypto quantity that can be executed. Not available for "ACA" strategy.
fiatReceivablenumberThe amount of quantity in fiat that is expected. If a user accidentally sends over the value of the quantity accepted, we will never trade above the quantity provided, and thus the fiatReceived will never be higher than the fiatReceivable.
fiatReceivednumberAmount traded to fiat
quantitynumberQuantity (in Crypto) deposited
subaccountstringPayment service provider's user who initiate the deposit request
symbolstringCrypto Symbol
tradePricenumberPrice of Execution
transactionType'DEPOSIT'Type of transaction. Will always be DEPOSIT
txHashstringBlockchain Transaction Hash
txTimenumberTime of transaction confirmation in blockchain
usernamestringYour username
expiredbooleanThe bill is expired
strategystringThe payment strategy of the bill
reasonstringHuman-readable rejected reason for reference only.
# Payment Flow The following is the workflow for the Aquanow payment service which is a two-step process: In stage 1, the user initiates a deposit request to the payment company. The payment company will send an requestPaymentAddress POST method request to Aquanow which will return the price, expiry time, quantity and cryptocurrency deposit information. Stage 2 starts when the user sends cryptocurrency to the deposit address. Once Aquanow has detected the transaction confirmation on the blockchain, Aquanow will convert the deposited cryptocurrency into the destination currency. There are two options available for the payment company to detect if the deposit has occurred: ### Option 1: Webhooks Push Approach (Recommended) ![](/files/9AdtmHfxtsSBevYlDxKO) ### Option 2: Pull Approach ![](/files/QEX3pKGZyXu0pvwniuzX) # Confirmations & Limits The following are the number of confirmations and minimum withdrawal quantity per cryptocurrency. | **Cryptocurrency** | **Confirmations** | **Min Withdrawal** | **Min Conversion Size** | | ------------------ | ----------------- | ------------------ | ----------------------- | | BTC | 1 | 0.001 | 0.0000001 | | BCH | 6 | 0.002 | 0.0000001 | | LTC | 1 | 0.01 | 0.0000001 | | ETH | 10 | 0.02 | 0.0000001 | | USDC | 10 | 100 | 0.01 | | USDT-ERC20 | 10 | 100 | 0.01 | | USDT-TRC20 | 19 | 100 | 0.01 | | SOL | 1 | 0.02 | 0.0000001 | # Testnet and Faucet ## Coin Contract Address
SymbolTestnetContract address
USDTSepolia0xb60B42C095d08776a6ecc9a246180FE37AbA02A5
USDCSepolia0x2eAd10C40f15D33927a3114251733bAE44c9F0E3
USDTShastaTBu65s6R4qBx1eHbiCRjrpD9DV2bD6P76W
## Faucets {% hint style="warning" %} The faucets provided below are not maintained by Aquanow, please use at your own risk. {% endhint %}
SymbolTestnetFaucet
BTC-https://testnet-faucet.com/btc-testnet/
BCH-https://tbch.googol.cash/
LTC-https://testnet-faucet.com/ltc-testnet/
ETHSepoliahttps://sepoliafaucet.com/
USDCSepoliaAsk Aquanow tech support to get test coins
USDTSepoliaAsk Aquanow tech support to get test coins
USDTShastaAsk Aquanow tech support to get test coins
SOLDevnethttps://solfaucet.com/
# Payment API ## General Information {% hint style="danger" %} AquaPay will recycle the generated payment address. Please DO NOT keep it for a prolonged period of time for receiving additional deposits. {% endhint %} ## Create Payment Bill `POST` `https://api.aquanow.io/payment/v1/requestPaymentAddress` This endpoint allows you request a payment address by using a fiat quantity (*fiatReceivable*) to generate the executable price. #### Request Body | Name | Type | Description | | ------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | cryptoType\* | string | Symbol deposited ie. "BTC". Look at Crypto & Currency Support for a full list of supported cryptos. | | fiat\* | string | Designated currency which the cryptocurrency will be converted into. Look at Crypto & Currency Support for a full list of supported fiat. | | fiatReceivable\* | number | Amount (in fiat) you want to receive as a result of payment execution. | | subaccount\* | string | Payment service provider's user who initiate the deposit request. | | networkType | enum | Network Type of `USDT`. `eth` or `tron`. Default to `eth`. | | bech32 | boolean | Defaults to false. If set to true, it will return **bech32 segwit address** for BTC address, or **BCH cash address** for BCH. | | strategy | enum | `"RAI" \| "LMT" \| "ACA"`. See below for more information. | | feeModel | enum | `"SPREAD" \| "EXPLICIT"`. See below for more information | {% tabs %} {% tab title="200 Successfully created using ETH" %} ```javascript { "deposit_address": "0xfbc341964BC644944EDfE51798CEb441260B0CcC", "price": 2994.8982, "quantity": 0.004123, "expiryTime": 1632197603530 } ``` {% endtab %} {% tab title="400 If you provide a networkType that does not exist." %} ```javascript { "message": "Provided network type does not exist" } ``` {% endtab %} {% endtabs %} ## Get Payment `GET` `https://api.aquanow.io/payment/v1/payment` Get all payment bills by time range, address or paymentId. #### Query Parameters | Name | Type | Description | | ----------- | ------ | --------------------------------------------------------------- | | startTime | number | Time in epoch. Required when query for all bills by time range. | | endTime | number | Time in epoch. Must within 90 days of startTime. | | startsAfter | string | Pagination token | | address | string | Query for all bills under an address | | paymentId | string | Query for single bill | {% tabs %} {% tab title="200: OK " %} ```javascript { "data": [ { "quantity": 0.00048385, "paymentId": "1dad9864-a235-47f5-997a-b4674fda3e42", "subaccount": "testing-event-4", "fiatReceivable": 1, "symbol": "ETH", "createdAt": 1662576446318, "fiat": "CAD", "address": "0xaf91e342A29D92C7667D85782C36a0D806529025_ETH", "paymentStatus": "DONE", "updatedAt": 1662576446318, "expirationTime": 1662577646316, "tradePrice": 2066.75820001996, "username": "jeffen", "transactions": [ { "quantity": 0.001, "sourceAddress": "0xf6aCc5f06BCE41860B425bcaDfD7ce5ABcc19ECa", "paymentId": "1dad9864-a235-47f5-997a-b4674fda3e42", "subaccount": "testing-event-4", "fiatReceivable": 1, "executableQuantity": 0.00048385, "txId": "7170e2da-2b68-4abd-bc9e-16dd057e7051", "symbol": "ETH", "txHash": "0xf29ebf7ccb1b9c993ecb49ad1e4641a566af98a3886abda89f723b578eca576e", "createdAt": 1662576607008, "fiat": "CAD", "txTime": 1662576704421, "address": "0xaf91e342A29D92C7667D85782C36a0D806529025", "fiatReceived": 1, "transactionType": "DEPOSIT", "riskLevel": 0, "tradePrice": 2066.75820001996, "username": "jeffen", "adminApproval": "DONE", "quantityReceived": 0.001, "quantityConverted": 0.00048385, "quantityUnconverted": 0.00051615 } ], "summary": { "fiatReceivable": 1, "riskLevel": 0, "quantityReceived": 0.001, "quantityConverted": 0.00048385, "quantityUnconverted": 0.00051615, "quantityConvertible": 0.00051615, "fiatReceived": 1, "fiatConverted": 0 } } ], "pagination": { "startsAfter": "eyJ0eElkIjoiNTg2YjZiZWUtNjAzMy00OThjLTlkMzEtZjQyYTBmNTAzMDMxIn0=" } } ``` {% endtab %} {% endtabs %} ## Payment Strategy #### Default Request parameter: `"RFQ"`. Applicable for all supported coins. Received crypto deposits are converted to fiat when the bill is within the expiry time. #### Receive As Is Request parameter: `"RAI"`. Applicable for all supported coins. Received crypto deposits are not converted to fiat. #### Always Convert All Request parameter: `"ACA"`. Applicable for all supported coins. All received crypto will be converted by RFQ or market order to fiat depending on the bill expiry time. #### Limit Price Request parameter: `"LMT"`. Only applicable to stablecoins, i.e. `USDC` and `USDT` as a risk factor. Received crypto deposits will be converted to fiat only when the guaranteed trade price in bill is better than the user-configured limit price. Crypto deposits received after the bill expiry time are not converted to fiat. {% hint style="info" %} Unconverted payments received through the RAI and LMT strategies are subject to a transaction fee. {% endhint %} ## Fee Model #### Default Request parameter: `"SPREAD"`. Service fee is charged by spread. #### Explicit Fee Request parameter: `"EXPLICIT"`. Service fee is charged by crypto amount from the conversion. Not affecting non-conversion transactions. Not supported by `ACA` strategy market order yet. ## Supported Network Types For symbols that support multiple networks, please specify `networkType` parameter in request body. If you provide a network type for a symbol that is NOT USDT, a **400 HTTP** error will be thrown with the response. | CryptoType | NetworkType | Description | | ---------- | --------------- | ---------------- | | USDT | `eth` (Default) | Ethereum network | | USDT | `tron` | Tron network | # Conversion API API specs for conversion workflow, for web portal access, please see [here](/features/crypto-conversion). ## Get conversions `GET` `https://api.aquanow.io/payment/v1/conversion` Get conversion history by ID or time range. #### Query Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ----------------------------------------- | | invoiceId\* | String | | | startTime\* | String | ISO 8601 format | | endTime | String | ISO 8601 format. Default to request time. | {% tabs %} {% tab title="200: OK " %} ```javascript [ { "quantity": 54.692493, "baseSymbol": "USDC", "status": "CANCELLED", "created": "2022-06-24T23:50:23.486Z", "items": [ { "txId": "f473123d-a0c1-4a25-a713-2c5ecab27bfa", "address": "0x0aE90a043419DAe46774Ba067263202c1a0F60FF", "quantity": 52.461662, "subaccount": "usdc-5" }, { "txId": "948bf813-e055-4e24-be26-5ead961f1fd2", "address": "0x1e4622932738763107E949e011167176F14C5327", "quantity": 2.230831, "subaccount": "usdc-4" } ], "quoteSymbol": "CAD", "username": "jeffen", "side": "SELL", "invoiceId": "f81123c8-2edd-4f29-88e7-6da5f855e48c", "type": "CONVERSION" } ] ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found Only for invoiceId response" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} ## Create a conversion `POST` `https://api.aquanow.io/payment/v1/conversion` Create a conversion invoice by passing conversion info and conversion items(addresses of bills) #### Request Body | Name | Type | Description | | --------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | | baseSymbol\* | String | Crypto to convert | | quoteSymbol\* | String | Fiat to receive | | quantity\* | Number | Total crypto quantity to convert | | items\* | Array<{paymentId: string}> | An array of object that contains `paymentId` of each bills. They must have the same `baseSymbol` and `quoteSymbol` | {% tabs %} {% tab title="200: OK " %} ```javascript { "invoiceId": "1663abe9-509c-4e0a-ab0a-aa340cbe7340", "status": "CREATED", "items": [ { "txId": "72302a49-6948-4217-9131-534bec20cc4c", "quantity": 52.461662, "subaccount": "aq-3578-usdc-5", "address": "0x11182D6C867B17c6BCE7a2d5711C33a0B61621C9" }, { "txId": "fcfdc253-cc05-4121-a2be-ab3e77323128", "quantity": 2.230831, "subaccount": "aq-3578-usdc-4", "address": "0x693eDfb2352FE1e3a6D1ce95291c30FCc4b5990C" } ], "username": "jeffen", "baseSymbol": "USDC", "quoteSymbol": "CAD", "side": "SELL", "quantity": 54.692493 } ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} ## Cancel a conversion `DELETE` `https://api.aquanow.io/payment/v1/conversion` #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | invoiceId\* | String | | {% tabs %} {% tab title="200: OK " %} ```javascript { // Response } ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} ## Quote a conversion `POST` `https://api.aquanow.io/payment/v1/conversion/quote` #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | invoiceId\* | String | | {% tabs %} {% tab title="200: OK " %} ```javascript { "quoteId": "768b49f3-5359-471d-812f-398c0544e646", "quoteTime": 1656191311136, "expireTime": 1656191319136, "symbol": "USDC-CAD", "side": "sell", "receiveCurrency": "CAD", "receiveQuantity": 70.4001769896, "deliverCurrency": "USDC", "deliverQuantity": 54.692493, "price": 1.2872 } ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} ## Execute a conversion `POST` `https://api.aquanow.io/payment/v1/conversion/execute` #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | invoiceId\* | String | | {% tabs %} {% tab title="200: OK " %} ```javascript { "invoiceId": "1663abe9-509c-4e0a-ab0a-aa340cbe7340" } ``` {% endtab %} {% tab title="400: Bad Request " %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} # Transaction API ## Get User Balance `GET` `https://api.aquanow.io/users/v1/userbalance` Get user balances by symbol. #### Query Parameters | Name | Type | Description | | ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | | symbol\* | string | Fetches the user balance for the symbol provided. If symbol is not specified in query parameters, it fetch all user balances | {% tabs %} {% tab title="200: OK " %} ```javascript // https://api.aquanow.io/users/v1/userbalance?symbol=BTC { "pendingTransfer": 0, "totalBalance": 0.00500797, "availableBalance": 0.00500797, "symbol": "BTC", "updatedAt": 1569964868574, "depositAddress": "-" } ``` {% endtab %} {% endtabs %} ## Get Transactions `GET` `https://api.aquanow.io/accounts/v1/transaction` GET transaction records using one of the query parameters below. #### Query Parameters | Name | Type | Description | | --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- | | startTime | number | timestamp in `ms`, MUST be sent with endTime. | | endTime | number | timestamp in `ms`, MUST be sent with startTime. | | address | string | Specify the address to grab transactions associated with the address. You can optionally add startTime and endTime as well | | txId | string | GET single transaction via txId | | txHash | string | query all transactions with the same txHash | | transactionType | enum | `DEPOSIT`, `WITHDRAW` or `CONVERSION` | | limit | number | default: `100`; max: `1000` | {% tabs %} {% tab title="200: OK " %} ```javascript [ { "quantity": 100, "isAutopilotAddress": false, "bankInfo": { "symbol": "CAD", "institutionNumber": "in", "beneficiaryName": "bn", "transitNumber": "tn", "verified": true, "swiftCode": "sw", "bankName": "bn", "label": "cadWithdrawTest", "accountNumber": "an", "beneficiaryAddress": "ba", "bankAddress": "ba" }, "txId": "05468a4c-1c88-4b7e-ae96-9a216030d7c8", "symbol": "CAD", "createdAt": 1663620355631, "address": "-", "transactionType": "WITHDRAW", "freeOrNot": true, "updatedAt": 1663620355631, "networkFee": 0, "username": "jeffen", "itemDateTime": 1663620355630, "adminApproval": "PROCESSING" } ] ``` {% endtab %} {% endtabs %} ## Create Withdrawal `POST` `https://api.aquanow.io/accounts/v1/transaction` A transaction of transferring crypto or fiat from Aquanow to an external address (a wallet, an exchange, or a bank account). #### Request Body | Name | Type | Description | | ------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------- | | symbol\* | string | Currency you wish to withdraw, in uppercase. | | address\* | string | Address you wish to withdraw to for **crypto withdrawal** | | addressId | string | Banking information you are withdrawing to for **fiat withdrawal**. Only required if you have multiple banking information stored | | quantity\* | number | Quantity you wish to withdraw. Must have sufficient funds to be able to withdraw. | | transactionType\* | string | Type of transaction. Currently only WITHDRAW is supported. | | networkType | "eth" \| "tron" | Only required when you withdraw from USDT | {% tabs %} {% tab title="200: OK " %} ```javascript { "itemDateTime": 1611713964494, "address": "CD7iJgfC1BF1a26LuTxAuQ35E5TSPsTsDr", "networkFeeAqua": 0, "quantity": 0.005, "bankInfo": {}, "txId": "373a49c7-b829-43de-a4dd-5462723d63e3", "symbol": "BTC", "tag": "withdrawal_address", "username": "pratikstaging", "fullNodeEnabled": true, "networkFee": 0.0001, "freeOrNot": false, "transactionType": "WITHDRAW", "isAutopilotAddress": false, "adminApproval": "PROCESSING", "createdAt": 1611713964495, "updatedAt": 1611713964495 } ``` {% endtab %} {% endtabs %} ## Get payouts & deposits `GET` `https://api.aquanow.io/payment/v1/payout` Get withdrawals and non-payment deposits #### Query Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------ | | startTime\* | number | Time in `ms` | | endTime | number | Time in `ms`. Default to now. | | txId | string | Get single record by transaction id | | startsAfter | string | Pagination token, only returns when there's more data available for the query. | {% tabs %} {% tab title="200: OK " %} ```javascript { "data": [ { "quantity": 20, "txId": "e7e234ee-4b53-405d-bcdf-d01c855cd1f1", "symbol": "USDT", "createdAt": 1662492193696, "username": "jeffen", "address": "0x3AD7847CfD5E9DB721E454c8D13506aBc294F642", "transactionType": "DEPOSIT", "adminApproval": "DONE" }, { "quantity": 100, "txId": "22c78fd3-702a-4fa4-ac11-f5c616ccf9b5", "symbol": "USD", "createdAt": 1662591787879, "username": "jeffen", "transactionType": "DEPOSIT", "adminApproval": "DONE" } ], "pagination": { "startsAfter": "eyJ0eElkIjoiNTg2YjZiZWUtNjAzMy00OThjLTlkMzEtZjQyYTBmNTAzMDMxIn0=" } } ``` {% endtab %} {% endtabs %} ### Transaction Response Fields | Field Name | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | address | The destination address of the transaction | | adminApproval |

Status of transaction.

UNCONFIRMED: Tx detected but not yet deposited (as there is not enough confirmations

PROCESSING: Tx is in transit and will be processed shortly

REJECTED: Tx is deposited but not executed to fiat (for autopilot/aquapay transactions)

DONE: Transaction has been processed.

| | bankInfo | If FIAT, bankInfo | | createdAt | Date Transaction was created in ms | | isAutopilotAddress | Whether or not this transaction is an autopilot (NOTE: Aquapay transactions are autopilot addresses) | | itemDateTime | Date of transaction | | networkFeeAqua | Blockchain NetworkFee, if applicable | | quantity | Size of transaction | | symbol | Currency symbol i.e BTC or USD | | tag | Tag set by you to differentiate transactions | | transactionType | `WITHDRAW`, `DEPOSIT` or `CONVERSION` | | txId | Uuid of transaction | | updatedAt | Date Transaction was last updated in ms | | username | Username | # Scenario Examples This section will highlight some of the scenarios that result in a change of transaction status. Your operations team can track and manage the payment history and payouts based on the messages from the callback URL, getCompletedPayment API endpoints or through the Aquapay web portal. ### Table of Contents 1. [User does not send cryptocurrency to the deposit address after initiating payment request](#scenario-1) 2. [User sends cryptocurrency within the payment required time period](#scenario-2) 3. [User sends cryptocurrency after the payment request is expired](#scenario-3) 4. [User sends cryptocurrency with quantity larger than deposit limit](#scenario-4) 5. [AML/Risk Check fails for the deposit transaction](#scenario-5) 6. [Price moved beyond our volatility threshold](#scenario-6) #### Scenario 1 > ### User does not send cryptocurrency to the deposit address after initiating payment request **Condition**\ End-user did not send the cryptocurrency to the corresponding deposit address.\ \ **Result** \ Since there is no transaction, no message is sent to the webook URL and the user balance does not change.\ \ **Action Required**\ None #### Scenario 2 > ### User Sends Cryptocurrency Within The Payment Required Time Period **Condition**\ End-user's cryptocurrency transfer was broadcasted onto the blockchain to the corresponding deposit address within the required deposit time.\ \ **Result** \ Once the transaction reaches the required number of confirmations, Aquapay will accept the deposit and convert the cryptocurrency to fiat with the price associated with this deposit.\ \ **Action Required**\ Completed transaction message is sent through the webook URL and clients can use the message to update their systems accordingly. #### Scenario 3 > ### User Sends Cryptocurrency After The Payment Request Is Expired **Condition**\ End-user's cryptocurrency transfer was broadcasted onto the blockchain to the corresponding deposit address after the required deposit time.\ \ **Result** \ Cryptocurrency deposit is accepted by Aquapay after required confirmation, but the cryptocurrency will be deposited to your balance without converting to fiat.\ \ **Action Required**\ Rejected transaction message is sent through the webook URL and clients can use the message to update their system accordingly. #### Scenario 4 > ### User Sends Cryptocurrency With Quantity Larger Than Deposit Limit **Condition**\ End-user's cryptocurrency transfer was broadcasted onto the blockchain to the corresponding deposit address after the required deposit time with quantity larger than the deposit limit. Note that the deposit limit is configurable and there is no limit by default.\ \ **Result** \ Cryptocurrency deposit is accepted by Aquapay after required confirmation, but the cryptocurrency will be deposited to the user balance and will not be converted to fiat.\ \ **Action Required**\ Rejected transaction message is sent through the webook URL and clients can use the message to update their system accordingly. #### Scenario 5 > ### AML / Risk Check Fails for the Deposit Transaction **Condition**\ We monitor any incoming deposit using our in-house risk check system and the transaction fails our risk measure.\ \ **Result** \ Cryptocurrency deposit is accepted by Aquapay after required confirmation, but the cryptocurrency will be deposited to the user balance and will not be converted to fiat.\ \ **Action Required**\ Rejected transaction message is sent through the webook URL and clients can use the message to update their system accordingly and we recommend to ask user to provide a refund address and send the cryptocurrency back. #### Scenario 6 > ### Price Moved Beyond Our Volatility Threshold **Condition**\ While Aquapay locks the trading price to give user enough time to transfer the cryptocurrency, during the high volatility period if the price when the transaction is confirmed is 2.5% lower than the locked price, it will hit the volatility threshold.\ \ **Result** \ Cryptocurrency deposit is accepted by Aquapay after required confirmation, but the cryptocurrency will be deposited to the user balance and will not be converted to fiat.\ \ **Action Required**\ Rejected transaction message is sent through the webook URL and clients can use the message to update their system accordingly. # FAQs
What happens if a transaction is double-spent? We only consider a transaction valid when it reached the confirmation threshold. Double-spent transactions won't be considered part of the payment.
What happens if a late payment? AquaPay guarantees the trade price for 20 minutes after a deposit address is created. Any crypto deposit received after 20 minutes will not be converted to fiat and will reside in the merchant's wallet balance. Merchants can then choose to payout the crypto or convert it. see [Scenario Examples](/common-scenarios-and-faqs/scenario-analysis#scenario-3) for more details.
In what scenario is a bill overpaid? A bill is considered overpaid if the received fiat amount is larger than the invoiced fiat amount. There are 2 scenarios that can cause a bill to be overpaid: 1\. Customer made multiple deposits within 20 minutes, each in an amount less than the invoiced amount but in total more than required, these deposits will be converted to fiat and in total the received fiat can exceed the invoiced amount. 2\. Merchant converted residual crypto in a bill. see [Scenario Examples](/common-scenarios-and-faqs/scenario-analysis) for more details.
What if customer deposited more than invoiced amount? For every single deposit within expiration time, AquaPay only converts no greater than the invoiced crypto amount to fiat. For example, customer Joe is invoiced for 1 ETH but made two deposits of 1.2 ETH each. AquaPay only converts 2 ETH, and 0.4 ETH will reside in the merchant's wallet balance. see [Scenario Examples](/common-scenarios-and-faqs/scenario-analysis#scenario-4) for more details.
What testnets are used for Ethereum and Tron network? Starting 2022-10-06, we switched to **Goerli** from Ropsten testnet due to its deprecation in 2022 Q4 (). We use **Shasta** for Tron network. For more coin assets information, please refer to [Testnet and Faucet](/integration-guide/testnet-and-faucet)
Can I keep the generated payment address for future usage? We strongly discourage this type of usage because AquaPay will recycle the generated addresses at a future point in time. Reusing the generated address may result in missing funds.
Can I keep the received crypto without conversion? Yes! By specifying `strategy` parameter in request body in requestPaymentAddress endpoint, you can choose whether or when to convert the received crypto. Please see [here](/api-endpoints/api-reference#payment-strategy-preview) for more information.