Status page
Guides

Integration Guide

Suggest Edits

Overview

This guide outlines the steps to integrate the Payment Processing into your platform for accepting fiat payments and receiving instant settlements in stablecoins.

Integration flow

The setup involves generating a payment processing request for a specific payment method, and initializing the user's payment process.

ℹ️

Detailed integration options could be found here.

User flow steps

  1. Amount and Payment Method Selection: The user selects the amount and payment method in your app.
  2. Payment Processing 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. (Conditional) If required, the user completes KYC verification. This step may not always occur, depending on the transaction limits, user's transaction history and risk profile.
  5. Payment Processing: Paybis processes the payment and initiates the stablecoin payout to yout wallet.
  6. Transaction Confirmation: The user lands on a transaction completion page.

Integration steps

To set up this flow, initialize the payment processing event with the transaction details (quote) created for a specific payment method (e.g. Credit Card) and the payment request (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 payment processing is initialized with a one-time authentication token.
  1. Your application allows users to select the 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 currencies for payment. This allows you to 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 currency.

3. Request a Quote

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

  • currencyCodeFrom: Fiat currency code in ISO alpha-3 format
  • currencyCodeTo: Stablecoin asset (i.e. USDT-TRC20)
  • amount: The fiat amount selected by the user.
  • paymentMethod: The specific payment method (e.g., credit_card).
  • isReceivedAmount: Specifies which party (user or partner) pays the transaction fees:
    • isReceivedAmount: false (Default): The commission is deducted from the final amount received by the partner.
    • isReceivedAmount: true: The commission is included in the initial amount paid by the user.
  • directionChange: This field determines the currency in which amount is specified.

⚠️

  • To receive settlements in the desired stablecoin (USDT or USDC), ensure the currencyCodeTo field is set to the correct corresponding asset code, as configured in your business account.
  • 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.

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

4. Get the Request ID required to initiate the Payment Processing

Generate the Request. Along with other optional parameters:

Required Parameters:

  • quoteId: Retrieved from the Quote API response.
  • partnerUserId: User's unique ID in your system to link the request to the existing user’s account or to create a new one in Paybis. Use the same ID for each request from the same customer to avoid duplicates.
  • paymentMethod: Must match the method used to generate the quote.
  • CryptoWalletAddress object (Must match the stablecoin to generate the quote):
    • address: The crypto wallet address for payout.
    • currencyCode: Crypto asset code of the address.

Optional Parameters

  • locale: Preferred locale in ISO alpha-2 format. It defines the language of UI. (optional)
  • merchantCompanyName: equal to your Company name from the Business account. (optional)
  • email: User's email (optional)
  • passwordless: Authentication option - Single sign-on if true (optional)
  • Know Your Customer (KYC) information (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 responds with a requestId(and oneTimeToken if Single sign-on applies).

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

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

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 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 processes the KYC data and approves the user's verification.

ℹ️

Paybis offers a NO-KYC option for selected payment methods (Credit/Debit Cards, ACH Bank Transfer, AstroPay, and M-Pesa) depending on the user's transaction history, risk profile (like PEP/Sanctions check, location risks, etc.).

ℹ️

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

7. Paybis makes a crypto payout

After successful payment, Paybis initiates a stablecoin payout to your 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 17 days ago