Algorithm of actions for integration:

1. You need to register an account on the website https://crosspay.net/ and provide us with the e-mail that was specified during registration.

2. Get in the account the keys that are used when interacting with the API, for this, you need to:

   2.1 Enter the account
   2.2 Open the "Profile" section
   2.3 Go to the "Security" tab and activate 2FA
   2.4 Go to the "API" tab and click the "Create API Keys" button*
   

   *Please note that keys are displayed once. If you have not saved them, repeat step 2.4.

3. Provide a list of domains from which transitions to the form will be performed (or on which the form will be installed into the iframe).*

4. Provide the IP-addresses from which API requests will be made.*

   *Information is required for security purposes.

5. Agree on business terms of providing the services.

6. Wait for setting the system settings.

API documentation is available here: https://docs.crosspay.net/

If you have any further questions regarding API or integration — contact us, and we will give you all the information needed!

Regards, Crosspay team.

To use this API, you need to have an account and access to features that you're going to use. In order to obtain suitable configuration for your case, you need to contact us ([email protected]).

In order to authenticate your requests, you should provide authentication parameters using http headers.

Authorization: %public_key%
Signature: %signature%

How to sign?

You need to generate a signature on your side, based on request data and your secret key. We use HMAC-SHA256.

There is a simple piece of PHP code that shows how to generate a signature:

/** @var \Psr\Http\Message\RequestInterface $request */
$signature = hash_hmac(
  'sha256',
  $request->getBody()->getContents(),
  $secretKey
);

$request->withHeader('Signature', $signature);

Or JavaScript/Node.js:

const hmac = require('crypto-js/hmac-sha256');

const body = {
    order_id: '123',
    currency: 'uah',
    wallet_type: 'ecom',
    amount: 10,
    payway: 'card',
    // ...
};

const signature = hmac(JSON.stringify(body), 'secretKey')
  .toString();

// 0a059c58184f388c6fe56bc07bf0b71f941ad85175283b5257fc9490422d9f6e

Or Python:

import hashlib
import hmac
import json


def sign(data: str, secret_key: str):
    secret_key = bytes(secret_key, "utf8")

    return hmac.new(secret_key, data.encode(), hashlib.sha256).hexdigest()

data = {
    'order_id': '123',
    'currency': 'uah',
    'wallet_type': 'ecom',
    'amount': 10,
    'payway': 'card',
    # ...
}

payload = json.dumps(data)
signature = sign(payload, 'secretKey')

print(signature)
# 0ff2fa58c4811407c4cd5fcb5adef76bf32c4213a579da5b17ebffb61525cb11

How to verify?

Also, each response and callback contains Signature header signed with your secret key. It is important to verify response/callback signature in order to prevent possible security vulnerabilities.

/** @var \Psr\Http\Message\ResponseInterface $response */
if($response->getHeaderLine('Signature') === hash_hmac('sha256', $response->getBody()->getContents(), $secretKey))
{
  // You can trust
}

In case you provide callback url for payin, payout order request or exchange, we'll send you a final status callback.

Only 200 OK http status is expected.

Callback example for fiat transaction:

{
  "status": "success",
  "data": [
    {
      "order_id": "18374512",
      "order_uuid": "f36e6bba-cf3a-11eb-a8a9-06b7db1f31a8",
      "order_type": "payin",
      "payway": "card",
      "currency_from": "uah",
      "wallet_from_type": "ecom",
      "wallet_from": "444111******4444",
      "amount_from": "300.00000000",
      "currency_to": "uah",
      "wallet_to": "71a34bc2-686c-4617-84c3-887fbef51925",
      "wallet_to_type": "ecom",
      "amount_to": "289.50000000",
      "currency_fee": "uah",
      "amount_fee": "10.50000000",
      "exchange_rate": "0.00000000",
      "card_system": "visa",
      "status": "completed",
      "message": "",
      "error_code": "0",
      "created": "2021-06-17 10:09:26",
      "updated": "2021-06-17 10:09:53",
      "client_id": "193336",
      "trusted_user": "1",
      "client_payments": "0",
      "card_mask": "444111******4444",
      "method": "card"
    }
  ]
}

Callback example for crypto transaction:

{
  "status": "success",
  "data": [
    {
      "order_id": "crypto_111111",
      "order_uuid": "72b34af3-9eeb-4d34-9c68-d471cc44927c",
      "order_type": "exchange",
      "payway": "crypto",
      "card_system": "",
      "currency_from": "btc",
      "wallet_from_type": "ecom",
      "wallet_from": "11a11111-6e11-11ed-1111-040300000000",
      "currency_to": "usdt",
      "wallet_to": "11e01a57-ca11-11ec-1111-06e0bfad8ad8",
      "wallet_to_type": "ecom",
      "currency_fee": "btc",
      "status": "completed",
      "message": "",
      "error_code": "0",
      "created": "2022-11-27 05:46:34",
      "updated": "2022-11-27 05:47:06",
      "is_test": "0",
      "trusted_user": "0",
      "card_mask": null,
      "attributes": [],
      "client_payments": "0",
      "client_id": "1111",
      "amount_from": "0.00715791",
      "amount_to": "117.20650276",
      "amount_fee": "0.00006579",
      "exchange_rate": "16526.3",
      "extra": {
          "tx_id": "c1111111111111111111111111",
          "explorer_url": "https://www.blockchain.com/btc/tx/c1111111111111111111111111",
          "address": "0x863F9f9D1dB21f3b4dcF28a0C7B3EB4D670C4551",
          "tag_or_memo": null
      },
      "method": "unknown"
    }
  ]
}

