📘
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

OptionalPartner 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

POST /v1/userscreeningv1

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

POST /v1/post_v1-event

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.