On Ramp Integration Guide
Seamless conversion between fiat and crypto - end to end technical integration guide
Introduction
zerohash's On Ramp product allows any business to quickly launch an experience that allows their end customers to convert fiat to crypto.
Definitions
| Term | Definition |
|---|---|
| Platform | The company that's in contract with zerohash and directly interacts with zerohash's APIs or SDKs. |
| End Customer | The end retail customer that has a direct relationship with the Platform and zerohash. |
High Level Flow
- Submit End Customer
- Query End Customer
- Fund Float Account
- Get Assets
- Get Quote
- Execute Quote
- Query Withdrawal
- Network Fee Procedures
- Email Receipt Requirements
- End of Day Settlement
Initial Setup
The Platform will need to onboard its business to the zerohash platform. They then need to add additional users, create API keys, and whitelist IP addresses. See instructions here.
1. Submit End Customer
Once API keys are created and approved, the Platform can begin to integrate to the API. For the following examples, we’ll assume the Platform's platform code is PLAT01.
Natural Person
Example request - POST /participants/customers/new
{
"request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone_number": "+19545551234",
"address_one": "1 Main St.",
"address_two": "Suite 1000",
"city": "Chicago",
"zip": "12345",
"jurisdiction_code": "US-IL",
"date_of_birth": "1985-09-02",
"citizenship_code": "US",
"tax_id": "123456789",
"risk_rating": "low",
"kyc": "pass",
"kyc_timestamp": 1630623005000,
"sanction_screening": "pass",
"sanction_screening_timestamp": 1630623005000,
"idv": "pass",
"liveness_check": "pass",
"signed_agreements": [
{
"type": "user_agreement",
"region": "us",
"signed_timestamp": 1603378501286
}
]
}Non-natural person
To submit a non-natural person customer, use the POST /participants/entity/new endpoint. Example request:
{
"request_id": "b7e4c2a1-9d3f-4a68-8c15-2f6d0e9a4b73",
"platform_code": "PLAT01",
"entity_name": "Entity A",
"legal_name": "Entity A",
"contact_number": "+15553765432",
"website": "https://entitya.com",
"date_established": "2020-01-15",
"entity_type": "llc",
"address_one": "1 Main St.",
"address_two": "Suite 1000",
"city": "Chicago",
"postal_code": "12345",
"jurisdiction_code": "US-IL",
"tax_id": "883987654",
"id_issuing_authority": "US",
"risk_rating": "low",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"signed_timestamp": 1603378501286,
"submitter_email": "[email protected]",
"control_persons": [
{
"name": "Jane Smith",
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]",
"address_one": "1 Main St.",
"city": "Chicago",
"postal_code": "12345",
"jurisdiction_code": "US-IL",
"citizenship_code": "US",
"date_of_birth": "1985-06-15",
"tax_id": "123456789",
"id_number_type": "ssn",
"id_number": "123456789",
"id_issuing_authority": "US",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"control_person": 1,
"kyc": "pass",
"kyc_timestamp": 1603378501286
}
],
"beneficial_owners": [
{
"name": "Jane Smith",
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]",
"address_one": "1 Main St.",
"city": "Chicago",
"postal_code": "12345",
"jurisdiction_code": "US-IL",
"citizenship_code": "US",
"date_of_birth": "1985-06-15",
"tax_id": "123456789",
"id_number_type": "ssn",
"id_number": "123456789",
"id_issuing_authority": "US",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"beneficial_owner": 25,
"kyc": "pass",
"kyc_timestamp": 1603378501286
}
],
"signed_agreements": [
{
"type": "user_agreement",
"region": "us",
"signed_timestamp": 1603378501286
}
]
}Note: The response contains a participant_code for the End Customer. This uniquely identifies the End Customer indefinitely and should be used in subsequent API calls where applicable. We’ll use CUST01 as the participant_code throughout the examples.
You can make your requests idempotent by using the request_id field. If a subsequent call is made with a previously used request_id, then the request would fail with an error code 400, error message “requestID already used with different participant data”.
If you fail to indicate that the End Customer has agreed to the user agreement, in the signed_agreements object shown above, future API calls will fail.
There may be situations where the Platform is restricted from submitting Customers who reside in non-permitted jurisdictions. The Platform will receive an error that looks like:
{
"errors": [
"The submitting platform is not allowed to operate in the participant's resident state",
"participant is not in an allowed jurisdiction"
]
}See more detail on permitted jurisdictions here.
The preferred approach is for the Platform to not allow customers to onboard on their side (through a feature flag, for example). However, if a request with a Customer in a blocked jurisdiction does get submitted to zerohash via API, the Platform should fail gracefully and display a descriptive error message on-screen.
2. Query End Customer
The Platform can query the End Customer via the GET /participants/{email} endpoint or the Platform can query all End Customers via the GET /participants endpoint.
3. Fund Fiat Accounts
There are 3 types of fiat accounts needed for this flow:
- Float Account: The account that will fund real-time on ramp transactions. On ramp transactions will fail if the balance in this account is insufficient.
- Settlement Reserve Account: a buffer that covers the gap between what the PSP sends and what the Platform owes at end-of-day settlement.
- Settlement Account: The account that will be credited once a day in order to complete daily settlement. The deposit into this account will be initiated by the Payment Service Provider.
NoteIf you don't use an external PSP (ie, you are the PSP) to process the fiat leg of the transaction, the Settlement Account is used. If you use an external PSP, Settlement Accounts are not in scope for your integration.
For the following examples, we’ll assume Platform's platform code is PLAT01.
The Platform will fund each of the above accounts by sending fiat to the proper bank account, tagging each wire with a memo equal to the Platform's participant_code. Including the wire memo means that we can auto-credit the correct account when we receive the wire/ACH.
Here are the account details:
| Float Account | Settlement Reserve Account | Settlement Account | |
|---|---|---|---|
| Participant code | 00SCXM | [Platform's participant code] | [Platform's participant code] |
| Account group | [Platform's participant code] | [Platform's participant code] | [Platform's participant code] |
| Account label | general | settlement_reserve | general |
| Account type | Available | Available | Available |
| Asset | USD | USD | USD |
| Wire Memo | PLAT01 - FLOAT | PLAT01 - RESERVE | PLAT01 - SETTLEMENT |
For the example, let's say the Float Account is funded with $50,000 and the Settlement Reserve Account is funded with $25,000:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $50,000 | (+$50,000) |
| Settlement Reserve Account | USD | $25,000 | (+$25,000) |
Note: For the Wire Memo, some payment providers don't support a fixed memo for the wire or ACH. In these cases please reach out to your ZH contact so we can investigate alternatives.
In Cert, your platform will be pre-funded with Float account funds.
4. Get Assets
In order to know which assets are supported, the Platform can query the GET /assets. If "rfq_liquidity_enabled": true, then it is supported
5. Get Quote
The Platform will now get the initial quote via the POST /convert_withdraw/rfq endpoint:
{
"participant_code" : "CUST01",
"side" : "buy",
"underlying" : "BTC",
"quoted_currency" : "USD",
"total" : "20",
"withdrawal_address" : "2N8PYGKSQRpHa5VDNZ4iLwxi5crpRWb3TR1"
}Response:
{
"message": {
"request_id": "64f34a8d-f5f5-4e37-b01d-7c6814aed4bc",
"participant_code": "CUST01",
"quoted_currency": "USD",
"side": "buy",
"quantity": "0.00087097",
"price": "22962.90",
"quote_id": "5aaaa8af-5d0c-4d55-868b-b56ea19a5443",
"expire_ts": 1661449335103,
"account_group": "00SCXM",
"withdrawal_address" : "2N8PYGKSQRpHa5VDNZ4iLwxi5crpRWb3TR1",
"account_label": "general",
"obo_participant": {
"participant_code": "CUST01",
"account_group": "PLAT01",
"account_label": "general"
},
"network_fee_notional": "1.50",
"network_fee_quantity": "0.00001",
"total_notional": "21.5",
"underlying": "BTC",
"asset_cost_notional": "20"
}
}Note:
fee_inclusive= true can be enacted to ensure that the End Customer spends a maximum oftotaland the fees will be deducted from there- Typically for on ramps the quote length is 30 seconds, although this is configurable
6. Execute Quote
The platform will then execute a POST /convert_withdraw/execute call using the quote_id from the response above. Example Response:
{
"message": {
"request_id": "945c41ba-c06e-4e69-aaf6-ea27cb7c75b2",
"quote": {
"request_id": "7a8a8526-3614-4373-9ab4-0069dc643109",
"participant_code": "CUST01",
"quoted_currency": "USD",
"side": "buy",
"quantity": "0.00087097",
"price": "22962.90",
"quote_id": "dc179192-5bdf-41f2-9ffa-badb1396a0a7",
"expire_ts": 1568311649602,
"account_group": "GRP001",
"account_label": "general",
"obo_participant": {
"participant_code": "CUST01",
"account_group": "PLAT01",
"account_label": "general"
},
"network_fee_notional": "1.50",
"network_fee_quantity": "0.00001",
"total_notional": "21.5",
"underlying": "BTC",
"asset_cost_notional": "20",
"withdrawal_address": "2N8PYGKSQRpHa5VDNZ4iLwxi5crpRWb3TR1",
"payment_processor": {
"name": "payment processor name",
"id": "payment processor id"
},
"spread_notional": ".22",
"spread_bps": "100",
"withdrawal_request_id": "ea97133e-ab15-4c86-86c1-86671b8420nr"
},
"trade_id": "ba97133e-ab15-4c86-86c1-86671b8420bc",
"status": "Completed"
}
}Note: After this, fiat is being taken from the float account, a trade is being created and settled, and an automatic and immediate on-chain transfer is being sent to the withdrawal_address
7. Query Withdrawal
When monitoring a withdrawal, the Platform can query the GET /withdrawals/requests/Dea97133e-ab15-4c86-86c1-86671b8420nr endpoint.
Response:
{
"id":"Dea97133e-ab15-4c86-86c1-86671b8420nr",
"withdrawal_account_id": 152089,
"participant_code": "CUST01",
"account_group": "PLAT01",
"account_label": null,
"requestor_participant_code": "PLAT01",
"asset": "BTC",
"requested_amount": "20",
"settled_amount": "20",
"gas_price": null,
"status": "SETTLED",
"on_chain_status": "PENDING",
"client_withdrawal_request_id": "zh_withdrawal_17845eeffd5f71abaa85e9722e76c931a",
"requested_timestamp": 1659542191772,
"transaction_id": "3899526c5f986297d3b2ba29f2c4c8b0fb486bef2fc76f7c11aae2b1faf3fe76",
"input_data": null,
"fee_amount": 0.00001,
"quoted_fee_amount": 0.00001
} | Parameter | Description |
|---|---|
| status | The zerohash internal settlement status.
|
| on_chain_status | The blockchain status.
|
| transaction_id | The on-chain transaction hash, useful to display out to customers so that they can follow the transaction if they wish. |
8. Network Fee Procedures
The Platform will be paying for the network fee associated with any on ramp transactions. There are 2 options:
- Fund the network fee account. Account details:
- participant_code: PLAT01 (the Platform's participant_code)
- account_group: PLAT01
- account_label: network_fee
- asset: USD
All network fees will be paid out of this account in real-time
- Don’t fund the network fee account. This account will build up a payable balance
zerohash will add the amount of the payable balance on this account to the end-of-month invoice, coupling it with the on ramp usage activity amount due.
9. Email Receipt Requirements
zerohash requires that the End Customer receives an email receipt for each transaction. We also insist that the email contain:
- Certain fields and values, which can be obtained using our API
- Adequate support contact information
Fields
Here are the required field names and their associated API fields:
| Email Receipt Field Name | Description | Example | API Location |
|---|---|---|---|
| Order Number | Unique order identifier | 9a738372-0855-4b25-8c65-5de0aa858b8b | trade_id from GET /trades |
| Order Type | The type of order | On ramp Transaction | N/a, can hard-code to "On Ramp Transaction" |
| Transmission Amount | The transmission amount for the transaction, in quoted currency terms | $10 | total POST /convert_withdraw/rfq or POST /convert_withdraw/execute response |
| Amount Received by End Customer | The amount of the underlying crypto received by the End Customer | 10 USDC | quantity POST /convert_withdraw/rfq or POST /convert_withdraw/execute response |
| Fees | Any added fee values included in the transaction. If there are no fees, then this needs to be expressly stated. This includes processing fees (ie, a fee assessed by the Platform to the End Customer) or blockchain network fees. | "$0", "1.99", "$0 Fees", or "No Fees" |
|
| On-Chain Transaction ID | Transaction Hash on the Blockchain for the transaction | "0x9cb5289c1896a48594f9ed278599caefbc05c9a3cefc2755b7eff8dac8165445" | transaction_id from GET /withdrawals/requests/{withdrawal_request_id}Use withdrawal_request_id from POST /convert_withdraw/execute response to make the above call. |
| Date/Time | Date and timestamp of the transaction transmission (meaning the time that the fiat was converted and settled into crypto within the zerohash system) | 2024-10-11 18:38:00 | settled_timestamp from GET /trades |
10. End of Day Settlement:
Platforms will typically use a Payment Service Provider (PSP) to process the USD leg of the transaction. PSPs will be required to settle with zerohash on a daily basis (excluding weekends and holidays). PSPs will typically withhold both 1) chargebacks and 2) PSP fees. As a result, zerohash will receive a settlement amount that is less than the Net Delivery Obligation (NDO) - in this example the NDO is $500. To compensate for this, zerohash will sweep funds from the Settlement Reserve Account to the Settlement Account, completing end of day settlement.
Here are the account changes after the PSP's wire lands at zerohash:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $49,500 | |
| Settlement Reserve Account | USD | $25,000 | |
| End Customer Account | USDC | 0 | |
| Platform USDC Account | USDC | 0 | |
| Settlement Account | USD | $497.5 | +$497.5 |
In order to get the Settlement Account to the correct amount (500), zerohash will initiate a transfer from the Settlement Reserve Account to the Settlement Account:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $49,500 | |
| Settlement Reserve Account | USD | $24,997.5 | (-$2.5) |
| End Customer Account | USDC | 0 | |
| Platform USDC Account | USDC | 0 | |
| Settlement Account | USD | $500 | +$2.5 |
Once the NDO has been met, zerohash will automatically settle the $500 to the Float Account:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $50,000 | +$500 |
| Settlement Reserve Account | USD | $24,997.5 | |
| End Customer Account | USDC | 0 | |
| Platform USDC Account | USDC | 0 | |
| Settlement Account | USD | $0 | -$500 |
zerohash B.V. (EU entity)The following steps should be followed if you're onboarding a Customer to zerohash B.V. (the EU entity):
Base URL changeFor EU API calls, use the following base URL: https://api.zerohash.eu
Introduction
zerohash's On Ramp product allows any business to quickly launch an experience that allows their end customers to convert fiat to crypto.
Definitions
| Term | Definition |
|---|---|
| Platform | The company that's in contract with zerohash and directly interacts with zerohash's APIs or SDKs. |
| End Customer | The end retail customer that has a direct relationship with the Platform and zerohash. |
High Level Flow
- Submit End Customer
- Query End Customer
- Fund Float Account
- Get Assets
- Get Quote
- Execute Quote
- Query Withdrawal
- Network Fee Procedures
- Email Receipt Requirements
- End of Day Settlement
Initial Setup
The Platform will need to onboard its business to the zerohash platform. They then need to add additional users, create API keys, and whitelist IP addresses. See instructions here.
1. Submit End Customer
Once API keys are created and approved, the Platform can begin to integrate to the API. For the following examples, we’ll assume the Platform's platform code is PLAT01.
Submit customer
Natural Person
Example request - POST /participants/customers/new
{
"request_id": "c3d5e7f9-1a2b-4c6d-8e0f-3a5b7c9d1e2f",
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone_number": "+33612345678",
"date_of_birth": "1985-09-02",
"address_one": "123 Rue de Rivoli",
"city": "Paris",
"postal_code": "75001",
"jurisdiction_code": "FR-75",
"citizenship_code": "FR",
"tax_residence": {
"jurisdiction_code": "FR-75"
},
"tax_id": "1234567890123",
"id_number_type": "passport",
"id_number": "12AB34567",
"id_issuing_date": "2020-12-16",
"id_expiration_date": "2030-12-15",
"employment_status": "full_time",
"industry": "electronics",
"source_of_funds": "salary",
"savings_and_investments": "under_10000",
"risk_rating": "low",
"kyc": "pass",
"kyc_timestamp": 1603378501286,
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"idv": "pass",
"liveness_check": "pass",
"signed_timestamp": 1603378501286,
"self_certification_timestamp": 1667504636159,
"signed_agreements": [
{
"type": "user_agreement",
"region": "eu",
"signed_timestamp": 1603378501286
}
]
}Non-natural person
To submit a non-natural person customer, use the POST /participants/entity/new endpoint. Example request:
{
"request_id": "d4e6f8a0-2b3c-4d7e-9f1a-4b6c8d0e2f3a",
"entity_type": "corporation",
"platform_code": "PLAT01",
"entity_name": "Entity Name",
"legal_name": "Legal Name",
"contact_number": "+33140123456",
"date_established": "2015-09-02",
"address_one": "123 Rue de Rivoli",
"city": "Paris",
"postal_code": "75001",
"jurisdiction_code": "FR-75",
"country": "FRA",
"tax_id": "12345678901",
"id_issuing_authority": "FR",
"id_number": "549300TRWGQX5XMHYZ82",
"id_number_type": "legal_entity_identifier",
"chamber_of_commerce_number": "123456789",
"activity_locations": ["FR", "PT"],
"entity_source_of_funds": "crypto_activities",
"expected_annual_volume": "over_500k",
"declaration_no_foreseeable_changes": true,
"reason_for_business_relationship": "Digital asset custody and trading services for institutional clients",
"risk_rating": "low",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"signed_timestamp": 1603378501286,
"submitter_email": "[email protected]",
"signed_agreements": [
{
"type": "user_agreement",
"region": "eu",
"signed_timestamp": 1603378501286
}
],
"control_persons": [
{
"name": "Jane Smith",
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]",
"phone_number": "+33612345678",
"address_one": "123 Rue de Rivoli",
"city": "Paris",
"postal_code": "75001",
"jurisdiction_code": "FR-75",
"date_of_birth": "1985-09-02",
"citizenship_code": "FR",
"tax_id": "1234567890123",
"id_number_type": "passport",
"id_number": "12AB34567",
"id_issuing_authority": "FR",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"kyc": "pass",
"kyc_timestamp": 1603378501286
}
],
"beneficial_owners": [
{
"name": "Jane Smith",
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]",
"phone_number": "+33612345678",
"address_one": "123 Rue de Rivoli",
"city": "Paris",
"postal_code": "75001",
"jurisdiction_code": "FR-75",
"date_of_birth": "1985-09-02",
"citizenship_code": "FR",
"tax_id": "1234567890123",
"id_number_type": "passport",
"id_number": "12AB34567",
"id_issuing_authority": "FR",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286,
"kyc": "pass",
"kyc_timestamp": 1603378501286
}
],
"board_members": [
{
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]",
"address_one": "123 Rue de Rivoli",
"city": "Paris",
"postal_code": "75001",
"jurisdiction_code": "FR-75",
"date_of_birth": "1985-09-02",
"citizenship_code": "FR",
"place_of_birth_country_code": "FR",
"place_of_birth_name": "Paris",
"tax_id": "1234567890123",
"id_number_type": "passport",
"id_number": "12AB34567",
"id_issuing_authority": "FR",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1603378501286
}
]
}Note: The response contains a participant_code for the End Customer. This uniquely identifies the End Customer indefinitely and should be used in subsequent API calls where applicable. We’ll use CUST01 as the participant_code throughout the examples.
You can make your requests idempotent by using the request_id field. If a subsequent call is made with a previously used request_id, then the request would fail with an error code 400, error message “requestID already used with different participant data”.
If you fail to indicate that the End Customer has agreed to the user agreement, in the signed_agreements object shown above, future API calls will fail.
There may be situations where the Platform is restricted from submitting Customers who reside in non-permitted jurisdictions. The Platform will receive an error that looks like:
{
"errors": [
"The submitting platform is not allowed to operate in the participant's resident state",
"participant is not in an allowed jurisdiction"
]
}See more detail on permitted jurisdictions here.
The preferred approach is for the Platform to not allow customers to onboard on their side (through a feature flag, for example). However, if a request with a Customer in a blocked jurisdiction does get submitted to zerohash via API, the Platform should fail gracefully and display a descriptive error message on-screen.
[Recommended] Whitelist a self-custody receiving wallet's Travel Rule information
Proof of ownership is required for self-custody wallets above the Travel Rule threshold. zerohash manually reviews each submission, which can take up to 2 days, so it is recommended that you submit it well before you plan to initiate a withdrawal. Until the review is approved, payouts to that wallet are limited to €1,000 every 12 hours.
POST /travel-rule/submit Example Request:
{
"address": "0xABC123",
"participant_code": "MERCH1",
"address_belongs_to": "third_party", //can also set to existing zh_participant
"address_owner_type": "business",
"business_pii": {
"legal_entity_name": "Business XYZ",
"legal_entity_identifier": "123456789", //optional, only send when available
"legal_entity_address": "1 Example St, Dublin"
},
"wallet_type": "self_custody",
"deposit_id": "123456789" //optional, only send when referencing a specific deposit
}Warning: Skip this step for Exchange wallets. Their Travel Rule information is retained only briefly, so submit it right before you initiate the withdrawal. Find more information on Travel Rule here.
At any time, you can confirm a wallet's Travel Rule information availability through GET /travel-rule/state-approval
Request - GET /travel-rule/state-approval
{
"intention_action": "withdrawal",
"participant_code": "BENEF1",
"wallet_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"asset": "USDC.SOL",
"crypto_amount": "100"
}-
intention_action(required):depositorwithdrawal. For On Ramps, set towithdrawal -
participant_code: 6 uppercase alphanumeric characters. For a withdrawal, use the customer's code. -
wallet_address: non-empty string. Should matchb
Response - GET /travel-rule/state-approval
{
"message": {
"status": "action_required",
"status_reasons": ["proof_of_ownership"]
}
}Other GET /travel-rule/state-approval responses:
status | status_reasons | Meaning |
|---|---|---|
allowed | not returned | Travel Rule checks have passed |
action_required | ["info_required"] | Owner identity information, or the hosting VASP, is needed. Send it with POST /travel-rule/submit. |
action_required | ["proof_of_ownership"] | A self-custody wallet needs proof of ownership |
processing | not returned | Information has been received and is under review |
blocked | not returned | The transfer was rejected and can’t go ahead |
unknown | not returned | The status couldn’t be determine |
2. Query End Customer
The Platform can query the End Customer via the GET /participants/{email} endpoint or the Platform can query all End Customers via the GET /participants endpoint.
3. Fund Fiat Accounts
There are 3 types of fiat accounts needed for this flow:
- Float Account: The account that will fund real-time on ramp transactions. On ramp transactions will fail if the balance in this account is insufficient.
- Settlement Reserve Account: a buffer that covers the gap between what the PSP sends and what the Platform owes at end-of-day settlement.
- Settlement Account: The account that will be credited once a day in order to complete daily settlement. The deposit into this account will be initiated by the Payment Service Provider.
NoteIf you don't use an external PSP (ie, you are the PSP) to process the fiat leg of the transaction, the Settlement Account is used. If you use an external PSP, Settlement Accounts are not in scope for your integration.
For the following examples, we’ll assume Platform's platform code is PLAT01.
The Platform will fund each of the above accounts by sending fiat to the proper bank account, tagging each wire with a memo equal to the Platform's participant_code. Including the wire memo means that we can auto-credit the correct account when we receive the wire/ACH.
Here are the account details:
| Float Account | Settlement Reserve Account | Settlement Account | |
|---|---|---|---|
| Participant code | ZHDSEU | [Platform's participant code] | [Platform's participant code] |
| Account group | [Platform's participant code] | [Platform's participant code] | [Platform's participant code] |
| Account label | general | settlement_reserve | general |
| Account type | Available | Available | Available |
| Asset | USD | USD | USD |
| Wire Memo | PLAT01 - FLOAT | PLAT01 - RESERVE | PLAT01 - SETTLEMENT |
For the example, let's say the Float Account is funded with $50,000 and the Settlement Reserve Account is funded with $25,000:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $50,000 | (+$50,000) |
| Settlement Reserve Account | USD | $25,000 | (+$25,000) |
Note: For the Wire Memo, some payment providers don't support a fixed memo for the wire or ACH. In these cases please reach out to your ZH contact so we can investigate alternatives.
In Cert, your platform will be pre-funded with Float account funds.
4. Get Assets
In order to know which assets are supported, the Platform can query the GET /assets. If "rfq_liquidity_enabled": true, then it is supported
5. Get Quote
Submit Travel Rule Information for Withdrawal Address
A quote can't be generated until Travel Rule information for the receiving wallet (withdrawal_address) has been submitted via POST /travel-rule/submit. This applies to both Exchange wallets and self-custody wallets. Because Travel Rule data for Exchange wallets is stored only briefly, be sure to always submit it immediately before generating and executing a quote.
ReminderIf you already whitelisted a self-custody wallet's Travel Rule information, confirm its status with GET /travel-rule/state-approval before generating a quote.
Get Quote
EUR quoted currencyFor zerohash B.V. (EU), you can quote in USD or EUR. The examples on this page use USD. To quote in EUR, set the quoted currency to EUR in your request. EUR pairs are available for a growing set of assets. Visit Supported Instruments (RFQ) to see which assets can be quoted in EUR.
The Platform will now get the initial quote via the POST /convert_withdraw/rfq endpoint:
{
"participant_code" : "CUST01",
"side" : "buy",
"underlying" : "BTC",
"quoted_currency" : "USD", //defaults to USD, EUR also supported
"total" : "20",
"withdrawal_address" : "2N8PYGKSQRpHa5VDNZ4iLwxi5crpRWb3TR1"
}Response:
{
"message": {
"request_id": "64f34a8d-f5f5-4e37-b01d-7c6814aed4bc",
"participant_code": "CUST01",
"quoted_currency": "USD",
"side": "buy",
"quantity": "0.00087097",
"price": "22962.90",
"quote_id": "5aaaa8af-5d0c-4d55-868b-b56ea19a5443",
"expire_ts": 1661449335103,
"account_group": "ZHDSEU",
"withdrawal_address" : "2N8PYGKSQRpHa5VDNZ4iLwxi5crpRWb3TR1",
"account_label": "general",
"obo_participant": {
"participant_code": "CUST01",
"account_group": "PLAT01",
"account_label": "general"
},
"network_fee_notional": "1.50",
"network_fee_quantity": "0.00001",
"total_notional": "21.5",
"underlying": "BTC",
"asset_cost_notional": "20"
}
}Note:
fee_inclusive= true can be enacted to ensure that the End Customer spends a maximum oftotaland the fees will be deducted from there- Use
quoted_currencyto specify quoted currency (EUR vs USD). - Typically for on ramps the quote length is 30 seconds, although this is configurable
POST /convert_withdraw/rfq possible responses:
| Scenario | Return code | Error response |
|---|---|---|
| Quote created | 201 Created | none |
Quote request failed; Travel Rule information not available for withdrawal_address OR Travel Rule information provided but not sufficient for withdrawal amount. Check Travel Rule status of withdrawal_address with GET /travel-rule/state-approval | 400 Bad Request | withdrawal address is not yet travel-rule verified |
| Quote request failed; the withdrawal address is not yet Travel Rule verified and required information is missing | 400 Bad Request | withdrawal address is not yet travel-rule verified; missing required information: NATURAL_PERSON_FULL_NAME, NATURAL_PERSON_DATE_OF_BIRTH |
Quote request failed; Travel Rule information for withdrawal_address was provided and rejected by zerohash.Use POST /travel-rule/submit to provide information for a new withdrawal_address | 400 Bad Request | withdrawal address was rejected by the travel-rule compliance check |
6. Execute Quote
The platform will then execute a POST /convert_withdraw/execute call using the quote_id from a successful POST /convert_withdraw/rfq response. Example Response:
{
"message": {
"request_id": "945c41ba-c06e-4e69-aaf6-ea27cb7c75b2",
"quote": {
"request_id": "7a8a8526-3614-4373-9ab4-0069dc643109",
"participant_code": "CUST01",
"quoted_currency": "USD",
"side": "buy",
"quantity": "0.00087097",
"price": "22962.90",
"quote_id": "dc179192-5bdf-41f2-9ffa-badb1396a0a7",
"expire_ts": 1568311649602,
"account_group": "GRP001",
"account_label": "general",
"obo_participant": {
"participant_code": "CUST01",
"account_group": "PLAT01",
"account_label": "general"
},
"network_fee_notional": "1.50",
"network_fee_quantity": "0.00001",
"total_notional": "21.5",
"underlying": "BTC",
"asset_cost_notional": "20",
"withdrawal_address": "2N8PYGKSQRpHa5VDNZ4iLwxi5crpRWb3TR1",
"payment_processor": {
"name": "payment processor name",
"id": "payment processor id"
},
"spread_notional": ".22",
"spread_bps": "100",
"withdrawal_request_id": "ea97133e-ab15-4c86-86c1-86671b8420nr"
},
"trade_id": "ba97133e-ab15-4c86-86c1-86671b8420bc",
"status": "Completed"
}
}Note: After this, fiat is being taken from the float account, a trade is being created and settled, and an automatic and immediate on-chain transfer is being sent to the withdrawal_address
7. Query Withdrawal
When monitoring a withdrawal, the Platform can query the GET /withdrawals/requests/Dea97133e-ab15-4c86-86c1-86671b8420nr endpoint.
Response:
{
"id":"Dea97133e-ab15-4c86-86c1-86671b8420nr",
"withdrawal_account_id": 152089,
"participant_code": "CUST01",
"account_group": "PLAT01",
"account_label": null,
"requestor_participant_code": "PLAT01",
"asset": "BTC",
"requested_amount": "20",
"settled_amount": "20",
"gas_price": null,
"status": "SETTLED",
"on_chain_status": "PENDING",
"client_withdrawal_request_id": "zh_withdrawal_17845eeffd5f71abaa85e9722e76c931a",
"requested_timestamp": 1659542191772,
"transaction_id": "3899526c5f986297d3b2ba29f2c4c8b0fb486bef2fc76f7c11aae2b1faf3fe76",
"input_data": null,
"fee_amount": 0.00001,
"quoted_fee_amount": 0.00001
} | Parameter | Description |
|---|---|
| status | The zerohash internal settlement status.
|
| on_chain_status | The blockchain status.
|
| transaction_id | The on-chain transaction hash, useful to display out to customers so that they can follow the transaction if they wish. |
8. Network Fee Procedures
The Platform will be paying for the network fee associated with any on ramp transactions. There are 2 options:
- Fund the network fee account. Account details:
- participant_code: PLAT01 (the Platform's participant_code)
- account_group: PLAT01
- account_label: network_fee
- asset: USD
All network fees will be paid out of this account in real-time
- Don’t fund the network fee account. This account will build up a payable balance
zerohash will add the amount of the payable balance on this account to the end-of-month invoice, coupling it with the on ramp usage activity amount due.
9. Email Receipt Requirements
zerohash requires that the End Customer receives an email receipt for each transaction. We also insist that the email contain:
- Certain fields and values, which can be obtained using our API
- Adequate support contact information
Fields
Here are the required field names and their associated API fields:
| Email Receipt Field Name | Description | Example | API Location |
|---|---|---|---|
| Order Number | Unique order identifier | 9a738372-0855-4b25-8c65-5de0aa858b8b | trade_id from GET /trades |
| Order Type | The type of order | On ramp Transaction | N/a, can hard-code to "On Ramp Transaction" |
| Transmission Amount | The transmission amount for the transaction, in quoted currency terms | $10 | total POST /convert_withdraw/rfq or POST /convert_withdraw/execute response |
| Amount Received by End Customer | The amount of the underlying crypto received by the End Customer | 10 USDC | quantity POST /convert_withdraw/rfq or POST /convert_withdraw/execute response |
| Fees | Any added fee values included in the transaction. If there are no fees, then this needs to be expressly stated. This includes processing fees (ie, a fee assessed by the Platform to the End Customer) or blockchain network fees. | "$0", "1.99", "$0 Fees", or "No Fees" |
|
| On-Chain Transaction ID | Transaction Hash on the Blockchain for the transaction | "0x9cb5289c1896a48594f9ed278599caefbc05c9a3cefc2755b7eff8dac8165445" | transaction_id from GET /withdrawals/requests/{withdrawal_request_id}Use withdrawal_request_id from POST /convert_withdraw/execute response to make the above call. |
| Date/Time | Date and timestamp of the transaction transmission (meaning the time that the fiat was converted and settled into crypto within the zerohash system) | 2024-10-11 18:38:00 | settled_timestamp from GET /trades |
| Account ID | zerohash’s unique account identifier for the End Customer ( the “participant code” within zerohash). | CUST01 | participant_code from POST /convert_withdraw/rfq or POST /convert_withdraw/execute |
10. End of Day Settlement:
Platforms will typically use a Payment Service Provider (PSP) to process the USD leg of the transaction. PSPs will be required to settle with zerohash on a daily basis (excluding weekends and holidays). PSPs will typically withhold both 1) chargebacks and 2) PSP fees. As a result, zerohash will receive a settlement amount that is less than the Net Delivery Obligation (NDO) - in this example the NDO is $500. To compensate for this, zerohash will sweep funds from the Settlement Reserve Account to the Settlement Account, completing end of day settlement.
Here are the account changes after the PSP's wire lands at zerohash:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $49,500 | |
| Settlement Reserve Account | USD | $25,000 | |
| End Customer Account | USDC | 0 | |
| Platform USDC Account | USDC | 0 | |
| Settlement Account | USD | $497.5 | +$497.5 |
In order to get the Settlement Account to the correct amount (500), zerohash will initiate a transfer from the Settlement Reserve Account to the Settlement Account:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $49,500 | |
| Settlement Reserve Account | USD | $24,997.5 | (-$2.5) |
| End Customer Account | USDC | 0 | |
| Platform USDC Account | USDC | 0 | |
| Settlement Account | USD | $500 | +$2.5 |
Once the NDO has been met, zerohash will automatically settle the $500 to the Float Account:
| Asset | Current Balance | Change | |
|---|---|---|---|
| Float Account | USD | $50,000 | +$500 |
| Settlement Reserve Account | USD | $24,997.5 | |
| End Customer Account | USDC | 0 | |
| Platform USDC Account | USDC | 0 | |
| Settlement Account | USD | $0 | -$500 |
Updated 13 days ago