Promo codes for buying/selling crypto

A promotional code is an alphanumeric string that Paybis partners can use in their marketing activities to encourage customers to buy/sell crypto with a discount applied to transaction fees.


The promo code feature is not available in the widget by default. Please contact your integration manager to enable it for your partner account and to obtain the list of active promo codes along with their usage conditions.

This feature operates at the widget SDK level, requiring no changes in the integration as a precondition.

How it works

  1. Paybis enables promo codes for the partner account.
  2. Paybis provides active promo code(s) and usage conditions.
  3. Parter distributes promo(s) across its user base through its marketing channels.
  4. When the widget is initiated, the promo code entry field is displayed on the exchange form. Alternatively, the promo code can be passed via API in the promoCode field of the POST Quote endpoint.
  5. The user selects the currency pair and amount and then enters the promo code to redeem the discount.
  6. Paybis calculates the discount applied to transaction fees. The quote is re-calculated to include the discount amount. The bonus equivalent in fiat is displayed next to the provided promo code.
  7. The user confirms the quote with the discount.
  8. The user gets authenticated. Paybis validates the promo code against the user account.
  9. Upon successful validation (ensuring the user hasn't applied this coupon the maximum allowed number of times), a transaction is created with a discount. Otherwise, the transaction amount is recalculated to exclude the discount.

Promo codes format and usage

  • Promo code format: alphanumeric string (case sensitive).
  • Promo code has a set of attributes defined on Paybis end during its generation:
    • A maximum number of times the promo code can be applied per user.
    • Expiration date.
    • Discount: a percentage deducted from the original transaction fee amount. The discount is typically applied to the partner fee.
  • A promo code can apply to both buy and sell crypto transactions.
  • Each promo code can be used by multiple users for a limited number of transactions. The promo code is considered used only for successfully completed transactions. The promo code is "locked" from use if it was applied in a transaction that is currently not completed or rejected. The promo code can be "unlocked" and used again if the transaction is canceled or rejected.
  • If the user has entered an invalid, expired, or used-up promo code, the corresponding error message is displayed on the widget UI. The user will still be able to initiate a transaction in each of these cases but without any discount applied.

Tracking the promo code usage

Use the Transaction Status Webhook to track promo code usage. If the promo code has been used, the promo code value is returned in the promoCode field.