Offramps
Offramps is a service that allows businesses to convert cryptocurrency assets like BTC, USDT and USDC into local currencies like NGN, KES and AUD and receive or transfer these funds to specified bank accounts or mobile money wallets. Blockchain networks like TRC20, and ERC20 are supported, BTC transactions can be performed on both mainnet and lightning. Offramps also offers real-time exchange rates, flexible integrations, and they must be resolved within 15 minutes or they are tagged as expired and a new quote needs to be generated.
Quotes
Transactions within Offramps are processed using quotes. Each quote represents the details of a single transaction and has a 15-minute lifespan. This is an overview of the quote lifecycle:
1. Create a quote
A quote can be created with details like the cryptocurrency, the settlement currency, the transaction amount, and the payment method. The response will contain:
- The current exchange rate
- A unique
quoteIdfor tracking - The settlement amount in the selected settlement currency Amongst some other details that provide general information about the quote. If you are satisfied with the exchange rates proceed to the next step.
2. Initialize the quote
This step is where the details of the beneficiary is added to the quote, this can either be their bank account details or details of their mobile money wallet. A transaction reference and the payment reason can also be added here too. A successful response provides confirmation of the transaction's readiness and the necessary details for review before proceeding to finalizing the quote.
3. Finalizing the quote
The quote is finalized to confirm the transaction. At this step, payment is deducted from your existing balance or received from an external source (depending on the source provided when the quote was created). Only after the payment is received and processed can a finalized quote proceed to settlement.
Key properties of a quote
| Property | Description |
|---|---|
id | The unique identifier for the quote. |
quoteId | A non uuid unique identifier for the quote, used for tracking purposes. |
customerId | The unique identifier of the customer associated with the quote. |
paymentReason | The reason provided for the payment associated with the quote. |
reference | A reference string for the transaction, useful for tracking. |
callbackUrl | The URL to which webhook events regarding transaction updates will be sent. |
beneficiaryId | The unique identifier of the beneficiary receiving the funds, useful for when a beneficiary is reused |
status | The current status of the quote (e.g., pending_address_deposit, expired, etc). |
exchangeRate.rate | The exchange rate applied to the transaction. |
exchangeRate.currency | The currency for which the exchange rate applies (e.g., NGN). |
beneficiary | An object containing all the details of the beneficiary required for the transaction. The id is the same as beneficiaryId above |
trip | An object containing timestamps of when various events in the quote lifecycle occurred (e.g,submitted, quoteSentAt, assetReceived, initializedAt, etc) |
clientMetaData | An object containing additional client metadata, values and properties here are provided by the user when Initializing the quote. |
satAmount | The transaction amount in satoshis. |
btcAmount | The transaction amount in BTC. |
amount | The transaction amount in fiat currency. |
centAmount | The transaction amount in the lowest denomination of the settlement currency. |
settlementAmount | The amount the beneficiary will receive in the settlement currency. |
centFees | Fees charged for the transaction in the lowest denomination of the currency. |
fees | Fees charged for the transaction. |
address | The cryptocurrency address for the transaction (if the transaction source was onchain) |
source | The source of the cryptocurrency (e.g., onchain). |
fromAsset | The cryptocurrency asset being converted (e.g., USDT). |
chain | The blockchain network used (e.g., TRC20). |
toCurrency | The fiat currency for settlement (e.g., NGN). |
expiry | The timestamp indicating when the quote will expire. |
Fetching a quote
Every detail of a transaction at any point in its life cycle can be retrieved from the quote. There are three ways to fetch or retrieve a quote, these 3 methods are:
- Using the quoteId:
GETrequest toapi/v1/payouts/quotes/quoteId(e.g, QT_6156) - Using the reference that was provided or generated:
GETrequest toapi/v1/payouts/fetch/reference/reference - Using the id of the quote:
GETrequest toapi/v1/payouts/fetch/id
Next steps
Detailed instructions for each step, including sample API requests and responses, can be found in the corresponding sections: