📘
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.

Please use the sandbox API key, which will be provided during onboarding.
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.

Production

Please use the production API key, which will be provided during onboarding.
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: will be provided during onboarding
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.

API key will be assigned and provided to the Partner during onboarding.

Signing requests

All requests to the server should be signed with the private RSA key using theRSASSA_PSS_SHA_512signing algorithm. Paybis uses the public key to verify the signature and authenticity of your request.

Keys are generated by the partner, and the public key is provided to Paybis integration manager.

🚧
If the private key was lost or compromised, you need to notify the integration team immediately: the related public key stored on the Paybis end should be revoked and the new key pair should be generated.

Generating RSA keys

If you prefer to generate the key pair on your end, you can use the following commands:

Generate a private 4096-bit RSA key.

openssl genrsa -out private.key 4096

Create a public key from the private key.

openssl rsa -in private.key -outform PEM -pubout -out public.pub

Provide the public.pubkey to the Paybis integration manager.

Signing HTTP Requests

A signature should be generated from the private 4096-bit RSA key and HTTP request body hash using theRSASSA_PSS_SHA_512asymmetric signing algorithm. After that, the signature is encoded with Base64.

Signature = Base64(RSASSA_PSS_SHA_512(PRIVATE_KEY, SHA512(requestBody)))

A signature should be passed in theX-Request-SignatureHTTP header.

If the request signature validation fails, a 403 HTTP error code is returned.

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 direction

Partner → Paybis

Request

POST <API_BASE_URL>/v1/user-screening

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 direction

Partner → Paybis

Request

POST <API_BASE_URL>/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 API endpoint. Care must be taken to handle error responses and retry the request until a successful response from Paybis is received.

Request direction

Partner → Paybis

Request

POST <API_BASE_URL>/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"
    }
}

Transaction Data Webhook

Webhook on the successfully executed event, after the crypto transaction is submitted to the blockchain.

Request direction

Paybis → Partner

Request

POST <PARTNER_WEBHOOK_URL>

Parameter	Type	Description
event_id	REQUIRED uuid	Event id.
transaction_id	REQUIRED uuid	Transaction id. Paybis will return value from `payment.transaction.id` from the corresponding Event.
digital_amount_sent	REQUIRED object
digital_amount_sent.currency	REQUIRED string	Cryptocurrency is sent to the crypto address.
digital_amount_sent.amount	REQUIRED string	Crypto amount sent to the crypto address.
blockchain_txn_hash	OPTIONAL string	The blockchain transaction hash.

{
  "event_id": "0000079f-6981-4cd7-bf7b-88c5699eebb5",
  "transaction_id": "26e312b9-2206-1005-227e-f95808946cd3",
  "digital_amount_sent": {
    "currency": "BTC",
    "amount": "0.699999"
  },
  "blockchain_txn_hash": "492e43fa04ec86d7d4bc7deb38e4956312e78eb68d97824e73660a52283344ab"
}

Response

A successful HTTP response is expected (2xx code).

If Paybis receives any other status code in the response, the webhook request will be retried for up to 24 hours with exponential backoff.

Integration Guide

📘
Glossary

General Information

Business Process Flow

Use Case Description

Environments

Sandbox

Production

API Specification

📘
Strings length

Authentication

Signing requests

🚧

Generating RSA keys

Signing HTTP Requests

Crypto Address Screening API

Request direction

Request

Response

Quote API

Request direction

Request

Response

Execute API Endpoint

Request direction

Request

Response

Transaction Data Webhook

Request direction

Request

Response

📘Glossary

General Information

Business Process Flow

Use Case Description

Environments

Sandbox

Production

API Specification

📘Strings length

Authentication

Signing requests

🚧

Generating RSA keys

Signing HTTP Requests

Crypto Address Screening API

Request direction

Request

Response

Quote API

Request direction

Request

Response

Execute API Endpoint

Request direction

Request

Response

Transaction Data Webhook

Request direction

Request

Response

📘
Glossary

📘
Strings length