Create a CryptoOnrampSession

Creates a CryptoOnrampSession object.

After the CryptoOnrampSession is created, display the onramp session modal using the client_secret.

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_currency, and destination_network are set.
    • When set, both destination_currency and destination_network must also be set. All cryptocurrencies are supported to their full precisions (for example, 18 decimal places for eth). We validate and generate an error if the amount exceeds the supported precision based on the exchange currency. Setting source_amount is mutually exclusive with setting destination_amount (only one or the other is supported). Users can update the amount in the onramp UI.
  • 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_networks if set.
    • 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.
  • destination_currencyenum

    The default destination cryptocurrency.

    • When left null, the first value of destination_currencies is selected.
    • When set, if destination_currencies is also set, the value of destination_currency must be present in that array. To lock a destination_currency, specify that value as the single value for destination_currencies. Users can select a different cryptocurrency in the onramp UI subject to destination_currencies if set.
  • destination_networkenum

    The default destination crypto network.

    • When left null, the first value of destination_networks is selected.
    • When set, if destination_networks is also set, the value of destination_network must be present in that array. To lock a destination_network, specify that value as the single value for destination_networks. Users can select a different network in the onramp UI subject to destination_networks if set.
  • 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_amount is set.
    • When set, setting source_amount is mutually exclusive with setting destination_amount (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.
  • 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_networks or destination_network and we perform address validation. Users can still select a different wallet in the onramp UI.

Returns

Returns the created CryptoOnrampSession object

POST /v1/crypto/onramp_sessions
cURL
curl -X POST https://api.stripe.com/v1/crypto/onramp_sessions \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
"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",
"sol",
"usdc"
],
"destination_currency": null,
"destination_network": null,
"destination_networks": [
"bitcoin",
"ethereum",
"solana",
"polygon",
"stellar"
],
"fees": null,
"lock_wallet_address": false,
"source_amount": null,
"source_currency": null,
"transaction_id": null,
"wallet_address": null,
"wallet_addresses": null
}
}

Retrieve a CryptoOnrampSession

Retrieves the details of a CryptoOnrampSession that was previously created.

Parameters

No parameters.

Returns

Returns a CryptoOnrampSession object

GET /v1/crypto/onramp_sessions/:id
cURL
curl https://api.stripe.com/v1/crypto/onramp_sessions/cos_1NamBL2eZvKYlo2CP38sZVEW \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
"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",
"sol",
"usdc"
],
"destination_currency": null,
"destination_network": null,
"destination_networks": [
"bitcoin",
"ethereum",
"solana",
"polygon",
"stellar"
],
"fees": null,
"lock_wallet_address": false,
"source_amount": null,
"source_currency": null,
"transaction_id": null,
"wallet_address": null,
"wallet_addresses": null
}
}

List CryptoOnrampSessions

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_after. Each entry in the array is a separate onramp session object. If no more onramp sessions are available, the resulting array will be empty.

GET /v1/crypto/onramp_sessions
cURL
curl -G https://api.stripe.com/v1/crypto/onramp_sessions \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
-d limit=3
Response
{
"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",
"sol",
"usdc"
],
"destination_currency": null,
"destination_network": null,
"destination_networks": [
"bitcoin",
"ethereum",
"solana",
"polygon",
"stellar"
],
"fees": null,
"lock_wallet_address": false,
"source_amount": null,
"source_currency": null,
"transaction_id": null,
"wallet_address": null,
"wallet_addresses": null
}
}
{...}
{...}
],
}

Crypto Onramp Quotes

Crypto Onramp Quotes are estimated quotes for onramp conversions into all the different cryptocurrencies on different networks. The Quotes API allows you to display quotes in your product UI before directing the user to the onramp widget.

Related guide: Quotes API

Climate Order

Orders represent your intent to purchase a particular Climate product. When you create an order, the payment is deducted from your merchant balance.

Climate Product

A Climate product represents a type of carbon removal unit available for reservation. You can retrieve it to see the current price and availability.

Forwarding RequestPreview feature

Instructs Stripe to make a request on your behalf using the destination URL. The destination URL is activated by Stripe at the time of onboarding. Stripe verifies requests with your credentials provided during onboarding, and injects card details from the payment_method into the request.

Stripe redacts all sensitive fields and headers, including authentication credentials and card numbers, before storing the request and response data in the forwarding Request object, which are subject to a 30-day retention period.

You can provide a Stripe idempotency key to make sure that requests with the same key result in only one outbound request. The Stripe idempotency key provided should be unique and different from any idempotency keys provided on the underlying third-party request.

Forwarding Requests are synchronous requests that return a response or time out according to Stripe’s limits.

Related guide: Forward card details to third-party API endpoints.

Webhook Endpoints

You can configure webhook endpoints via the API to be notified about events that happen in your Stripe account or connected accounts.

Most users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints.

Related guide: Setting up webhooks

Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$