Skip to main content

Crypto on-ramp

The crypto on-ramp flow allows a user to add funds from a credit or debit card to a crypto address.

Bootstrap token payload​

  • partner (optional): Partner object.
    • continueUrl (optional): URL to redirect the user to after the order is placed.
    • continueUrlTarget (optional): In which tab should the continueUrl be opened.
    • displayName (optional): Partner name to be displayed to the user.
    • fee (optional): An object configuring the partner fee to be charged.
      • percentage: Percentage of the total source amount (the maximum allowed value is "5").
      • new-tab: Open in a new tab.
      • same-tab: Open in the same tab or iframe (default).
      • parent-tab: Useful only in an iframe: open in the tab that contains the iframe.
    • validation (optional): Custom request validation parameters.
      • device: (optional): Device parameters to validate.
        • alg (optional): Algorithm used to hash the fields. In case no algorithm is set, we'll be assumed that sha256 was used.
        • fields (optional): Fields that have been hashed.
        • hash (optional): Result of hashing the fields appended in the given order, without any extra characters or whitespaces, using the given algorithm.
        • ip (optional): User IP on partner's side that we should validate remains the same.
        • ipVersion (optional): Version of IP value used on the hash.
        • user-agent (optional): User agent used on partner's side that we should validate remains the same.
  • partnerFee (deprecated): Use partner.fee instead.
  • reusableKYC (optional): An object to provide a KYC shareable token.
    • provider (required): Provider that issued the shareable token.
    • token (required): Token issued that can be used to fetch user information.
  • simulation (optional): Simulation object.
    • country (optional): Country to use during simulations, in alpha-2 code format; It will be ignored after the user is authenticated and the user's country will be used.
  • source (optional): An object configuring the asset and amount to be paid.
    • amount (optional): Amount to be paid.
    • asset: Currency code in the ISO 4217 format used to make the payment.
    • paymentMethod (optional): An object configuring the pre-selected payment method.
      • network: Payment method network (e.g.: apple-pay, google-pay, card, paypal, venmo, pix, or sepa).
  • target (optional): An object configuring recipient wallet.
    • allowedAssets (optional): Set of cryptoassets that the user can set as target asset. Can be an array of objects with asset and networks (e.g.: { "asset": "ETH", "networks": ["ethereum"] }), an array of asset codes (e.g.: ["BTC", "ETH"] where all available networks for each asset are included), or a combination of both for flexibility.
    • amount (optional): Amount the user will receive.
    • asset: Cryptoasset the user will receive.
    • network: Network of the receiving asset.
    • address: Recipient wallet address.
    • tag (optional): Tag of the crypto transaction, used to complement the address.
      • type: Tag type (e.g.: memo or destination-tag).
      • value: Tag value.
    • priority (optional): Priority of the crypto transaction (e.g.: fast will enable instant send for Dash transactions). Defaults to normal.
    • recipientEditMode (optional): Controls if the user can change asset, network, address and tag on the widget. Defaults to not-editable.
    • label (optional): A label used for display purposes to name the recipient wallet. Defaults to the widget name.
note

At least one of source.amount or target.amount must be provided, but not both.

The supported values for source.asset, target.asset, target.network, target.tag and target.priority can be found using our REST API, via the assets endpoint.

caution

If target.allowedAssets is set, and you define target.asset with an asset that is not allowed, the bootstrap will fail.

If target.allowedAssets is set and target.asset is not, the target.asset will default to the first asset on target.allowedAssets.

caution

In the sandbox environment, Topper has limited funds on testnets. If you make an order using an asset we have no funds for, the order will be stuck indefinitely trying to create the blockchain transaction. We recommend that you use XRP for testing purposes when integrating Topper since we have a larger quantity of them. If you prefer to test with another asset and network, please reach out to us beforehand so that we can guarantee funds on our pool and give you a smoother integration experience.

Custom partner validation​

To increase customer security we support an extra layer of validations that can be customizable by our partners. This layer includes validations from customer's device, like IP and user agent, that we ensure is the same as the one provided by you. In case of any mismatch, the user request to initiate a widget session will fail. We accept this validation parameters as plain strings or as an hashed string. If you send us hashed parameters, we'll fetch the same parameters we receive from the user request, hash them and compare if both hashes are equal. If you plan on using hashed validation, please check the example below to see how you should hash your data.

import { createHash } from 'node:crypto';

await createHash('sha256')
  .update('1.2.3.4')
  .digest('hex');
note

When validating user IP, if the IP versions mismatch, validation will be partially (plain string validation) or entirely (hashed validation) skipped.

Recipient edit mode​

When recipientEditMode is not-editable, the user can't change asset, network, address or tag on the widget. This means that these fields are all required on the bootstrap token.

{
  "iat": 1679538023,
  "jti": "4b552af1-1592-42f8-bbc9-dac28e2b4000",
  "sub": "b9fe022b-f436-49e1-bb89-6f2e8eabf336",
  "target": {
    "asset": "ETH",
    "network": "ethereum",
    "address": "0xb794f5ea0ba39494ce839613fffba74279579268",
    "label": "My wallet",
    "recipientEditMode": "not-editable"
  }
}

Events​

Full information about the available events and their associated payloads can be found on the events page.