Integrating Crypto Acquiring
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
-
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.
-
Quote Retrieval
2.1. Quote Retrieval - Amount Set in Crypto
Business Use Case: Non-profit organizations or individuals can accept cryptocurrency donations directly through your platform.
-
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.2.2. Quote Retrieval - Amount set in Fiat equivalent
Business Use Case: E-commerce platforms or online businesses can allow customers to purchase goods or services using cryptocurrencies.
To support this use case, Quote API has been extended with the following field: requestedCurrency
field (Optional)
This field is used in crypto-acquiring transactions where the price is denominated in fiat. It specifies the fiat currency in which the amount is denominated.
Example Request Object:
{
"amount": "100",
"requestedCurrency": "USD",
"currencyCodeFrom": "ETH-SEPOLIA",
"currencyCodeTo": "USDT-TRC20-SHASTA",
"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
}
]
}
- Transaction Request: Partner sends a request to Request API using the obtained
quote ID
and includes:
Parameter | Type | Description |
---|---|---|
quoteId | REQUIRED | Transaction will start with a predefined amount and crypto. |
locale | REQUIRED | The customerβs preferred locale in ISO alpha-2 format. |
partnerUserId | REQUIRED | The customer's unique ID in Partner's system |
email | REQUIRED | User's email address. |
payoutMethod | REQUIRED | ID of the payout method associated with the quote. |
cryptoWalletAddress | REQUIRED | Merchant's crypto wallet address for receiving the payout. |
cryptoWalletAddressForRefund | OPTIONAL | End-user's crypto wallet address for refunds must be in the same blockchain and asset type as the payment. |
salesItemDescription | OPTIONAL | Description of the item being sold. |
merchantCompanyName | REQUIRED | Merchant's company name. |
flow | REQUIRED | Set to swapCrypto |
Please Note
For transactions, the user's crypto wallet address must align with the blockchain and asset type used for the payment.
- 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
valuetrue
- The first attribute is allow with values
- Required URL parameters:
- 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.
- 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.
- Event Handling and Redirection:
- Partner subscribes to front-end events to manage the widget based on transaction outcomes.
- 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
Currency name | Asset ID | Blockchain |
---|---|---|
Ethereum Sepolia | ETH-SEPOLIA | ethereum |
Assets for Pay-out
Currency name | Asset ID | Blockchain |
---|---|---|
Tether | USDT-TRC20-SHASTA | tron |
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
Updated 8 days ago