Skip to main content

Crypto off-ramp

The crypto off-ramp flow allows a user to sell cryptocurrency and convert it into fiat, which can then be transferred to their linked debit cards.

Bootstrap token payload​

  • partner (optional): Partner object.
    • continueUrl (optional): URL to redirect the user to after the order is placed and the funds were received.
    • 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.
    • 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").
  • refund (optional): An object configuring the refund details. The asset and network of the refund will be the same as the source asset and network.
    • address: Address to which the refund will be sent.
    • 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.
  • source (optional): An object configuring the asset and amount to be sold.
    • allowedAssets (optional): Set of cryptoassets that the user can set as source asset.
    • amount (optional): Amount to be sold.
    • asset: Cryptoasset the user will send.
    • editMode (optional): Controls what values the user can change on the widget.
      • all-editable: The user can change amount, asset and network on the widget. (default)
      • only-amount: The user can only change the amount on the widget.
    • network (optional): Network of the receiving asset.
    • walletSendUrl (optional): URL to redirect the user to send the crypto from their wallet.
    • walletSendUrlTarget (optional): In which tab should the walletSendUrl 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.
  • target (optional): An object configuring the amount and asset to be paid.
    • amount (optional): Amount the user will receive.
    • asset: Currency code in the ISO 4217 format used to receive the funds.
note

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

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

caution

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

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

caution

In the sandbox environment, Topper has limited funds on testnets. If you make an order that needs to be refunded 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.

Events​

order:crypto-offramp:committed​

Triggered when a user has placed an order.

  • 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 what the user will send.
    • amount: Amount the user will send.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user will send.
    • network: Network of the sending asset.
    • depositAddress: Object containing information related to the deposit.
      • expiredAt: Timestamp at which the deposit expires.
      • remindAt: Timestamp at which the user is reminded.
      • tag: Tag of the crypto transaction, used to complement the address.
        • type: Tag type.
        • value: Tag value.
      • value: Address to which the user sends the funds.
  • destination: Object containing information about what the user will receive.
    • amount: Amount the user will receive.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to receive the funds.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • 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 destination.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-offramp:funds-sent​

Triggered when a user has sent funds for their order.

  • 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 what the user sent.
    • amount: Amount the user sent.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user sent.
    • network: Network of the sending asset.
    • depositAddress: Object containing information related to the deposit.
      • expiredAt: Timestamp at which the deposit expires.
      • remindAt: Timestamp at which the user is reminded.
      • tag: Tag of the crypto transaction, used to complement the address.
        • type: Tag type.
        • value: Tag value.
      • value: Address to which the user sends the funds.
  • destination: Object containing information about what the user will receive.
    • amount: Amount the user will receive.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to receive the funds.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • 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 destination.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-offramp:funds-received​

Triggered when a user has sent funds for their order and we have received them.

  • 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 what the user sent.
    • amount: Amount the user sent.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user sent.
    • network: Network of the sending asset.
    • depositAddress: Object containing information related to the deposit.
      • expiredAt: Timestamp at which the deposit expires.
      • remindAt: Timestamp at which the user is reminded.
      • tag: Tag of the crypto transaction, used to complement the address.
        • type: Tag type.
        • value: Tag value.
      • value: Address to which the user sends the funds.
  • destination: Object containing information about what the user will receive.
    • amount: Amount the user will receive.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to receive the funds.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • 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 destination.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-offramp: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 what the user sent.
    • amount: Amount the user sent.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user sent.
    • network: Network of the sending asset.
    • depositAddress: Object containing information related to the deposit.
      • expiredAt: Timestamp at which the deposit expires.
      • remindAt: Timestamp at which the user is reminded.
      • tag: Tag of the crypto transaction, used to complement the address.
        • type: Tag type.
        • value: Tag value.
      • value: Address to which the user sends the funds.
  • destination: Object containing information about what the user received.
    • amount: Amount the user received.
    • rate: Rate used to calculate the amount.
    • asset: Currency code in the ISO 4217 format used to receive the funds.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • 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 destination.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-offramp: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 what the user sent.
    • amount: Amount the user sent.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user sent.
    • network: Network of the sending asset.
    • depositAddress: Object containing information related to the deposit.
      • expiredAt: Timestamp at which the deposit expires.
      • remindAt: Timestamp at which the user is reminded.
      • tag: Tag of the crypto transaction, used to complement the address.
        • type: Tag type.
        • value: Tag value.
      • value: Address to which the user sends the funds.
  • 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: Currency code in the ISO 4217 format used to receive the funds.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • 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 destination.paymentMethod.type can be found using our REST API, via the payment methods endpoint.

order:crypto-offramp:refund:completed​

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

  • 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 what the user sent.
    • amount: Amount the user sent.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user sent.
    • network: Network of the sending asset.
    • depositAddress: Object containing information related to the deposit.
      • expiredAt: Timestamp at which the deposit expires.
      • remindAt: Timestamp at which the user is reminded.
      • tag: Tag of the crypto transaction, used to complement the address.
        • type: Tag type.
        • value: Tag value.
      • value: Address to which the user sends the funds.
  • 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: Currency code in the ISO 4217 format used to receive the funds.
    • paymentMethod: Object containing information about the payment method used.
      • type: Type of payment method.
  • 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.
    • amount: Amount the user received.
    • rate: Rate used to calculate the amount.
    • asset: Cryptoasset the user received.
    • network: Network of the receiving asset.
    • address: User's wallet address to receive funds.
    • priority: Priority of the crypto transaction.
    • tag: Tag of the crypto transaction, used to complement the address.
      • type: Tag type (e.g.: memo or destination-tag).
      • value: Tag value.
  • 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 destination.paymentMethod.type can be found using our REST API, via the payment methods endpoint.