Status page
Guides

Integration Guide - v1

Suggest Edits

Overview

This guide outlines the steps to integrate the Payment Processing On-Ramp into your platform. By following this process, you can provide users with a seamless payment experience that converts fiat payments into stablecoin settlements.

Integration flow

The setup involves generating a Quote for a specific payment method, creating a Request linked to the quote, and initializing the user's payment process.

User flow steps

  1. Amount and Payment Method Selection: The user selects the fiat amount and payment method in the partner’s app.
  2. Widget Initialization: Paybis widget is initialized in the background.
  3. Direct Payment Page: The user lands directly on the payment page.
  4. Payment Authorization: The user enters payment details (e.g., credit card information) and authorizes the payment.
    1. If required, the user completes KYC verification.
  5. Payment Processing: Paybis processes the payment and initiates the cryptocurrency payout to the partner’s wallet.
  6. Transaction Confirmation: The user lands on a transaction completion page with confirmation details.

Integration steps

To set up this flow, the partner should initialize the widget with the Quote created for a specific payment method (Credit Card) and the Request with the corresponding payment method.

⚙️

Prerequisites

  1. To ensure that the authentication step is skipped, one of the conditions below should be met:
  • Option A: The user has an active section in the cookies
  • Option B: Single sign-on feature is enabled, and the widget is initialized with a one-time authentication token.
  1. Your application allows users to select the fiat amount and choose a payment method for their transaction.

1. Retrieve Available Currency Pairs

Use GET /v2/currency/pairs/buy-crypto endpoint to obtain the list of supported fiat and cryptocurrency pairs to get all the currency pairs available for buying crypto, which helps you display valid options to users.

2. Retrieve Available Payment Methods

After the user selects a currency pair, use the GET /v2/payment-methods/{currencyFrom}/{currencyTo} endpoint to get the list of available payment methods and transaction amount limits for the selected fiat/crypto pair.

3. Request a Quote

Call the POST Quote to generate a quote for the specific payment method:

  • amount: The fiat amount selected by the user.
  • currency: The fiat currency (e.g., USD).
  • paymentMethod: The specific payment method (e.g., credit_card).

⚠️

The paymentMethod must be specified in the request. Failure to include it will result in the quote being generated for all available methods, preventing the payment flow.

The Paybis backend processes the received data and returns a quote to your application. See the response here.

4. Get the Request ID required to initiate the On-Ramp

Generate the Request. Along with other optional parameters:

Required Parameters:

  • quoteId: Retrieved from the Quote API response.
  • paymentMethod: Must match the method used to generate the quote.
  • Partner's crypto wallet.

Optional Parameters

  • User's email (optional)
  • Know Your Customer (KYC) information (optional)
  • authentication option - Single sign-on (optional)

❗️

It is required to pass the quoteId retrieved in Step 2 and the paymentMethod value that matches the payment method for which the quote has been generated.

Paybis Widget backend responds with a requestId(and oneTimeToken if Single sign-on applies).

5. Run Widget UI with the retrieved requestId and oneTimeToken (optional)

Provided that the user has an active session in the onramp or Single sign-on is used, the transaction is created together with the onramp initialization and the user lands on the payment screen.

However, if the user is not authenticated, they will be prompted to enter their email address and a One-Time Password (OTP) for verification.

6. User makes a payment

The user enters the credit card/eWallet details (depending on the payment method) and submits the payment.

Paybis backend processes the transaction data and authorizes the payment (if applicable).

6.1 KYC

After successful credit card authorization, the user will be prompted to submit the verification data (one-time KYC process). For payments via eWallets, KYC is triggered before the payment can be processed.

Your application has the option to pass this KYC data. If you do, this step is skipped.

Paybis backend processes the KYC data and approves the user's verification.

ℹ️

To learn more about KYC options, read Share KYC article.

7. Paybis makes a crypto payout

After successful payment, Paybis initiates a cryptocurrency payout to the partner’s wallet. The user receives confirmation of the transaction on a simplified completion page.

8. Webhooks

Paybis will send webhooks to notify you of transaction status updates. Ensure your system can receive and process these webhooks. More details could be found here.


❗️

The settled amount is sent in stablecoins (e.g., USDT or USDC) equivalent to the fiat amount paid, minus transaction fees. Fees are automatically deducted before settlement.

Integrating the Payment Processing On-Ramp improves your platform by providing users with a seamless payment experience while you benefit from instant settlements in stablecoins.

Updated 24 days ago