Integration Guide
Glossary
Partner - a company or platform that utilizes the crypto settlement API to manage cryptocurrency transactions. Partners integrate with Paybis to enable cryptocurrency functionalities within their systems, allowing to offer crypto-related services to their clients - Merchants.
Merchant - a business entity that operates with Partner, utilizing the Partner's services to handle cryptocurrency transactions. Merchants are responsible for initiating crypto payments to end-users (Users) via the infrastructure provided by the Partner.
User - the end recipient of cryptocurrency payouts. Users interact with Merchantsβ platforms to receive crypto payments. They are the final beneficiaries in the cryptocurrency transaction process managed by the Partner and Merchant.
General Information
Business Process Flow
Use Case Description
Optional
Partner validates the wallet address with Paybis API - Crypto Address Screening API.- Recommended to avoid payout interruption.
- Partner gets a quote from Paybis - Quote API.
- Partner sends the payout request to Paybis - Execute API.
- Paybis accepts the requests and processes the crypto payout to the requested crypto address.
- Once the payout has been executed, Paybis notifies Partner of the status of the payout - Transaction Data Webhook.
- Settlements from Partner to Paybis should be covered by legal agreement.
Environments
Sandbox
Paybis provides a sandbox environment for partners 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.
- Sandbox API URL will be provided during onboarding.
- IP whitelisting is not enforced in Sandbox, contrary to production.
- Crypto payouts are done using Testnet blockchain networks.
More details can be found in the link.
Production
- Production API URL will be provided during onboarding.
- IP whitelisting will be enforced in Production, 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.
- API_BASE_URL: This can be found by the following link.
- PARTNER_WEBHOOK_URL: configurable per Partner
Strings length
Default length of string properties is 255 characters (if other is not specified).
Authentication
Each request to Paybis API must include an API key in the Authorization HTTP header and should be signed with the private RSA key.
Crypto Address Screening API
This optional endpoint allows the Partner to verify that the End-userβs entered crypto address is not problematic policy-wise. If Paybis rejects the address, the end user will have to enter a different crypto address.
Request
Parameter | Type | Description |
---|---|---|
crypto_currency | REQUIRED string | Crypto asset code (i.e. BTC, ETH). |
wallet_address | REQUIRED string | Crypto asset wallet address for the payout. |
{
"crypto_currency": "BTCβ,
"wallet_address": β13BgLTnJ9wfVgQePm9crVBfaxnTbPCqj61β
}
Response
Parameter | Type | Description |
---|---|---|
is_approved | boolean | True if the address passed screening, False if not. |
reason | string | The reason for addressing screening failure. Returned if only is_approved is False. |
Status-Code: 200 OK
{
"is_approved": false,
"reason": "User's wallet address is invalid"
}
Quote API
Provides the possibility to create a quote based on either fiat or crypto amount.
Request
[\[POST /v1/post_v1-quote\]](https://docs.payb.is/v3.2/reference/post_v1-quote)
Parameter | Type | Description |
---|---|---|
quote_id | REQUIRED uuid | Partner-generated identifier of a specific quote in UUID format. |
crypto_currency | REQUIRED string | Crypto asset code. |
fiat_currency | REQUIRED string | Fiat currency code. |
requested_currency | REQUIRED string | Base crypto or fiat currency for quote calculation, see request examples. |
requested_amount | REQUIRED string | Requested amount with precision 2 for fiat and 8 for crypto. |
Paybis will provide a list of enabled crypto and fiat currency pairs configured per specific partner.
{
"quote_id": "383b15d9-611f-4452-a973-00790ebc7835",
"crypto_currency": "BTC",
"fiat_currency": "USD",
"requested_currency": "BTC",
"requested_amount": "0.123456"
}
{
"quote_id": "fee931bb-de84-448a-bf19-4d38f819925a",
"crypto_currency": "BTC",
"fiat_currency": "USD",
"requested_currency": "USD",
"requested_amount": "123.45"
}
Response
Parameter | Type | Description |
---|---|---|
quote_id | uuid | Identifies a specific quote. |
time | datetime | Quote creation timestamp. |
expiration | datetime | Quote expiration timestamp. |
digital_money | object | |
digital_money.currency | string | Digital currency code. |
digital_money.amount | string | Digital currency amount. |
fiat_money | object | |
fiat_money.currency | string | Fiat currency code. |
fiat_money.amount | string | Fiat currency amount. |
Status-Code: 201 Created
{
"status": "ok",
"result": {
"quote_id": "383b15d9-611f-4452-a973-00790ebc7835",
"digital_money": {
"currency": "BTC",
"amount": "1.03"
},
"fiat_money": {
"currency": "USD",
"amount": "5304.29"
},
"time": "2023-09-16T11:10:00"
"expiration": "2023-09-16T11:20:00"
}
}
Execute API Endpoint
There is an option to pass the crypto payout request to Paybis by using the API endpoint. Care must be taken to handle error responses and retry the request until a successful response from Paybis is received.
Request
Parameter | Type | Description |
---|---|---|
event_id | REQUIRED uuid | Unique event identifier in UUID format. Paybis will use this ID as an idempotency key. |
name | REQUIRED string | Event name. Must be constant payment_execute . |
timestamp | REQUIRED datetime | Request timestamp. |
payment | REQUIRED object | |
payment.transaction | REQUIRED object | Transaction details. |
payment.transaction.id | REQUIRED uuid | Payment transaction identifier generated by Partner, i.e. specific payout id |
payment.transaction.order_id | REQUIRED uuid | Order identifier generated by Partner, i.e. mass payout id |
payment.transaction.quote_id | REQUIRED uuid | Referenced quote id. Must be a valid and not expired quote. |
payment.transaction.fiat | REQUIRED object | |
payment.transaction.fiat.currency | REQUIRED string | Fiat currency of the transaction. Must match the quote fiat currency. |
payment.transaction.fiat.amount | REQUIRED string | Fiat amount of the transaction. Must match the quoted fiat amount. |
payment.transaction.crypto | REQUIRED object | |
payment.transaction.crypto.currency | REQUIRED string | Cryptocurrency of the transaction. Must match the quote cryptocurrency. |
payment.transaction.crypto.amount | REQUIRED string | Crypto amount of the transaction. Must match the quote crypto amount. |
payment.transaction.merchant | REQUIRED string | Crypto transaction sender. Must be a string up to 16 characters in length. |
payment.crypto_destination.type | REQUIRED string | Destination crypto address type. Must be constant user . |
payment.crypto_destination.crypto_address | REQUIRED string | Destination crypto wallet address. |
payment.crypto_destination.user | REQUIRED object | Crypto transaction beneficiary details. |
payment.crypto_destination.user.user_id | REQUIRED string | Receiver name. Must be an alphanumeric string w/o spaces. Max length: 70 characters. |
{
"event_id": "0000079f-6981-4cd7-bf7b-88c5699eebb5",
"name": "payment_execute",
"payment": {
"transaction": {
"id": "26e312b9-2206-1005-227e-f95808946cd3",
"order_id": "7e67bcad-36b9-757e-eddf-96c904228cb9",
"quote_id": "32b5d20c-e281-41e4-9035-1263ed8eeb04",
"fiat": {
"amount": "13853.96",
"currency": "USD"
},
"crypto": {
"amount": "0.31488388",
"currency": "BTC"
},
"merchant": "sender-name"
},
"crypto_destination": {
"type": "user",
"crypto_address": "1CoYiGR7S7CiWn75bTYpFMTr6n5SxX8zZz",
"user": {
"user_id": "receiver-name"
}
}
},
"timestamp": "2023-09-16T18:07:55.769Z"
}
Response
{
"status": "ok",
"result": {
"event_id": "87e2d429-529b-4542-b366-704d1e591750",
"name": "payment_execute",
"payment": {
"transaction": {
"id": "6f0f0b4d-de82-428b-a298-a4a06392f175",
"order_id": "7b3e9d21-54a3-403a-bc06-00627df2976f",
"quote_id": "850c535d-5d58-4b6f-86ee-c0614c86ff45",
"fiat": {
"amount": "7.10",
"currency": "USD"
},
"crypto": {
"amount": "7.000000",
"currency": "USDT-TRC20"
},
"merchant": "advertiser-name"
},
"crypto_destination": {
"type": "user",
"crypto_address": "TXJApRfPs1BbwDdYGT9AVQkZg8UeFuwgoy",
"user": {
"user_id": "getrid-oldauth"
}
}
},
"timestamp": "2023-09-16T18:07:55+00:00"
}
}
Technical Support
If you have any questions or encounter issues during integration, please contact your account manager for assistance with the Paybis Send API, signing requests, webhooks, sandbox setup, and pre-funded balance inquiries.
Updated 5 months ago