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.
    • 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").
    • continueUrl (optional): URL to redirect the user to after the order is placed.
    • continueUrlTarget (optional): In which tab should the continueUrl be opened.
      • 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.
  • partnerFee (deprecated): Use partner.fee instead.
  • 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, pix or card).
  • target (optional): An object configuring recipient wallet.
    • allowedAssets (optional): Set of cryptoassets that the user can set as target asset.
    • 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.

Recipient edit mode​

When recipientEditMode is not-editable, the user can 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​

order:crypto-onramp:committed​

Triggered when a user has placed an order.

  • id: UUID of the order.
  • status: Status of the order (pending).
  • createdAt: Timestamp at which the order was created.
  • updatedAt: Timestamp at which the order was last updated.
  • origin: Object containing information about how the user paid.
    • amount: Amount the user will pay.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to make the payment.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • destination: Object containing information about what the user will receive.
    • amount: Amount the user will receive.
    • rate: Rate used to calculate the amount.
    • 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.
  • fees: Array containing fees associated with the order.
    • amount: Amount user was charged for this fee.
    • asset: Asset used to charge the fee.
    • normalized: Amount in USD that the user was charged for this fee.
    • type: Type of fee (network, deposit or partner).
  • widget: Widget associated with the session.
    • id UUID of the widget.
    • name: Name of the widget.
    • flow: Flow associated with the widget.
note

The values for origin.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-onramp:charged​

Triggered when a user has been charged.

  • id: UUID of the order.
  • status: Status of the order (processing).
  • createdAt: Timestamp at which the order was created.
  • updatedAt: Timestamp at which the order was last updated.
  • origin: Object containing information about how the user paid.
    • amount: Amount the user paid.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to make the payment.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • destination: Object containing information about what the user will receive.
    • amount: Amount the user will receive.
    • rate: Rate used to calculate the amount.
    • 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.
  • fees: Array containing fees associated with the order.
    • amount: Amount user was charged for this fee.
    • asset: Asset used to charge the fee.
    • normalized: Amount in USD that the user was charged for this fee.
    • type: Type of fee (network, deposit or partner).
  • widget: Widget associated with the session.
    • id UUID of the widget.
    • name: Name of the widget.
    • flow: Flow associated with the widget.
note

The values for origin.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-onramp:completed​

Triggered when a user's order has completed.

  • id: UUID of the order.
  • status: Status of the order (completed).
  • createdAt: Timestamp at which the order was created.
  • updatedAt: Timestamp at which the order was last updated.
  • origin: Object containing information about how the user paid.
    • amount: Amount the user paid.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to make the payment.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • destination: Object containing information about what the user received.
    • amount: Amount the user received.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user received.
    • blockchainUrl (deprecated): URL to view the transaction details on a blockchain explorer.
    • 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.
    • ledger (optional): Object containing information about the transaction on the ledger.
      • txid: Transaction ID on the ledger.
      • url: URL to view the transaction details on a blockchain explorer.
  • fees: Array containing fees associated with the order.
    • amount: Amount user was charged for this fee.
    • asset: Asset used to charge the fee.
    • normalized: Amount in USD that the user was charged for this fee.
    • type: Type of fee (network, deposit or partner).
  • widget: Widget associated with the session.
    • id UUID of the widget.
    • name: Name of the widget.
    • flow: Flow associated with the widget.
note

The values for origin.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-onramp:failed​

Triggered when a user's order has failed.

  • id: UUID of the order.
  • status: Status of the order (failed).
  • createdAt: Timestamp at which the order was created.
  • updatedAt: Timestamp at which the order was last updated.
  • origin: Object containing information about how the user paid.
    • amount: Amount the user paid.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to make the payment.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • destination: Object containing information about what the user would have received.
    • amount: Amount the user would have received.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user would have received.
    • 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.
  • fees: Array containing fees associated with the order.
    • amount: Amount user was charged for this fee.
    • asset: Asset used to charge the fee.
    • normalized: Amount in USD that the user was charged for this fee.
    • type: Type of fee (network, deposit or partner).
  • widget: Widget associated with the session.
    • id UUID of the widget.
    • name: Name of the widget.
    • flow: Flow associated with the widget.
  • error: Indicates specific error information.
    • reason: Indicates the reason for the error, possible values are fraud.
note

The values for origin.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-onramp:refund:completed​

Triggered when a user's order has been successfully refunded.

  • id: UUID of the order.
  • status: Status of the order (refunded).
  • createdAt: Timestamp at which the order was created.
  • updatedAt: Timestamp at which the order was last updated.
  • origin: Object containing information about how the user paid.
    • amount: Amount the user paid.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to make the payment.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • destination: Object containing information about what the user would have received.
    • amount: Amount the user would have received.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user would have received.
    • 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.
  • fees: Array containing fees associated with the order.
    • amount: Amount user was charged for this fee.
    • asset: Asset used to charge the fee.
    • normalized: Amount in USD that the user was charged for this fee.
    • type: Type of fee (network, deposit or partner).
  • refund: Object containing information about how much was refunded to the user.
    • formattedAmount: Amount refunded to the user
    • asset: Currency code in the ISO 4217 format used to make the payment.
    • rate: Rate used to calculate the amount.
  • widget: Widget associated with the session.
    • id UUID of the widget.
    • name: Name of the widget.
    • flow: Flow associated with the widget.
note

The values for origin.paymentMethod.type can be found using our REST API, via the payment methods endpoint.