Final statuses

When order gets final statuses, processing stops. Theses statuses are:

• rejected
• completed
• overpaid
• underpaid
• canceled

Important:

You must consider status of your transaction only based on a valid response structure which contains the transaction and its status (see /api/v2/order/status).

Any other responses can't guarantee that your expectation and real state of the transaction match each other.

If you can't receive the expected status, please contact our support.

This feature addresses situations where the payer sends an amount that differs from the expected in the order.

Use Case:

1. Detection of discrepancies: The system automatically analyzes "payin" transactions and identifies underpayment or overpayment.
2. Display in the interface: Discrepancies are displayed in the system interface with a corresponding status ("underpaid", "overpaid") indicating underpayment or overpayment.

Important:

Please note that the parameters "amount_from", "amount_to", "amount_fee" are recalculated according to the authorized payer's amount.

Example:

Overpaid: In the case of overpayment, imagine the order was initially created for $100, but the customer sent $110. This means the customer has exceeded the specified order amount. The system recognizes this overpayment and reflects it, indicating that the customer has sent more funds than required.

Overpaid response example:

{
  "status": "success",
  "data": [
      {
          "order_id": "payin_uah-1706700562-uah_hosted_form",
          "order_uuid": "d3ca8b43-983a-465c-83f6-70a70172788d",
          "order_type": "payin",
          "payway": "card",
          "card_system": "",
          "currency_from": "uah",
          "wallet_from": "",
          "currency_to": "uah",
          "wallet_to": "346eb501-d50c-11ec-834c-06677a2a1e0e",
          "currency_fee": "uah",
          "status": "overpaid",
          "message": "",
          "error_code": "0",
          "created": "2024-01-31 13:29:23",
          "updated": "2024-01-31 13:29:54",
          "is_test": "0",
          "trusted_user": "0",
          "card_mask": null,
          "attributes": {
              "payment_form_locale": "en"
          },
          "method": "unknown",
          "wallet_from_type": "ecom",
          "wallet_to_type": "ecom",
          "client_payments": "0",
          "client_id": "1369",
          "amount_from": "110.00",
          "amount_to": "110.00",
          "amount_fee": "0",
          "exchange_rate": "1"
      }
  ]
}

Underpaid: For underpayment, consider a scenario where the order was created for $100, but the customer only sent $90. This signifies that the customer fell short of the expected payment. The system recognizes this overpayment and reflects it, indicating that the customer has sent fewer funds than required.

Underpaid response example:

{
  "status": "success",
  "data": [
    {
      "order_id": "payin_uah-1706700539-uah_hosted_form",
      "order_uuid": "322e7d8f-25fd-4e21-bbde-3f921f87391d",
      "order_type": "payin",
      "payway": "card",
      "card_system": "",
      "currency_from": "uah",
      "wallet_from": "",
      "currency_to": "uah",
      "wallet_to": "346eb501-d50c-11ec-834c-06677a2a1e0e",
      "currency_fee": "uah",
      "status": "underpaid",
      "message": "",
      "error_code": "0",
      "created": "2024-01-31 13:29:00",
      "updated": "2024-01-31 13:29:33",
      "is_test": "0",
      "trusted_user": "0",
      "card_mask": null,
      "attributes": {
        "payment_form_locale": "en"
      },
      "method": "unknown",
      "wallet_from_type": "ecom",
      "wallet_to_type": "ecom",
      "client_payments": "0",
      "client_id": "1369",
      "amount_from": "90.00",
      "amount_to": "90.00",
      "amount_fee": "0",
      "exchange_rate": "1"
    }
  ]
}

We provide possibility of accepting cryptocurrency payments by following scheme:

1. First of all, you need need to make /api/v2/client_address call in order to get unique address for each client. This address is assosiated only with this client. You can have multiple addresses for one client - they should be in different currencies. E.g. for client '1' you can have address in BTC and address in ETH.
2. After you get address for required currency, every transfer to that address will create order in Crosspay.
3. Also, Crosspay will generate callback for each order (as described in Callback section) to the url provided during /api/v2/client_address call.

At this point we are working on methods to deactivate address and list all orders for specified address or client, feel free to contact our support for proposals or improvements.

Payin description:

• Generate a new unique address for the customer and provide it to send the transfer;
• Customer makes the transfer to the address the merchant generated for this customer;
• Transfer confirmed on the blockchain;
• Crosspay creates the transaction;
• Crosspay will send the callback by the transaction was created that the merchant needs to handle and create the transaction on the merchant side. The callback will be sent on the callback_url that was provided on the address creating step «get_client_address» request.