A Crypto Onramp Session represents your customer’s session as they purchase cryptocurrency through Stripe. Once payment is successful, Stripe will fulfill the delivery of cryptocurrency to your user’s wallet and contain a reference to the crypto transaction ID.
You can create an onramp session on your server and embed the widget on your frontend. Alternatively, you can redirect your users to the standalone hosted onramp.
Related guide: Integrate the onramp
Attributes
- idstring
Unique identifier for the object.
- objectstring
String representing the object’s type. Objects of the same type share the same value.
- client_
secretstring A client secret that can be used to drive a single session using our embedded widget.
Related guide: Set up an onramp integration
- createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.
- kyc_
details_ providedboolean Has the value
true
if any user kyc details were provided during the creation of the onramp session. Otherwise, has the valuefalse
. - livemodeboolean
Has the value
true
if the object exists in live mode or the valuefalse
if the object exists in test mode. - metadatanullable object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- redirect_
urlnullable string Redirect your users to the URL for a prebuilt frontend integration of the crypto onramp on the standalone hosted onramp.
Related guide: Mint a session with a redirect url
- statusstring
The status of the Onramp Session. One of =
{initialized, rejected, requires_
payment, fulfillment_ processing, fulfillment_ complete} - transaction_
detailsobject A hash representing monetary details of the transaction this session represents.
{ "id": "cos_1NamBL2eZvKYlo2CP38sZVEW", "object": "crypto.onramp_session", "client_secret": "cos_1NamBL2eZvKYlo2CP38sZVEW_secret_B5faamUkzHbcpjy6NndGq1mMZGGCo8FhK2P", "created": 1691010131, "kyc_details_provided": false, "livemode": true, "metadata": {}, "redirect_url": null, "status": "initialized", "transaction_details": { "destination_amount": null, "destination_currencies": [ "btc", "eth", "matic", "sol", "xlm", "avax", "usdc" ], "destination_currency": null, "destination_network": null, "destination_networks": [ "bitcoin", "ethereum", "base", "polygon", "solana", "stellar", "avalanche" ], "fees": null, "lock_wallet_address": false, "source_amount": null, "source_currency": null, "transaction_id": null, "wallet_address": null, "wallet_addresses": null }}
Creates a CryptoOnrampSession object.
After the CryptoOnrampSession is created, display the onramp session modal using the client_
.
Related guide: Set up an onramp integration
Parameters
- customer_
ip_ addressstring The IP address of the customer the platform intends to onramp.
If the user’s IP is in a region we can’t support, we return an
HTTP 400
with an appropriate error code.We support IPv4 and IPv6 addresses. Geographic supportability is checked again later in the onramp flow, which provides a way to hide the onramp option from ineligible users for a better user experience.
- destination_
amountstring The default amount of crypto to exchange into.
- When left null, a default value is computed if
source_
,amount destination_
, andcurrency destination_
are set.network - When set, both
destination_
andcurrency destination_
must also be set. All cryptocurrencies are supported to their full precisions (for example, 18 decimal places fornetwork eth
). We validate and generate an error if the amount exceeds the supported precision based on the exchange currency. Settingsource_
is mutually exclusive with settingamount destination_
(only one or the other is supported). Users can update the amount in the onramp UI.amount
- When left null, a default value is computed if
- destination_
currenciesarray of enums The list of destination cryptocurrencies a user can choose from.
- When left null, all supported cryptocurrencies are shown in the onramp UI subject to
destination_
if set.networks - When set, it must be a non-empty array where all values in the array are valid cryptocurrencies. You can use it to lock users to a specific cryptocurrency by passing a single value array. Users cannot override this parameter.
- When left null, all supported cryptocurrencies are shown in the onramp UI subject to
- destination_
currencyenum The default destination cryptocurrency.
- When left null, the first value of
destination_
is selected.currencies - When set, if
destination_
is also set, the value ofcurrencies destination_
must be present in that array. To lock acurrency destination_
, specify that value as the single value forcurrency destination_
. Users can select a different cryptocurrency in the onramp UI subject tocurrencies destination_
if set.currencies
- When left null, the first value of
- destination_
networkenum The default destination crypto network.
- When left null, the first value of
destination_
is selected.networks - When set, if
destination_
is also set, the value ofnetworks destination_
must be present in that array. To lock anetwork destination_
, specify that value as the single value fornetwork destination_
. Users can select a different network in the onramp UI subject tonetworks destination_
if set.networks
- When left null, the first value of
- destination_
networksarray of enums The list of destination crypto networks user can choose from.
- When left null, all supported crypto networks are shown in the onramp UI.
- When set, it must be a non-empty array where values in the array are each a valid crypto network. It can be used to lock users to a specific network by passing a single value array. Users cannot override this parameter.
- kyc_
detailsobject Pre-populate some of the required KYC information for the user if you’ve already collected it within your application.
Related guide: Using the API
- lock_
wallet_ addressboolean Whether or not to lock the suggested wallet address. If destination tags are provided, this will also lock the destination tags.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata
. - source_
amountstring The default amount of fiat (in decimal) to exchange into crypto.
- When left null, a default value is computed if
destination_
is set.amount - When set, setting
source_
is mutually exclusive with settingamount destination_
(only one or the other is supported). We don’t support fractional pennies. If fractional minor units of a currency are passed in, it generates an error. Users can update the value in the onramp UI.amount
- When left null, a default value is computed if
- source_
currencyenum The default source fiat currency for the onramp session.
- When left null, a default currency is selected based on user locale.
- When set, it must be one of the fiat currencies supported by onramp. Users can still select a different currency in the onramp UI.
- wallet_
addressesobject The end customer’s crypto wallet address (for each network) to use for this transaction.
- When left null, the user enters their wallet in the onramp UI.
- When set, the platform must set either
destination_
ornetworks destination_
and we perform address validation. Users can still select a different wallet in the onramp UI.network
Returns
Returns the created CryptoOnrampSession object
{ "id": "cos_1NamBL2eZvKYlo2CP38sZVEW", "object": "crypto.onramp_session", "client_secret": "cos_1NamBL2eZvKYlo2CP38sZVEW_secret_B5faamUkzHbcpjy6NndGq1mMZGGCo8FhK2P", "created": 1691010131, "kyc_details_provided": false, "livemode": true, "metadata": {}, "redirect_url": null, "status": "initialized", "transaction_details": { "destination_amount": null, "destination_currencies": [ "btc", "eth", "matic", "sol", "xlm", "avax", "usdc" ], "destination_currency": null, "destination_network": null, "destination_networks": [ "bitcoin", "ethereum", "base", "polygon", "solana", "stellar", "avalanche" ], "fees": null, "lock_wallet_address": false, "source_amount": null, "source_currency": null, "transaction_id": null, "wallet_address": null, "wallet_addresses": null }}
Retrieves the details of a CryptoOnrampSession that was previously created.
Parameters
No parameters.
Returns
Returns a CryptoOnrampSession object
{ "id": "cos_1NamBL2eZvKYlo2CP38sZVEW", "object": "crypto.onramp_session", "client_secret": "cos_1NamBL2eZvKYlo2CP38sZVEW_secret_B5faamUkzHbcpjy6NndGq1mMZGGCo8FhK2P", "created": 1691010131, "kyc_details_provided": false, "livemode": true, "metadata": {}, "redirect_url": null, "status": "initialized", "transaction_details": { "destination_amount": null, "destination_currencies": [ "btc", "eth", "matic", "sol", "xlm", "avax", "usdc" ], "destination_currency": null, "destination_network": null, "destination_networks": [ "bitcoin", "ethereum", "base", "polygon", "solana", "stellar", "avalanche" ], "fees": null, "lock_wallet_address": false, "source_amount": null, "source_currency": null, "transaction_id": null, "wallet_address": null, "wallet_addresses": null }}
Returns a list of onramp sessions that match the filter criteria. The onramp sessions are returned in sorted order, with the most recent onramp sessions appearing first.
Parameters
- createdobject
Only return onramp sessions that were created during the given date interval.
- destination_
currencyenum The destination cryptocurrency to filter by.
- destination_
networkenum The destination blockchain network to filter by.
- ending_
beforestring An object ID cursor for use in pagination.
- limitinteger
A limit ranging from 1 to 100 (defaults to 10).
- starting_
afterstring An object ID cursor for use in pagination.
- statusenum
The status of the Onramp Session. One of =
{initialized, rejected, requires_
payment, fulfillment_ processing, fulfillment_ complete}
Returns
A dictionary with a data property that contains an array of up to limit
onramp sessions, starting after onramp session starting_
. Each entry in the array is a separate onramp session object. If no more onramp sessions are available, the resulting array will be empty.
{ "object": "list", "url": "/v1/crypto/onramp_sessions", "has_more": false, "data": [ { "id": "cos_1NamBL2eZvKYlo2CP38sZVEW", "object": "crypto.onramp_session", "client_secret": "cos_1NamBL2eZvKYlo2CP38sZVEW_secret_B5faamUkzHbcpjy6NndGq1mMZGGCo8FhK2P", "created": 1691010131, "kyc_details_provided": false, "livemode": true, "metadata": {}, "redirect_url": null, "status": "initialized", "transaction_details": { "destination_amount": null, "destination_currencies": [ "btc", "eth", "matic", "sol", "xlm", "avax", "usdc" ], "destination_currency": null, "destination_network": null, "destination_networks": [ "bitcoin", "ethereum", "base", "polygon", "solana", "stellar", "avalanche" ], "fees": null, "lock_wallet_address": false, "source_amount": null, "source_currency": null, "transaction_id": null, "wallet_address": null, "wallet_addresses": null } } ]}