📘

Glossary

Partner - a business-to-business (B2B) or business-to-customer (B2C) client of Paybis that integrates cryptocurrency payment solutions into its offerings.

Merchant - a business entity that operates with Partner, utilizing the Partner's services to handle cryptocurrency transactions. Merchants are beneficiaries of initiated crypto payments from Users via the infrastructure provided by the Partner.

User - an individual who engages in transactions on websites or e-commerce platforms that utilize crypto-acquiring services.

General Information

Paybis Crypto Acquiring allows merchants to accept cryptocurrency payments, opening up new streams for revenue and customer engagement. Here are some key use cases and integration guidelines:

Use Case Description

1. Retrieving Cryptocurrency Pairs: Partner requests available currency pairs for swap crypto and parses JSON from Paybis to get available cryptocurrency pairs to show to the User.
2. Quote Retrieval

• User Selection: Users select their preferred cryptocurrency pair on the Partner's platform.
• API Interaction: Partner calls Quote API with the User's selection to fetch the quote ID needed for transaction initiation.

Quote API offers two options for specifying the transaction amount:

1. Fiat-Based Calculation (using requestedCurrency):

Business Use Case: E-commerce platforms or online businesses can allow customers to purchase goods or services using cryptocurrencies.

• Specify the requestedCurrency parameter with the selected fiat currency (e.g., USD, EUR).
• The amount parameter should represent the fiat price of the item or service.
• Paybis will calculate the equivalent cryptocurrency amount for payment, considering the exchange rate and any applicable fees.

This option provides the merchant receives the exact fiat amount specified.

Crypto-Based Calculation (using directionChange):

Business Use Case: Non-profit organizations or individuals can accept cryptocurrency donations directly through your platform.

• Specify the directionChange parameter with the value from.
• The amount parameter should represent the crypto price of the item or service.
• Paybis will calculate the equivalent cryptocurrency amount for payment, considering the exchange rate and any applicable fees.

This option allows the merchant receives the corresponding crypto amount.

Commission Allocation

The isReceivedAmount parameter determines which party (user or merchant) pays the transaction fees:

• isReceivedAmount: false (Default): The commission is deducted from the final amount received by the merchant. This means the user pays the full amount, and the merchant receives the crypto equivalent minus fees.
• isReceivedAmount: true: The commission is included in the initial amount paid by the user. This means the user pays the amount plus fees, and the merchant receives the full crypto equivalent.

Example Request Object:

{  
  "amount": "100",  
  "requestedCurrency": "USD",  
  "currencyCodeFrom": "ETH-SEPOLIA",  
  "currencyCodeTo": "USDT-TRC20-SHASTA",  
  "isReceivedAmount": false,  
  "payoutMethod": "ca-test-sell-ethereum-widget"  
}

{
  "amount": "100",             
  "currencyCodeFrom": "ETH-SEPOLIA",  
  "currencyCodeTo": "USDT-TRC20-SHASTA", 
  "directionChange": "from",    
  "isReceivedAmount": false,   
  "payoutMethod": "ca-test-sell-ethereum-widget" 
}

Example Response:

{
  "id": "b83f478f-227b-42a7-a53e-fed76d4cb222",
  "currencyCodeTo": "USDT-TRC20-SHASTA",
  "currencyCodeFrom": "ETH-SEPOLIA",
  "requestedAmount": {
    "amount": "100.00",
    "currencyCode": "USD"
  },
  "requestedAmountType": "from",
  "payoutMethods": [
    {
      "id": "ca-test-tether-trc-20",
      "name": "Tether",
      // ... other fields
    }
  ]
}

3. Transaction Request: Partner sends a request to Request API using the obtained quote ID and includes:

🚧

Please Note

For transactions, the user's crypto wallet address must align with the blockchain and asset type used for the payment.

4. Widget Integration and User Interaction

• Widget Launch: Partner initiates the Paybis Widget in an iFrame within the Partner checkout system.
  • Required URL parameters: layout=light&theme=paybiscryptoacquiring
  • Required iFrame attributes:
    • The first attribute is allow with values clipboard-read; clipboard-write *; payment ; camera ; microphone *
    • The second attribute is allowpaymentrequestwith value true
• Authentication: The Paybis system authenticates the User via email and sends an OTP for verification.
• One-Time Password (OTP) Verification: The user enters the received OTP into the Paybis Widget to proceed.

5. Transaction Completion:

• KYC Verification: If the transaction amount exceeds the No-KYC threshold, Paybis performs KYC verification.
• Payment Details: After verification, the widget displays the payment details including the wallet address and the amount due.
• Payment Execution: The User sends cryptocurrency from an external wallet to the specified Paybis wallet address.
• Transaction Confirmation: Paybis verifies the receipt of funds and updates the transaction status through a webhook to Partner.

📘

Until funds aren’t received and confirmed completely, End-User sees progress screens, and then success/failed screen

• successReturnURL/ failureReturnURL - after complete or reject of the transaction User could be redirected to the provided URL, if options were submitted.
• urlencodedUrl - a URL-encoded string for success and failure return URLs.

6. Event Handling and Redirection:

• Partner subscribes to front-end events to manage the widget based on transaction outcomes.

7. Payout Notification: After the crypto payout to the merchant's wallet is executed, Paybis notifies of the payout status via the Transaction Data Webhook.

Available Environments

Sandbox

Paybis provides a sandbox environment for the Partner to use for testing the APIs quickly and easily. The Sandbox environment includes a few differences from the production one making it suitable for testing.

• Please use sandbox API key, which will be provided during onboarding.
• Sandbox API URL - https://widget-api.sandbox.paybis.com/.
• IP whitelisting is not enforced in Sandbox, contrary to production.
• Crypto payouts are done using Testnet blockchain networks.

Supported Assets at Sandbox

Currently, testnet crypto pay -ins/-outs are allowed for the following cryptocurrencies:

Assets for Pay-in

Assets for Pay-out

🚧

We strongly recommend to test crypto payments for small amounts (i.e. <10 USD).
Testnet coins are challenging to obtain, so a return of the received testnet coins from Paybis is also greatly appreciated.

Production

• Partner should use production API key (will be provided by Paybis during Partner onboarding).
• Production API URL - https://widget-api.paybis.com/
• IP whitelisting will be enforced in Production, to be shared with Paybis, and enforced before going live.

API Specification

Paybis provides REST API endpoints that accept JSON as a request body and respond with JSON as output.

• List of API_BASE_URL to initiate transaction:
  • Currency pairs for swap crypto API Retrieve the list of supported cryptocurrencies for swaps.
  • Quote API Generate a quote with predefined crypto assets to provide users with estimated transaction details.
  • Request API Create a request to initiate a transaction based on the generated quote.
• PARTNER_WEBHOOK_URL: configurable per Partner

Quote Handling

Paybis Crypto Acquiring provides flexibility in handling quotes, allowing for both fiat- and crypto-denominated transactions:

• Quote with Fiat Amount: When the price of goods or services is set in fiat currency, the quote is generated based on the fiat amount, and Paybis calculates the equivalent cryptocurrency amount for payment.
• Quote with Crypto Amount: Alternatively, quotes can be generated based on a fixed cryptocurrency amount.

Authentication

Each request to Paybis API must include an API key in the Authorization HTTP header - Introduction