# DeusX Pay API Documentation

> Last updated: 2026-06-17
> Machine-readable mirror of https://console.deusxpay.com/docs/api

DeusX Pay is a crypto payments gateway. This document describes the v1 REST API.
The API base URL is `https://api.deusxpay.com/pay/`.

## Introduction

Deus X Pay is a crypto payments gateway enabling seamless integration options for your existing website.

Deus X Pay can be integrated into your website in either of three ways:

- **Deus X Pay Payment Button:** This is a Javascript based payment button for instantly accepting payments on your website.
- **API:** This is a server side integration with Deus X Pay, including additional functionality over the Deus X Pay Payment Button.
- **WooCommerce:** This is a plugin designed to accept crypto payments using a wordpress checkout page
    - NOTE: this is available to selected clients only - please contact your relationship manager should you wish to implement the WooCommerce plugin.

Building an integration with an AI coding assistant? An LLM-readable version of this documentation is available at /llms.txt.

### General Terminology

| Term | Meaning |
| --- | --- |
| Payment | A payment contains payment details for your customers to deposit crypto. Depending on your payment configuration and settings, an automatic conversion may be processed once the applicable payment amount has been received. |
| Purchase payment | A payment where there is a set required amount. In cases of over- or underpayment, the payment status will be updated to inform you of any manual interventions required to process completion. A single payment ID will exist for all deposits to the payment address. |
| Account payment | A payment where there is no required amount required for each deposit. Each successful deposit will automatically be allocated to your customer’s account with a unique payment ID. |
| Profile | Parts of a merchant's settings. Controls how currencies and markups are applied to payments and optionally specifies webhook and email notifications for events in the payment lifecycle. |
| Transaction | A blockchain transaction related to a payment address in Deus X Pay. Each blockchain transaction sent to a given payment address is recorded for ease of reconciliation. |
| Withdrawal | A digital currency withdrawal for settling funds received. Funds are settled from a fiat or digital wallet balance and may require a conversion. There is a cost associated with blockchain transactions processed through withdrawal requested. Withdrawal fees are charged based on your agreed fee schedule. |
| Payout | A bank payout for settling funds received. Funds are settled from a fiat wallet balance and paid to your registered bank account through wire transfer. There is a cost associated with processing bank transfers - payout fees are charged based on your agreed fee schedule. |

## Getting Started

### Account Setup

1. [Registering your Deus X Pay account](https://support.deusxpay.com/article/137-how-do-i-register-for-deus-x-pay)
2. [Logging in to the Deus X Pay Console](https://console.deusxpay.com/)

### Integration

1. Creating new API keys (see [API Authentication](#api-authentication))
2. Setting up webhooks (see [Webhooks](#webhooks))
3. Embedding the Deus X Pay Payment Button (see [DXP Payment Button (SDK)](#dxp-payment-button-sdk))

### API Authentication

You can obtain API Keys by logging in and creating a key in **Settings > Integrations**. This will give you both an "API Key" that will serve as your user name, and an "API Secret" that you will use to sign messages.

All requests must contain a **nonce**, a number that will never be repeated and must increase between requests. This is to prevent an attacker who has captured a previous request from simply replaying that request. We recommend using a timestamp at millisecond or higher precision.

#### Payload

The payload for the POST requests must be a JSON string and must be put in the request body. You'll find more detailed signature generation code in the examples. The following four headers are required to make requests to the Deus X Pay API.

| Header | Value |
| --- | --- |
| X-DEUSXPAY-KEY | Your Deus X Pay API Key |
| X-DEUSXPAY-NONCE | Nonce |
| X-DEUSXPAY-SIGNATURE | SHA256 signature |
| Content-Type | application/json |

### Code Signing Examples

**Note:** When generating a signature for a request, request paths should be used exclusive of any url or path parameters i.e if your request url is `/v1/payments/d7f93fa7-b5b4-4004-af2d-1c7ca766bb40` then the request path used in your signature should be: `/v1/payments/`

#### Javascript

```javascript
const axios = require('axios');
const Base64 = require('js-base64').Base64;
const crypto = require('crypto');
const url = require('url');

// This is used for production configuration. For pre-production integration it should be prepended
// with the correct environment url i.e https://preprod-api.deusxpay.com and the apiKey and apiSecret should be specific
// to that environment.

const apiUrl = 'https://api.deusxpay.com/pay';
const apiKey = 'your_api_key';
const apiSecret = 'your_api_secret';

function encodeHmac(key, msg) {
    return crypto.createHmac('sha256', key).update(msg).digest('hex');
}

function deusxpayApiRequest(endpoint, payload = null, method = 'GET') {
    const nonce = (new Date).getTime().toString()

    // Parse the endpoint to separate path and query parameters
    const parsedUrl = url.parse(endpoint, true);
    const basePath = '/v1/' + parsedUrl.pathname;
    const requestPath = basePath.endsWith('/') ? basePath : basePath + '/';

    // Prepare query parameters
    const queryParams = new URLSearchParams(parsedUrl.query).toString();

    // Prepare payload
    let stringPayload = '';
    if (method !== 'GET' && payload) {
        if (typeof payload === 'object') {
            stringPayload = JSON.stringify(payload);
        } else if (typeof payload === 'string') {
            stringPayload = payload;
        }
    }

    // Create signature data object. Keep order of keys as specified:
    const signatureData = {
        path: requestPath,
        nonce: nonce,
        payload: stringPayload,
    };

    // Convert signature data to json + base64 format and create signature using your apiSecret
    const signatureDataString = JSON.stringify(signatureData);
    const b64 = Base64.encode(signatureDataString);

    const signature = encodeHmac(apiSecret, b64);

    // Add your API key, nonce and signature to following headers
    const requestHeaders = {
        'X-DEUSXPAY-KEY': apiKey,
        'X-DEUSXPAY-NONCE': nonce,
        'X-DEUSXPAY-SIGNATURE': signature,
        'Content-Type': 'application/json'
    };

    const fullUrl = apiUrl + requestPath + (queryParams ? `?${queryParams}` : '');

    return axios({
        method: method,
        url: fullUrl,
        data: method !== 'GET' ? payload : undefined,
        headers: requestHeaders,
        httpsAgent: new (require('https').Agent)({ rejectUnauthorized: false }), // Note: remove this line when running in a production environment with a valid certificate.
    });
}

// EXAMPLE REQUESTS
// Example requests for various API requests can be found below. Uncomment and use as needed.

// GET Request
deusxpayApiRequest('payments').then(function (response) {
    console.log(JSON.stringify(response.data, null, 2));
}).catch(function (error) {
    console.log(error);
});

// GET Request with query parameters
// deusxpayApiRequest('payments?p=4').then(function (response) {
//     console.log(JSON.stringify(response.data, null, 2));
// }).catch(function (error) {
//     console.log(error);
// });

// GET by ID Request
// deusxpayApiRequest('payments/d7f93fa7-b5b4-4004-af2d-1c7ca766bb40').then(function (response) {
//     console.log(JSON.stringify(response.data, null, 2));
// }).catch(function (error) {
//     console.log(error);
// });

// POST Request
// const requestBody = {
//     requested_currency: "USD",
//     requested_amount: "25",
//     payment_currency: "ETH",
//     profile_uuid: "bacc5b65-767f-463c-b4cd-a0c24a8edb41",
//     passthrough: JSON.stringify({order_id: 12345}, null, 0),
//     notes: "Test payment"
// }

// deusxpayApiRequest('payments', requestBody, 'POST').then(function (response) {
//     console.log(JSON.stringify(response.data, null, 2))
// }).catch(function (error) {
//     console.log(error);
// });
```

#### PHP

```php
<?php

// This is used for production configuration. For pre-production integration it should be prepended
// with the correct environment url i.e https://preprod-api.deusxpay.com and the API_KEY and API_SECRET should be specific
// to that environment.

$API_URL = 'https://api.deusxpay.com/pay';
$API_KEY = 'your_api_key';
$API_SECRET = 'your_secret';

function encode_hmac($key, $msg) {
    return hash_hmac('sha256', $msg, $key);
}

function deusxpay_api_request($endpoint, $payload = null, $method = 'GET') {
    global $API_URL, $API_KEY, $API_SECRET;

    $nonce = (string)(round(microtime(true) * 1000));

    // Parse the endpoint to separate path and query parameters
    $parsed_url = parse_url($endpoint);
    $base_path = '/v1/' . (isset($parsed_url['path']) ? $parsed_url['path'] : '');
    $request_path = rtrim($base_path, '/') . '/';

    // Prepare query parameters
    $query_params = isset($parsed_url['query']) ? $parsed_url['query'] : '';

    // Prepare payload
    $string_payload = '';
    if ($method !== 'GET' && $payload) {
        if (is_array($payload)) {
            $string_payload = json_encode($payload, JSON_UNESCAPED_SLASHES);
        } elseif (is_string($payload)) {
            $string_payload = $payload;
        }
    }

    // Create signature data object. Keep order of keys as specified:
    $signature_data = [
        'path' => $request_path,
        'nonce' => $nonce,
        'payload' => $string_payload,
    ];

    // Convert signature data to json + base64 format and create signature using your API_SECRET
    $signature_data_string = json_encode($signature_data, JSON_UNESCAPED_SLASHES);
    $b64 = base64_encode($signature_data_string);

    $signature = encode_hmac($API_SECRET, $b64);

    // Prepare headers
    $request_headers = [
        'X-DEUSXPAY-KEY: ' . $API_KEY,
        'X-DEUSXPAY-NONCE: ' . $nonce,
        'X-DEUSXPAY-SIGNATURE: ' . $signature,
        'Content-Type: application/json'
    ];

    $full_url = $API_URL . $request_path . ($query_params ? "?{$query_params}" : '');

    // Initialize cURL
    $ch = curl_init();

    // Set cURL options
    curl_setopt($ch, CURLOPT_URL, $full_url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $request_headers);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // Note: remove this line when running in a production environment with a valid certificate.

    if ($method !== 'GET') {
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        if ($string_payload) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, $string_payload);
        }
    }

    // Execute the request
    $response = curl_exec($ch);

    // Check for cURL errors
    if (curl_errno($ch)) {
        $error = curl_error($ch);
        curl_close($ch);
        throw new Exception("cURL Error: " . $error);
    }

    // Get the HTTP status code
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    // Close cURL resource
    curl_close($ch);

    // Return the response as an associative array
    $decoded_response = json_decode($response, true);

    // If there's an error, throw an exception
    if ($http_code >= 400) {
        throw new Exception(json_encode($decoded_response, JSON_PRETTY_PRINT));
    }

    return $decoded_response;
}

// EXAMPLE REQUESTS
// Example requests for various API requests can be found below. Uncomment and use as needed.

// GET Request
try {
    $response = deusxpay_api_request('payments');
    echo json_encode($response, JSON_PRETTY_PRINT) . "\n";
} catch (Exception $e) {
    echo $e->getMessage() . "\n";
}

// GET Request with query parameters
// try {
//     $response = deusxpay_api_request('payments?p=4');
//     echo json_encode($response, JSON_PRETTY_PRINT) . "\n";
// } catch (Exception $e) {
//     echo $e->getMessage() . "\n";
// }

// // GET By ID Request.
// try {
//     $response = deusxpay_api_request('payments/bdc884c9-32cf-4e44-adf9-ac9078d605bb');
//     echo json_encode($response, JSON_PRETTY_PRINT) . "\n";
// } catch (Exception $e) {
//     echo $e->getMessage() . "\n";
// }

// POST Request
// $request_body = [
//     'requested_currency' => "USD",
//     'requested_amount' => "25",
//     'payment_currency' => "ETH",
//     'profile_uuid' => "bacc5b65-767f-463c-b4cd-a0c24a8edb41",
//     'passthrough' => json_encode(['order_id' => 12345], JSON_FORCE_OBJECT),
//     'notes' => "Test payment"
// ];

// try {
//     $response = deusxpay_api_request('payments', $request_body, 'POST');
//     echo json_encode($response, JSON_PRETTY_PRINT) . "\n";
// } catch (Exception $e) {
//     echo $e->getMessage() . "\n";
// }
```

#### Python

```python
import requests
import json
import time
import hmac
import hashlib
import base64
from urllib.parse import urlparse, parse_qsl, urlencode

# This is used for production configuration. For pre-production integration it should be prepended
# with the correct environment url i.e https://preprod-api.deusxpay.com/pay and the API_KEY and API_SECRET should be specific
# to that environment.

API_URL = 'https://api.deusxpay.com/pay'
API_KEY = 'your_api_key'
API_SECRET = 'your_secret'

def encode_hmac(key, msg):
    return hmac.new(key.encode(), msg, hashlib.sha256).hexdigest()

def deusxpay_api_request(endpoint, payload=None, method='GET'):
    nonce = str(int(time.time() * 1000))

    # Parse the endpoint to separate path and query parameters
    parsed_url = urlparse(endpoint)
    base_path = '/v1/' + parsed_url.path
    request_path = base_path if base_path.endswith('/') else base_path + '/'

    # Prepare query parameters
    query_params = urlencode(parse_qsl(parsed_url.query))

    # Prepare payload
    string_payload = ''
    if method != 'GET' and payload:
        if isinstance(payload, dict):
            string_payload = json.dumps(payload)
        elif isinstance(payload, str):
            string_payload = payload

    # Create signature data object. Keep order of keys as specified:
    signature_data = {
        'path': request_path,
        'nonce': nonce,
        'payload': string_payload,
    }

    # Convert signature data to json + base64 format and create signature using your API_SECRET
    signature_data = json.dumps(signature_data, separators=(',', ':'))
    signature_data = signature_data.encode()
    b64 = base64.b64encode(signature_data)

    signature = encode_hmac(API_SECRET, b64)

    # Add your API key, nonce and signature to following headers
    request_headers = {
        'X-DEUSXPAY-KEY': API_KEY,
        'X-DEUSXPAY-NONCE': nonce,
        'X-DEUSXPAY-SIGNATURE': signature,
        'Content-Type': 'application/json'
    }

    full_url = API_URL + request_path + ('?' + query_params if query_params else '')


    response = requests.request(
        method,
        full_url,
        headers=request_headers,
        data=string_payload if method != 'GET' else None,
        verify=False  # Note: remove this parameter when running in a production environment with a valid certificate.
    )

    return response

# EXAMPLE REQUESTS
# Example requests for various API requests can be found below. Uncomment and use as needed.

# GET Request
try:
    response = deusxpay_api_request('payments')
    print(f"Status Code: {response.status_code}")
    print(f"Response Headers: {json.dumps(dict(response.headers), indent=2)}")
    print(f"Response Body: {json.dumps(response.json(), indent=2)}")
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

# GET Request with query parameters
# try:
#     response = deusxpay_api_request('payments?p=4')
#     # print(f"Status Code: {response.status_code}")
#     # print(f"Response Headers: {json.dumps(dict(response.headers), indent=2)}")
#     print(f"Response Body: {json.dumps(response.json(), indent=2)}")
# except requests.exceptions.RequestException as e:
#     print(f"Error: {e}")

# GET by ID Request
# try:
#     response = deusxpay_api_request('payments/c67ad477-bbcf-448e-ba99-88d0935e4cf1')
#     # print(f"Status Code: {response.status_code}")
#     # print(f"Response Headers: {json.dumps(dict(response.headers), indent=2)}")
#     print(f"Response Body: {json.dumps(response.json(), indent=2)}")
# except requests.exceptions.RequestException as e:
#     print(f"Error: {e}")

# POST Request
# request_body = {
#     "requested_currency": "USD",
#     "requested_amount": "25",
#     "payment_currency": "ETH",
#     "profile_uuid": "bacc5b65-767f-463c-b4cd-a0c24a8edb41",
#     "passthrough": json.dumps({"order_id": 12345}),
#     "notes": "Test payment"
# }

# try:
#     response = deusxpay_api_request('payments', request_body, 'POST')
#     print(f"Status Code: {response.status_code}")
#     print(f"Response Headers: {json.dumps(dict(response.headers), indent=2)}")
#     print(f"Response Body: {json.dumps(response.json(), indent=2)}")
# except requests.exceptions.RequestException as e:
#     print(f"Error: {e}")
```

## General Usage

### Payment Lifecycle

Deus X Pay's advanced platform offers a multitude of payment types:

- **Purchase payments:** Your business gets paid in crypto and you receive the equivalent amount in the currency of your choice.
- **Account payments:** Your customer can transfer any amount in crypto to top up their crypto wallet.

### Steps to receiving payments

1. You create a payment with an associated wallet address.
2. You display payment details to your customer in order to receive an amount.
3. Your customer transfers an amount to a specified payment address.
4. Deus X Pay processes the payment amount received from your customer.
5. You settle your received funds as a crypto withdrawal or bank payout

### Purchase payments

Should you wish to receive an exact amount for goods or services listed on your website, you will require your customer to send an equivalent payment amount in cryptocurrency.

In such cases, automatic conversion will only occur when the payment amount received is sufficient to complete the payment.

Purchase payments display a unique payment address for each payment created.

Once the payment is completed, the address is no longer required to process the payment.

There may be times where the payment amount received is not converted, such as in the case of under- or overpayment. For more detailed information, see [Manual interventions for payment processing](#manual-interventions-for-payment-processing).

The workflow below describes the typical process for a purchase payment.

1. As a merchant, you want to receive a specified requested amount for goods or services listed for sale.
2. Your customer adds the desired products to their cart and begins the checkout process.
3. Your website requests an indicative payment amount in cryptocurrency from Deus X Pay APIs for your customer to process payment for the order.
4. Your website displays the indicative payment amount and payment address(es) returned in the API response.
5. Your customer uses their crypto wallet to deposit the payment amount to the specified payment address(es). An optional webhook response is sent to your web server.
6. Once enough crypto has been deposited to the payment address, the payment will be marked as "Complete" after any associated conversions have been completed. Optional webhook responses are sent to your web server.

### Account payments

Should you wish to receive multiple deposits for any amount to be credited to the same payment address, using an account payment will ensure that any amount received will automatically be converted upon receipt of the transaction.

The payment will automatically become complete once the amount is received and allocated.

Each deposit to the same payment address will generate a new payment ID.

Thereafter, subsequent deposits will be related to the original ("parent") payment through the Parent ID field:

The _parent_payment_id_ attribute is visible on the Pay Console and included in related payment webhooks. The related webhooks will contain the same notes and passthrough values as the parent payment (refer to the [Payment Model](#the-payment-model) for more details).

The workflow above remains the same, however, instead of requesting a specific amount, you will leave the requested amount blank when using [Create Payment](#create-payment).

### Supported Currencies

| Currency | Supported Testnet Networks | Supported Mainnet Networks |
| --- | --- | --- |
| ADA | ADA Network [Testnet] | ADA Network [Mainnet] |
| BNB | BSC Network (BEP20) [Testnet] | BSC Network (BEP20) |
| BTC | BTC Network [Testnet] | BTC Network [Mainnet] |
| DOGE | DOGE Network [Testnet] | DOGE Network [Mainnet] |
| ETH | ETH Network [Sepolia] | ETH Network (ERC20) |
| HYPE | HYPE Network [Testnet] | HYPE Network [Mainnet] |
| SOL | SOL Network [Devnet] | SOL Network [Mainnet] |
| TRX | TRX Network [Shasta] | TRX Network (TRC20) |
| XRP | XRP Network [Testnet] | XRP Network [Mainnet] |
| USDC | ETH Network [Sepolia], TRX Network (TRC20), SOL Network [Devnet] | ETH Network (ERC20), BSC Network (BEP20), SOL Network |
| USDT* | BSC Network (BEP20) [Testnet] | ETH Network (ERC20), BSC Network (BEP20), TRX Network (TRC20), SOL Network |
| AED | - | - |
| AUD | - | - |
| EUR | - | - |
| GBP | - | - |
| USD | - | - |
| ZAR | - | - |

*TUSDT can be used in testnet by adding the token contract address 0x3842BD7EC378C2a1149cCE4Aa865B0aD834bf1BF. You can contact us with your Sepolia wallet address and we will send you tokens to test with.

## Accounts (Deprecated)

**Deprecated:** The Accounts API is deprecated. Please use the [Wallets](#wallets) API instead.

Accounts are entities reflecting your balances in the different supported currencies.

### The Account Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the account. |
| currency - string | The currency of the account. |
| balances - object | An object with the two accounts balances, total and held. |

### Get Accounts

This endpoint retrieves all accounts. It is not paginated.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/accounts`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| id | None | The account's ID. |
| currency | None | The account's currency. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/accounts`

```json
{
    "result": [
        {
            "id": "f0338eda-77aa-4636-bee1-20f8b6e92e4f",
            "currency": "EUR",
            "balances": {
                "total": 49.43,
                "held": 0
            }
        },
        {
            "id": "03022fb1-2500-4cb0-8126-538d92c3b59d",
            "currency": "USDT",
            "balances": {
                "total": 0,
                "held": 0
            }
        },
        {
            "id": "16f9d1d0-ef00-4d12-9369-325bb4c1c449",
            "currency": "AED",
            "balances": {
                "total": 5172.06,
                "held": 110
            }
        }
    ]
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/accounts?id=111`

```json
{
    "result": {
        "message": "id must be a uuid",
        "reason": "invalid_request",
        "result": "error"
    }
}
```

## Wallets

Wallets are containers for your accounts across different currencies. Each wallet has a name and holds one or more currency accounts with their respective balances.

### The Wallet Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the wallet. |
| name - string | The name of the wallet. |
| accounts - object array | The accounts that belong to the wallet, each containing an id, currency, and balances (total and held). |
| created_at - string | The date and time the wallet was created. |
| updated_at - string | The date and time the wallet was last updated. |

### Create Wallet

This endpoint creates a new wallet.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/wallets`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| name | Name of the wallet. | Yes |
| currencies | Currencies to be added to the wallet. | Yes |

**Responses**

201 Successful Response

Request:

```json
{
    "name": "My Trading Wallet",
    "currencies": [
        "BTC",
        "ETH",
        "USDT"
    ]
}
```

Response:

```json
{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Trading Wallet",
    "accounts": [
        {
            "id": "f0338eda-77aa-4636-bee1-20f8b6e92e4f",
            "currency": "BTC",
            "balances": {
                "total": 0,
                "held": 0
            }
        },
        {
            "id": "03022fb1-2500-4cb0-8126-538d92c3b59d",
            "currency": "ETH",
            "balances": {
                "total": 0,
                "held": 0
            }
        },
        {
            "id": "16f9d1d0-ef00-4d12-9369-325bb4c1c449",
            "currency": "USDT",
            "balances": {
                "total": 0,
                "held": 0
            }
        }
    ],
    "created_at": "2025-11-10T07:22:23.108Z",
    "updated_at": "2025-11-10T07:22:23.108Z"
}
```

400 Bad Request

```json
{
    "result": "error",
    "reason": "invalid_request",
    "message": "name must be a string"
}
```

### Update Wallet

This endpoint updates a specific wallet.

**HTTP Request**

`PATCH https://api.deusxpay.com/pay/v1/wallets/[ID]`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the wallet. |

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| name | Name of the wallet. | No |
| currencies | Currencies to be added to the wallet. | No |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/wallets/a1b2c3d4-e5f6-7890-abcd-ef1234567890`

Request:

```json
{
    "name": "Updated Wallet Name",
    "currencies": [
        "SOL"
    ]
}
```

Response:

```json
{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Updated Wallet Name",
    "accounts": [
        {
            "id": "f0338eda-77aa-4636-bee1-20f8b6e92e4f",
            "currency": "BTC",
            "balances": {
                "total": 0,
                "held": 0
            }
        },
        {
            "id": "03022fb1-2500-4cb0-8126-538d92c3b59d",
            "currency": "ETH",
            "balances": {
                "total": 0,
                "held": 0
            }
        },
        {
            "id": "16f9d1d0-ef00-4d12-9369-325bb4c1c449",
            "currency": "USDT",
            "balances": {
                "total": 0,
                "held": 0
            }
        },
        {
            "id": "7a8b9c0d-1e2f-3456-7890-abcdef123456",
            "currency": "SOL",
            "balances": {
                "total": 0,
                "held": 0
            }
        }
    ],
    "created_at": "2025-11-10T07:22:23.108Z",
    "updated_at": "2025-11-12T10:15:42.331Z"
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/wallets/a1b2c3d4-e5f6-7890-abcd-000000000000`

```json
{
    "result": "error",
    "message": "Wallet a1b2c3d4-e5f6-7890-abcd-000000000000 not found",
    "reason": "wallet_not_found"
}
```

### Get Wallets

This endpoint retrieves all wallets. It uses pagination and returns 25 wallets per page. Wallets are sorted by creation time in descending order.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/wallets`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| id | None | Filter wallets by ID. |
| name | None | Filter wallets by name. |
| p | None | Page number. |
| size | 25 | Number of results per page. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/wallets`

```json
{
    "result": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "My Trading Wallet",
            "accounts": [
                {
                    "id": "f0338eda-77aa-4636-bee1-20f8b6e92e4f",
                    "currency": "BTC",
                    "balances": {
                        "total": 1.5,
                        "held": 0.1
                    }
                },
                {
                    "id": "03022fb1-2500-4cb0-8126-538d92c3b59d",
                    "currency": "ETH",
                    "balances": {
                        "total": 10.25,
                        "held": 0
                    }
                }
            ],
            "created_at": "2025-11-10T07:22:23.108Z",
            "updated_at": "2025-11-10T07:22:23.108Z"
        },
        {
            "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "name": "Settlement Wallet",
            "accounts": [
                {
                    "id": "16f9d1d0-ef00-4d12-9369-325bb4c1c449",
                    "currency": "USD",
                    "balances": {
                        "total": 50000,
                        "held": 1200
                    }
                }
            ],
            "created_at": "2025-10-05T14:30:00.000Z",
            "updated_at": "2025-10-05T14:30:00.000Z"
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 2,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/wallets?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

### Get Wallet Summary

This endpoint returns the currency summary across all wallets, including the total and held balances for each currency.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/wallets/summary`

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/wallets/summary`

```json
{
    "result": [
        {
            "currency": "USDT",
            "total": 100,
            "held": 1.23
        },
        {
            "currency": "USDC",
            "total": 50,
            "held": 50
        },
        {
            "currency": "BTC",
            "total": 0.01,
            "held": 0
        },
        {
            "currency": "ETH",
            "total": 3.418261,
            "held": 0.028411
        },
        {
            "currency": "EUR",
            "total": 6148.2,
            "held": 3559.37
        }
    ]
}
```

### The Transfer Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the transfer. |
| amount - string | The amount transferred. |
| currency - string | The currency of the transfer. |
| from_wallet_id - string | The ID of the source wallet. |
| to_wallet_id - string | The ID of the destination wallet. |
| created_at - string | The date and time the transfer was created. |
| updated_at - string | The date and time the transfer was last updated. |

### Create Transfer

This endpoint creates a transfer between two wallets.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/transfers`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| from_wallet_id | The ID of the source wallet. | Yes |
| to_wallet_id | The ID of the destination wallet. | Yes |
| amount | The amount to transfer. | Yes |
| currency | The currency of the transfer. | Yes |

**Responses**

201 Successful Response

Request:

```json
{
    "from_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_wallet_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": "100.00",
    "currency": "USD"
}
```

Response:

```json
{
    "result": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "amount": "100.00",
        "currency": "USD",
        "from_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "to_wallet_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "created_at": "2025-11-10T07:22:23.108Z",
        "updated_at": "2025-11-10T07:22:23.108Z"
    }
}
```

400 Bad Request

```json
{
    "result": "error",
    "reason": "invalid_request",
    "message": "from_wallet_id must be a valid UUID"
}
```

### Get Transfers

This endpoint retrieves all transfers. It uses pagination and returns 25 transfers per page.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/transfers`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| id | None | Filter transfers by ID. |
| currency | None | Filter transfers by currency. |
| from_wallet_id | None | Filter transfers by source wallet ID. |
| to_wallet_id | None | Filter transfers by destination wallet ID. |
| p | None | Page number. |
| size | 25 | Number of results per page. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/transfers`

```json
{
    "result": [
        {
            "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
            "amount": "100.00",
            "currency": "USD",
            "from_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "to_wallet_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "created_at": "2025-11-10T07:22:23.108Z",
            "updated_at": "2025-11-10T07:22:23.108Z"
        },
        {
            "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
            "amount": "50.00",
            "currency": "BTC",
            "from_wallet_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "to_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "created_at": "2025-11-09T12:00:00.000Z",
            "updated_at": "2025-11-09T12:00:00.000Z"
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 2,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/transfers?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

## NeXus

NeXus Transfers allow you to send funds to other clients on the platform. Each transfer is identified by a unique ID and includes the sender and receiver public IDs, wallet references, purpose and notes.

### The NeXus Transfer Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the NeXus transfer. |
| amount - string | The amount transferred. |
| currency - string | The currency of the transfer. |
| from_public_id - string | The public ID of the sending client. |
| to_public_id - string | The public ID of the receiving client. |
| from_wallet_id - string | The ID of the source wallet. Null when you are the receiver of the transfer. |
| to_wallet_id - string | The ID of the destination wallet. Null when you are the sender of the transfer. |
| purpose - string | The purpose of the transfer. Null when you are not the sender. Available values: inter-company-transfer-of-assets, payment-for-receipt-of-goods-or-services, intra-company-transfer-of-assets. |
| notes - string | (Optional) Notes attached to the transfer. |
| created_at - string | The date and time the transfer was created. |

### Create NeXus Transfer

This endpoint creates a NeXus transfer to another client on the platform.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/nexus-transfers`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| from_wallet_id | The ID of the source wallet. | Yes |
| to_public_id | The public ID of the receiving client. | Yes |
| amount | The amount to transfer. | Yes |
| currency | The currency of the transfer. | Yes |
| purpose | The purpose of the transfer. Available values: inter-company-transfer-of-assets, payment-for-receipt-of-goods-or-services, intra-company-transfer-of-assets. | Yes |
| notes | Optional notes on the transfer. | No |

**Responses**

201 Successful Response

Request:

```json
{
    "from_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_public_id": "ACME-001",
    "amount": "250.00",
    "currency": "USD",
    "purpose": "payment-for-receipt-of-goods-or-services",
    "notes": "Payment for invoice #1234"
}
```

Response:

```json
{
    "result": {
        "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
        "amount": "250.00",
        "currency": "USD",
        "from_public_id": "MYCO-001",
        "to_public_id": "ACME-001",
        "from_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "to_wallet_id": null,
        "purpose": "payment-for-receipt-of-goods-or-services",
        "notes": "Payment for invoice #1234",
        "created_at": "2025-11-10T07:22:23.108Z"
    }
}
```

400 Bad Request

```json
{
    "result": "error",
    "reason": "invalid_request",
    "message": "from_wallet_id must be a valid UUID"
}
```

### Get NeXus Transfers

This endpoint retrieves all NeXus transfers. It uses pagination and returns 25 transfers per page.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/nexus-transfers`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| id | None | Filter NeXus transfers by ID. |
| currency | None | Filter NeXus transfers by currency. |
| notes | None | Filter NeXus transfers by notes. |
| from_wallet_id | None | Filter NeXus transfers by source wallet ID. |
| to_public_id | None | Filter NeXus transfers by receiving client public ID. |
| purpose | None | Filter NeXus transfers by purpose. Available values: inter-company-transfer-of-assets, payment-for-receipt-of-goods-or-services, intra-company-transfer-of-assets. |
| p | None | Page number. |
| size | 25 | Number of results per page. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/nexus-transfers`

```json
{
    "result": [
        {
            "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
            "amount": "250.00",
            "currency": "USD",
            "from_public_id": "MYCO-001",
            "to_public_id": "ACME-001",
            "from_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "to_wallet_id": null,
            "purpose": "payment-for-receipt-of-goods-or-services",
            "notes": "Payment for invoice #1234",
            "created_at": "2025-11-10T07:22:23.108Z"
        },
        {
            "id": "f6a7b8c9-d0e1-2345-fabc-678901234568",
            "amount": "500.00",
            "currency": "EUR",
            "from_public_id": "GLOBEX-002",
            "to_public_id": "MYCO-001",
            "from_wallet_id": null,
            "to_wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "purpose": null,
            "notes": null,
            "created_at": "2025-11-09T12:00:00.000Z"
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 2,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/nexus-transfers?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

## Payments

Payments are deposit requests that contain payment details to allow your customer to send cryptocurrency using a supported cryptocurrency and network. Each deposit is tracked by the payment ID associated with the payment address.

See [Payment Lifecycle](#payment-lifecycle) for more details on the payment workflow.

### The Payment Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID associated with the payment |
| wallet_id - string | The ID of the wallet the funds will be sent to. |
| created_at - string | The date and time the payment was created at |
| profile_id - string | The ID of the profile the payment was created against. |
| payment_currency - string | The currency the payer will send to complete the transaction. |
| payment_amount - string | The amount the payer will send in the payment currency to complete the transaction. |
| requested_currency - string | The currency the client will receive once payment is made. It can be the same as the payment currency, or different in which case a conversion will take place. |
| requested_amount - string | The amount requested by the client in the requested currency. |
| address - string | (Deprecated, use the addresses field below) The destination wallet address to which the customer will transfer the payment amount. |
| addresses - string | An object mapping each supported network to its corresponding wallet address. For some payment currencies, multiple networks are supported. |
| status - string | The status of the payment. |
| paid_amount - object | An object containing information about the amounts already paid, where crypto represents the payment currency and fiat represents the requested currency (which could be a crypto currency). |
| conversion_fee - string | Fee charged for the payment. |
| notes - string | (Optional) notes which can be attached to the payment at the time of creation. |
| passthrough - string | (Optional) metadata associated with the payment object. This can be given as either a regular string or JSON string. |
| transactions - object array | A list of blockchain transactions for this payment, including multiple entries when paid in increments. |
| parent_payment_id - string | In the event of account payments, overpay and address reuse scenarios, the ID associated with the original (first) payment. |

### Payment Statuses

| Status | Description |
| --- | --- |
| new | A new payment has been created and a unique address has been generated for the payer to send their crypto to. |
| pending | Blockchain transactions are found and are awaiting confirmation. |
| converting | The crypto amount received is within the accepted threshold and the conversion of the crypto has been initiated. |
| cancelled | The payment has been cancelled. |
| complete | Conversion has finished if applicable and the payment is now complete. |
| incomplete | The payer transferred crypto, but the amount received is below the acceptable threshold for the payment to be complete. |
| overpay | The payer transferred crypto, but the received amount is above the accepted threshold. Excess crypto can be returned, or manually converted. |
| address_reuse | A Crypto deposit has been made to a wallet address that was used on a previously completed payment. It will require manual handling. |
| conversion_failed | Conversion from crypto to fiat has failed and manual intervention is required. |

### Get Payment Quotes

This endpoint returns quotes for a given amount. If no quote is currently available for a given payment currency, "null" will be returned.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/quotes/payments`

**Query Parameters**

| Parameter | Description | Default |
| --- | --- | --- |
| profile_id | Profile ID to use for settings | None |
| requested_currency | Currency for the specified payment amount. | None |
| requested_amount | Quoted decimal payment amount. | None |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/quotes/payments?profile_id=deb23315-1eae-46fe-929f-6f3067292493&requested_currency=USD&requested_amount=500`

```json
{
    "result": [
        {
            "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
            "requested_currency": "USD",
            "requested_amount": "500",
            "payment_currency": "BTC",
            "payment_amount": "0.005432"
        },
        {
            "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
            "requested_currency": "USD",
            "requested_amount": "500",
            "payment_currency": "ETH",
            "payment_amount": null
        },
        {
            "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
            "requested_currency": "USD",
            "requested_amount": "500",
            "payment_currency": "USDT",
            "payment_amount": "505"
        },
        {
            "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
            "requested_currency": "USD",
            "requested_amount": "500",
            "payment_currency": "USDC",
            "payment_amount": "505"
        }
    ]
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/quotes/payments?profile_id=deb23315-1eae-46fe-929f-6f3067292493&requested_currency=&requested_amount=500`

```json
{
    "result": {
        "message": "requested_currency should not be empty",
        "reason": "invalid_request",
        "result": "error"
    }
}
```

### Create Payment

This endpoint creates an payment. Response is identical to [Get Payment](#get-payment) endpoint response.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/payments/`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| wallet_id | The ID of the wallet the funds will be sent to. | Yes |
| profile_uuid | Profile ID to use for settings, webhook and wallet address generation. | Yes |
| requested_currency | The currency the client will receive once payment is made. It can be the same as the payment currency, or different in which case a conversion will take place. | Yes |
| requested_amount | Quoted decimal payment amount for "purchase payments", or NULL for "account payments". | No |
| payment_currency | The currency the payer will send to complete the transaction. | Yes |
| passthrough | String. Meta-data you wish to store with the payment. Will be sent alongside all webhooks associated with the payment. | No |
| notes | Can be product or service name or any other notes. Visible in dashboard and in public payment link. | No |

See [supported currencies](#supported-currencies) for payment and requested currency options.

**Responses**

201 Successful Response

Request:

```json
{
    "requested_currency": "USD",
    "requested_amount": "4500",
    "payment_currency": "USDT",
    "profile_uuid": "<YOUR_PROFILE_UUID>",
    "passthrough": "{\"order_id\":\"123456\"}",
    "notes": "public note",
    "wallet_id": "<YOUR_WALLET_UUID>"
}
```

Response:

```json
{
    "result": {
        "id": "52774b36-34e1-4cee-a959-b5d59ccd09a0",
        "created_at": "2025-11-10T07:22:23.108Z",
        "confirmed_at": null,
        "completed_at": null,
        "paid_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "payment_currency": "USDT",
        "payment_amount": "4504.503784",
        "requested_currency": "USD",
        "requested_amount": "4500",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "status": "new",
        "paid_amount": {
            "crypto": {
                "currency": "USDT",
                "amount": "0"
            },
            "fiat": {
                "currency": "USD",
                "amount": "0"
            }
        },
        "conversion_fee": "45",
        "payment_fee": "45",
        "notes": "public note",
        "passthrough": "hidden {\"order_id\": 12345}",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transactions": []
    }
}
```

400 Bad Request

Request:

```json
{
    "requested_currency": "",
    "requested_amount": "200",
    "payment_currency": "ETH",
    "profile_uuid": "3a73e618-af3c-4928-98e9-0286652d0a34",
    "passthrough": "{\"order_id\":\"test\"]",
    "notes": "this is demo"
}
```

Response:

```json
{
    "result": {
        "message": "requested_currency should not be empty",
        "reason": "invalid_request",
        "result": "error"
    }
}
```

### Get Payments

This endpoint retrieves all payments. Endpoint uses pagination and returns 25 payments per page. Payments are sorted by creation time in descending order.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/payments/`

**Query Parameters**

| Parameter | Description | Default |
| --- | --- | --- |
| p | Page number. | None |
| wallet_id | Filter payments by wallet ID. | None |
| txid | Filter payments by txid | None |
| address | Filter payments by receiving address. | None |
| status | Filter by status. Available values specified in Payment Statuses. | None |
| passthrough | Filter by passthrough. Response includes partial or complete matches. | None |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/payments?p=1`

```json
{
    "result": [
        {
            "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
            "created_at": "2025-11-10T07:22:23.108Z",
            "confirmed_at": "2025-11-10T07:40:06.330Z",
            "completed_at": "2025-11-10T07:40:06.330Z",
            "paid_at": "2025-11-10T07:40:06.330Z",
            "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
            "payment_currency": "USDT",
            "payment_amount": "4504.503784",
            "requested_currency": "USD",
            "requested_amount": "4500",
            "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "addresses": {
                "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
                "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
            },
            "status": "complete",
            "paid_amount": {
                "crypto": {
                    "currency": "USDT",
                    "amount": "4504.503784"
                },
                "fiat": {
                    "currency": "USD",
                    "amount": "4500"
                }
            },
            "conversion_fee": "45",
            "payment_fee": "45",
            "notes": "public note",
            "passthrough": "{\"order_id\":1642457702}",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "transactions": [
                {
                    "id": "2ceeeec5-acbf-4fed-98f3-99c364532322",
                    "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                    "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213",
                    "amount": {
                        "crypto": {
                            "currency": "USDT",
                            "amount": "4504.503784"
                        },
                        "fiat": {
                            "currency": null,
                            "amount": null
                        }
                    },
                    "currency": "USDT",
                    "created_at": "2025-11-10T07:40:05.433Z",
                    "confirmed_at": "2025-11-10T07:40:06.297Z",
                    "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4"
                }
            ]
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 1,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/payments?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

### Get Payment

This endpoint retrieves a specific payment.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/payments/[ID]`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the payment to retrieve. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/payments/0baa1b12-1d05-4ca1-b0fd-4c391e9d3b9f`

```json
{
    "result": {
        "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
        "created_at": "2025-11-10T07:22:23.108Z",
        "confirmed_at": "2025-11-10T07:40:06.330Z",
        "completed_at": "2025-11-10T07:40:06.330Z",
        "paid_at": "2025-11-10T07:40:06.330Z",
        "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
        "payment_currency": "USDT",
        "payment_amount": "4504.503784",
        "requested_currency": "USD",
        "requested_amount": "4500",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "status": "complete",
        "paid_amount": {
            "crypto": {
                "currency": "USDT",
                "amount": "4504.503784"
            },
            "fiat": {
                "currency": "USD",
                "amount": "4500"
            }
        },
        "conversion_fee": "45",
        "payment_fee": "45",
        "notes": "public note",
        "passthrough": "{\"order_id\":1642457702}",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transactions": [
            {
                "id": "2ceeeec5-acbf-4fed-98f3-99c364532322",
                "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213",
                "amount": {
                    "crypto": {
                        "currency": "USDT",
                        "amount": "4504.503784"
                    },
                    "fiat": {
                        "currency": null,
                        "amount": null
                    }
                },
                "currency": "USDT",
                "created_at": "2025-11-10T07:40:05.433Z",
                "confirmed_at": "2025-11-10T07:40:06.297Z",
                "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4"
            }
        ]
    }
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/payments/1234`

```json
{
    "result": {
        "message": "payment with id 1234 not found",
        "reason": "not_found",
        "result": "error"
    }
}
```

### Cancel Payment

This endpoint cancels a payment.

**HTTP Request**

`PUT https://api.deusxpay.com/pay/v1/payments/[ID]`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the payment to retrieve. |

**Responses**

201 Successful Response — Request: `https://api.deusxpay.com/pay/v1/payments/d8d74e70-a31b-453c-b447-3000e6c061e3`

```json
{
    "result": {
        "id": "49b45775-c264-467b-a919-94c569b1ef79",
        "created_at": "2023-10-26T15:30:54.354812+00:00",
        "confirmed_at": null,
        "completed_at": null,
        "profile_id": "3a73e618-af3c-4928-98e9-0286652d0a34",
        "payment_currency": "USDT",
        "payment_amount": "4504.503784",
        "requested_currency": "USD",
        "requested_amount": "4500",
        "address": "0x77135f4A2D6C67294A3a750Fe22Fb3f6831b1EEA",
        "addresses": {
            "BSC": "0x77135f4A2D6C67294A3a750Fe22Fb3f6831b1EEA",
            "ETH": "0x77135f4A2D6C67294A3a750Fe22Fb3f6831b1EEA"
        },
        "status": "cancelled",
        "paid_amount": {
            "crypto": {
                "currency": "USDT",
                "amount": "0"
            },
            "fiat": {
                "currency": "USD",
                "amount": "0"
            }
        },
        "conversion_fee": "45",
        "payment_fee": "45",
        "notes": "public note",
        "passthrough": "{\"order_id\":\"123456\"}",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transactions": []
    }
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/payments/1234`

```json
{
    "result": {
        "message": "payment with id 1234 not found",
        "reason": "not_found",
        "result": "error"
    }
}
```

### Payment Response Examples

#### Payment Complete

```json
{
    "result": {
        "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
        "created_at": "2025-11-10T07:22:23.108Z",
        "confirmed_at": "2025-11-10T07:40:06.330Z",
        "completed_at": "2025-11-10T07:40:06.330Z",
        "paid_at": "2025-11-10T07:40:06.330Z",
        "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
        "payment_currency": "USDT",
        "payment_amount": "4504.503784",
        "requested_currency": "USD",
        "requested_amount": "4500",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "status": "complete",
        "paid_amount": {
            "crypto": {
                "currency": "USDT",
                "amount": "4504.503784"
            },
            "fiat": {
                "currency": "USD",
                "amount": "4500"
            }
        },
        "conversion_fee": "45",
        "payment_fee": "45",
        "notes": "public note",
        "passthrough": "{\"order_id\":1642457702}",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transactions": [
            {
                "id": "2ceeeec5-acbf-4fed-98f3-99c364532322",
                "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213",
                "amount": {
                    "crypto": {
                        "currency": "USDT",
                        "amount": "4504.503784"
                    },
                    "fiat": {
                        "currency": null,
                        "amount": null
                    }
                },
                "currency": "USDT",
                "created_at": "2025-11-10T07:40:05.433Z",
                "confirmed_at": "2025-11-10T07:40:06.297Z",
                "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4"
            }
        ]
    }
}
```

#### Payment Incomplete

```json
{
    "result": {
        "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
        "created_at": "2025-11-10T07:22:23.108Z",
        "confirmed_at": null,
        "completed_at": null,
        "paid_at": null,
        "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
        "payment_currency": "USDT",
        "payment_amount": "4504.503784",
        "requested_currency": "USD",
        "requested_amount": "4500",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "status": "incomplete",
        "paid_amount": {
            "crypto": {
                "currency": "USDT",
                "amount": "2000"
            },
            "fiat": {
                "currency": "USD",
                "amount": "1998.01"
            }
        },
        "conversion_fee": "45",
        "payment_fee": "45",
        "notes": "public note",
        "passthrough": "{\"order_id\":1642457702}",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transactions": [
            {
                "id": "6da35f85-9127-4042-b1a4-f9b4d13d2f4b",
                "txid": "0xb5b4462afcc6ac3e2295bfdd8b050affec356b2e05b55f77d62c78e962cbb265",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213",
                "amount": {
                    "crypto": {
                        "currency": "USDT",
                        "amount": "2000"
                    },
                    "fiat": {
                        "currency": null,
                        "amount": null
                    }
                },
                "currency": "USDT",
                "created_at": "2025-11-10T08:03:15.398Z",
                "confirmed_at": "2025-11-10T08:03:15.710Z",
                "network": "ETH",
                "status": "confirmed",
                "url": "https://sepolia.etherscan.io/tx/0xb5b4462afcc6ac3e2295bfdd8b050affec356b2e05b55f77d62c78e962cbb265"
            }
        ]
    }
}
```

#### Payment Overpaid

```json
{
    "result": {
        "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
        "created_at": "2025-11-10T07:22:23.108Z",
        "confirmed_at": "2025-11-10T07:40:06.330Z",
        "completed_at": "2025-11-10T07:40:06.330Z",
        "paid_at": "2025-11-10T07:40:06.330Z",
        "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
        "payment_currency": "USDT",
        "payment_amount": "4504.503784",
        "requested_currency": "USD",
        "requested_amount": "4500",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "status": "complete",
        "paid_amount": {
            "crypto": {
                "currency": "USDT",
                "amount": "4600"
            },
            "fiat": {
                "currency": "USD",
                "amount": "4500"
            }
        },
        "conversion_fee": "45",
        "payment_fee": "45",
        "notes": "public note",
        "passthrough": "{\"order_id\":1642457702}",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transactions": [
            {
                "id": "6d354bd3-af86-4b50-9725-aad9644c0a3f",
                "txid": "0x2f7e33ab9c5a19818a9c14f1aa6b1f0ddbf26ee3c1e4d7b69946b40abe110bb5",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213",
                "amount": {
                    "crypto": {
                        "currency": "USDT",
                        "amount": "4600"
                    },
                    "fiat": {
                        "currency": null,
                        "amount": null
                    }
                },
                "currency": "USDT",
                "created_at": "2025-11-10T08:08:50.772Z",
                "confirmed_at": "2025-11-10T08:08:51.239Z",
                "network": "ETH",
                "status": "confirmed",
                "url": "https://sepolia.etherscan.io/tx/0x2f7e33ab9c5a19818a9c14f1aa6b1f0ddbf26ee3c1e4d7b69946b40abe110bb5"
            }
        ]
    }
}
```

#### Payment Address Reuse

```json
{
    "result": {
        "id": "e4f78557-7fb4-42da-89b2-6874d235c70d",
        "created_at": "2025-11-10T07:22:23.108Z",
        "confirmed_at": "2025-11-10T07:40:06.330Z",
        "completed_at": "2025-11-10T07:40:06.330Z",
        "paid_at": "2025-11-10T07:40:06.330Z",
        "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
        "payment_currency": "USDT",
        "payment_amount": "4504.503784",
        "requested_currency": "USD",
        "requested_amount": "4500",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "status": "address_reuse",
        "paid_amount": {
            "crypto": {
                "currency": "USDT",
                "amount": "5504.503784"
            },
            "fiat": {
                "currency": "USD",
                "amount": "4500"
            }
        },
        "conversion_fee": "45",
        "payment_fee": "45",
        "notes": "public note",
        "passthrough": "{\"order_id\":1642457702}",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "transactions": [
            {
                "id": "859f2b15-7599-49fc-9faa-977210db1c7e",
                "txid": "0x8e980e9197f8ffa89bef6a7df39c1874bcead2c5bdfefc2281dd38dcb2fe52fb",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213",
                "amount": {
                    "crypto": {
                        "currency": "USDT",
                        "amount": "1000"
                    },
                    "fiat": {
                        "currency": null,
                        "amount": null
                    }
                },
                "currency": "USDT",
                "created_at": "2025-11-10T08:16:30.334Z",
                "confirmed_at": "2025-11-10T08:16:31.537Z",
                "network": "ETH",
                "status": "confirmed",
                "url": "https://sepolia.etherscan.io/tx/0x8e980e9197f8ffa89bef6a7df39c1874bcead2c5bdfefc2281dd38dcb2fe52fb"
            },
            {
                "id": "93322a7f-49b7-475a-b2c1-2d2e0000b7d7",
                "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213",
                "amount": {
                    "crypto": {
                        "currency": "USDT",
                        "amount": "4504.503784"
                    },
                    "fiat": {
                        "currency": null,
                        "amount": null
                    }
                },
                "currency": "USDT",
                "created_at": "2025-11-10T07:40:05.433Z",
                "confirmed_at": "2025-11-10T08:16:31.537Z",
                "network": "ETH",
                "status": "confirmed",
                "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4"
            }
        ]
    }
}
```

### Payment Webhooks

You can view history of webhooks (if any) in Deus X Pay Console's Payment detail view. Webhooks provide the exact same response format as the Get Payment API endpoint including the additional fields specified in the webhooks documentation. Webhook responses are sent using POST method.

**Payment Webhook Statuses**

| Status | Description |
| --- | --- |
| payment_pending | Payment matches requested amount, has zero confirmations on blockchain (BTC only). |
| payment_converting | Payment is received and it matches requested amount, conversion process from crypto into fiat has started. |
| payment_complete | Conversion has finished and payment is now complete. |
| payment_incomplete | Payment amount doesn't match profile "Allowed Difference" range. Requires manual handling. |
| payment_address_reuse | Already previously complete payment address receives a new transaction and "Address Reuse" parameter for related profile is not enabled. Requires manual handling. |
| payment_conversion_failed | Conversion from crypto to fiat has failed. Requires manual handling. |

### Payment Webhook Examples

#### Payment Pending Webhook

```json
{
    "payment": {
        "id": "52774b36-34e1-4cee-a959-b5d59ccd09a0",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "public note",
        "status": "pending",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "paid_at": null,
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "USDT": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "created_at": "2025-11-10T07:22:23.108Z",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "paid_amount": {
            "fiat": {
                "amount": 0,
                "currency": "USD"
            },
            "crypto": {
                "amount": 0,
                "currency": "USDT"
            }
        },
        "passthrough": "hidden {\"order_id\": 12345}",
        "completed_at": "2025-11-10T07:40:05.433Z",
        "confirmed_at": "2025-11-10T07:22:23.108Z",
        "transactions": [
            {
                "id": "93322a7f-49b7-475a-b2c1-2d2e0000b7d7",
                "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "amount": {
                    "fiat": {
                        "amount": null,
                        "currency": null
                    },
                    "crypto": {
                        "amount": 4504.503784,
                        "currency": "USDT"
                    }
                },
                "status": "pending",
                "network": "ETH",
                "currency": "USDT",
                "created_at": "2025-11-10T07:40:05.433Z",
                "confirmed_at": "2025-11-10T07:40:05.433Z",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213"
            }
        ],
        "conversion_fee": 45,
        "payment_amount": 4504.503784,
        "payment_currency": "USDT",
        "requested_amount": 4500,
        "requested_currency": "USD"
    },
    "signature": "d424d5bccde97e9a7a44cc3853f671bb972c2bcdf7807705d93a36112fada920",
    "callback_id": "9d6e4f18-74dc-4211-a6c9-f9bd33fd62e1",
    "callback_status": "payment_pending"
}
```

#### Payment Converting Webhook

```json
{
    "payment": {
        "id": "52774b36-34e1-4cee-a959-b5d59ccd09a0",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "public note",
        "status": "converting",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "paid_at": null,
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "USDT": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "created_at": "2025-11-10T07:22:23.108Z",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "paid_amount": {
            "fiat": {
                "amount": 4500,
                "currency": "USD"
            },
            "crypto": {
                "amount": 4504.503784,
                "currency": "USDT"
            }
        },
        "passthrough": "hidden {\"order_id\": 12345}",
        "completed_at": "2025-11-10T07:40:05.784Z",
        "confirmed_at": "2025-11-10T07:22:23.108Z",
        "transactions": [
            {
                "id": "93322a7f-49b7-475a-b2c1-2d2e0000b7d7",
                "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "amount": {
                    "fiat": {
                        "amount": null,
                        "currency": null
                    },
                    "crypto": {
                        "amount": 4504.503784,
                        "currency": "USDT"
                    }
                },
                "status": "confirmed",
                "network": "ETH",
                "currency": "USDT",
                "created_at": "2025-11-10T07:40:05.433Z",
                "confirmed_at": "2025-11-10T07:40:05.433Z",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213"
            }
        ],
        "conversion_fee": 45,
        "payment_amount": 4504.503784,
        "payment_currency": "USDT",
        "requested_amount": 4500,
        "requested_currency": "USD"
    },
    "signature": "db7ab1892c612c7a94d1a8ce9c7e0301b2ccba65db1df2bb5e913d1db631034a",
    "callback_id": "777f20dc-5185-438a-a2d9-9ca1ce378050",
    "callback_status": "payment_converting"
}
```

#### Payment Complete Webhook

```json
{
    "payment": {
        "id": "52774b36-34e1-4cee-a959-b5d59ccd09a0",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "public note",
        "status": "complete",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "paid_at": "2025-11-10T07:40:06.330Z",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "USDT": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "created_at": "2025-11-10T07:22:23.108Z",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "paid_amount": {
            "fiat": {
                "amount": 4500,
                "currency": "USD"
            },
            "crypto": {
                "amount": 4504.503784,
                "currency": "USDT"
            }
        },
        "passthrough": "hidden {\"order_id\": 12345}",
        "completed_at": "2025-11-10T07:40:06.330Z",
        "confirmed_at": "2025-11-10T07:22:23.108Z",
        "transactions": [
            {
                "id": "93322a7f-49b7-475a-b2c1-2d2e0000b7d7",
                "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "amount": {
                    "fiat": {
                        "amount": null,
                        "currency": null
                    },
                    "crypto": {
                        "amount": 4504.503784,
                        "currency": "USDT"
                    }
                },
                "status": "confirmed",
                "network": "ETH",
                "currency": "USDT",
                "created_at": "2025-11-10T07:40:05.433Z",
                "confirmed_at": "2025-11-10T07:40:05.433Z",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213"
            }
        ],
        "conversion_fee": 45,
        "payment_amount": 4504.503784,
        "payment_currency": "USDT",
        "requested_amount": 4500,
        "requested_currency": "USD"
    },
    "signature": "965f3051d24213d0245ec7bf2383bfe43290848b0ce3e7c2c51e96c09a12681c",
    "callback_id": "6c4bf57a-50f1-49d7-8d46-b425ce0ceb1d",
    "callback_status": "payment_complete"
}
```

#### Payment Incomplete Webhook

```json
{
    "payment": {
        "id": "936e45a7-4cc0-4cbb-b5cd-db5a5d0178c1",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "public note",
        "status": "incomplete",
        "address": "0xF86a8CfA52C661bC6CF05aFe39bCB1647552C9F3",
        "paid_at": null,
        "addresses": {
            "BSC": "0xF86a8CfA52C661bC6CF05aFe39bCB1647552C9F3",
            "ETH": "0xF86a8CfA52C661bC6CF05aFe39bCB1647552C9F3",
            "USDT": "0xF86a8CfA52C661bC6CF05aFe39bCB1647552C9F3"
        },
        "created_at": "2025-11-10T08:02:12.529Z",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "paid_amount": {
            "fiat": {
                "amount": 1998.01,
                "currency": "USD"
            },
            "crypto": {
                "amount": 2000,
                "currency": "USDT"
            }
        },
        "passthrough": "hidden {\"order_id\": 12345}",
        "completed_at": "2025-11-10T08:03:15.710Z",
        "confirmed_at": "2025-11-10T08:02:12.529Z",
        "transactions": [
            {
                "id": "6da35f85-9127-4042-b1a4-f9b4d13d2f4b",
                "url": "https://sepolia.etherscan.io/tx/0xb5b4462afcc6ac3e2295bfdd8b050affec356b2e05b55f77d62c78e962cbb265",
                "txid": "0xb5b4462afcc6ac3e2295bfdd8b050affec356b2e05b55f77d62c78e962cbb265",
                "amount": {
                    "fiat": {
                        "amount": null,
                        "currency": null
                    },
                    "crypto": {
                        "amount": 2000,
                        "currency": "USDT"
                    }
                },
                "status": "confirmed",
                "network": "ETH",
                "currency": "USDT",
                "created_at": "2025-11-10T08:03:15.398Z",
                "confirmed_at": "2025-11-10T08:03:15.398Z",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213"
            }
        ],
        "conversion_fee": 45,
        "payment_amount": 4504.503784,
        "payment_currency": "USDT",
        "requested_amount": 4500,
        "requested_currency": "USD"
    },
    "signature": "d5f7419d1c7adb8e6e79684eb75b58ee0bd8a0ab87756177f2b5c5d76d83c79a",
    "callback_id": "a4af965f-1736-4001-8ea6-15801513c827",
    "callback_status": "payment_incomplete"
}
```

#### Payment Overpaid Webhook

```json
{
    "payment": {
        "id": "824dbc59-552e-42a9-a2bc-3f2001cefe4e",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "public note",
        "status": "overpay",
        "address": "0xaBED02c7a112D7c4384cB34528B41b018e020A7F",
        "paid_at": "2025-11-10T08:08:51.251Z",
        "addresses": {
            "BSC": "0xaBED02c7a112D7c4384cB34528B41b018e020A7F",
            "ETH": "0xaBED02c7a112D7c4384cB34528B41b018e020A7F",
            "USDT": "0xaBED02c7a112D7c4384cB34528B41b018e020A7F"
        },
        "created_at": "2025-11-10T08:07:41.109Z",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "paid_amount": {
            "fiat": {
                "amount": 4500,
                "currency": "USD"
            },
            "crypto": {
                "amount": 4600,
                "currency": "USDT"
            }
        },
        "passthrough": "hidden {\"order_id\": 12345}",
        "completed_at": "2025-11-10T08:08:51.251Z",
        "confirmed_at": "2025-11-10T08:07:41.109Z",
        "transactions": [
            {
                "id": "6d354bd3-af86-4b50-9725-aad9644c0a3f",
                "url": "https://sepolia.etherscan.io/tx/0x2f7e33ab9c5a19818a9c14f1aa6b1f0ddbf26ee3c1e4d7b69946b40abe110bb5",
                "txid": "0x2f7e33ab9c5a19818a9c14f1aa6b1f0ddbf26ee3c1e4d7b69946b40abe110bb5",
                "amount": {
                    "fiat": {
                        "amount": null,
                        "currency": null
                    },
                    "crypto": {
                        "amount": 4600,
                        "currency": "USDT"
                    }
                },
                "status": "confirmed",
                "network": "ETH",
                "currency": "USDT",
                "created_at": "2025-11-10T08:08:50.772Z",
                "confirmed_at": "2025-11-10T08:08:50.772Z",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213"
            }
        ],
        "conversion_fee": 45,
        "payment_amount": 4505.404324,
        "payment_currency": "USDT",
        "requested_amount": 4500,
        "requested_currency": "USD"
    },
    "signature": "aeb070d38cd37d053439fc845a0c7b3757f7f6c0464232896ada9cc30d2bda52",
    "callback_id": "802d697d-e8cf-4ea9-8ac3-77211bef9b40",
    "callback_status": "payment_overpay"
}
```

#### Payment Address Reuse Webhook

```json
{
    "payment": {
        "id": "52774b36-34e1-4cee-a959-b5d59ccd09a0",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "public note",
        "status": "address_reuse",
        "address": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
        "paid_at": "2025-11-10T07:40:06.330Z",
        "addresses": {
            "BSC": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "ETH": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE",
            "USDT": "0x907bbC8AF1A863Ad0A07eC6107eAb34920f2f9cE"
        },
        "created_at": "2025-11-10T07:22:23.108Z",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "paid_amount": {
            "fiat": {
                "amount": 4500,
                "currency": "USD"
            },
            "crypto": {
                "amount": 5504.503784,
                "currency": "USDT"
            }
        },
        "passthrough": "hidden {\"order_id\": 12345}",
        "completed_at": "2025-11-10T08:16:31.537Z",
        "confirmed_at": "2025-11-10T07:22:23.108Z",
        "transactions": [
            {
                "id": "93322a7f-49b7-475a-b2c1-2d2e0000b7d7",
                "url": "https://sepolia.etherscan.io/tx/0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "txid": "0x26ff10f2b3b9b8247179230125f09002d65cfbe277f478e39941f14d3a2f84a4",
                "amount": {
                    "fiat": {
                        "amount": null,
                        "currency": null
                    },
                    "crypto": {
                        "amount": 4504.503784,
                        "currency": "USDT"
                    }
                },
                "status": "confirmed",
                "network": "ETH",
                "currency": "USDT",
                "created_at": "2025-11-10T07:40:05.433Z",
                "confirmed_at": "2025-11-10T07:40:05.433Z",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213"
            },
            {
                "id": "859f2b15-7599-49fc-9faa-977210db1c7e",
                "url": "https://sepolia.etherscan.io/tx/0x8e980e9197f8ffa89bef6a7df39c1874bcead2c5bdfefc2281dd38dcb2fe52fb",
                "txid": "0x8e980e9197f8ffa89bef6a7df39c1874bcead2c5bdfefc2281dd38dcb2fe52fb",
                "amount": {
                    "fiat": {
                        "amount": null,
                        "currency": null
                    },
                    "crypto": {
                        "amount": 1000,
                        "currency": "USDT"
                    }
                },
                "status": "confirmed",
                "network": "ETH",
                "currency": "USDT",
                "created_at": "2025-11-10T08:16:30.334Z",
                "confirmed_at": "2025-11-10T08:16:30.334Z",
                "source_address": "0x607cCAd8e92e79d6FAb91fBA5853bFc4ba43A213"
            }
        ],
        "conversion_fee": 45,
        "payment_amount": 4504.503784,
        "payment_currency": "USDT",
        "requested_amount": 4500,
        "requested_currency": "USD"
    },
    "signature": "90c4ff74a048cde2ef30209edf8ee6fd07feacff45c3e2ee3ea0020e4c112d5b",
    "callback_id": "3bea8fda-8315-493e-9f6a-4a871f2d3188",
    "callback_status": "payment_address_reuse"
}
```

#### Payment Cancelled Webhook

```json
{
    "payment": {
        "id": "d8d74e70-a31b-453c-b447-3000e6c061e3",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "public note",
        "status": "canceled_",
        "address": "0x0a81Bf7f521Bb1506dD795afcFa05825aaA22737",
        "paid_at": null,
        "addresses": {
            "BSC": "0x0a81Bf7f521Bb1506dD795afcFa05825aaA22737",
            "ETH": "0x0a81Bf7f521Bb1506dD795afcFa05825aaA22737",
            "USDT": "0x0a81Bf7f521Bb1506dD795afcFa05825aaA22737"
        },
        "created_at": "2025-11-10T07:53:51.123Z",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "paid_amount": {
            "fiat": {
                "amount": 0,
                "currency": "USD"
            },
            "crypto": {
                "amount": 0,
                "currency": "USDT"
            }
        },
        "passthrough": "hidden {\"order_id\": 12345}",
        "completed_at": "2025-11-10T07:54:31.884Z",
        "confirmed_at": "2025-11-10T07:53:51.123Z",
        "transactions": [],
        "conversion_fee": 45,
        "payment_amount": 4504.503784,
        "payment_currency": "USDT",
        "requested_amount": 4500,
        "requested_currency": "USD"
    },
    "signature": "85a4efe2cb154cfd4ff8973cc15a83d4ff2f00b692e21ac8f45a3860a7cb39b2",
    "callback_id": "2a5a34a5-9619-4376-8479-981c8ce5a322",
    "callback_status": "payment_canceled"
}
```

## Payouts

Payouts are fiat currency withdrawals or settlements to linked external bank accounts.

### The Payout Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the payout |
| wallet_id - string | The ID of the wallet the funds will be sourced from. |
| remote_uuid - string | (Legacy) This will correspond to either the ID of the payout on the legacy Deus X Pay or 'id' listed above. |
| reference - string | Reference value created which is associated with the Payout. |
| created_at - string | The date and time the Payout was created |
| to_wallet_uuid - string | The ID of the bank account where the payout will occur |
| amount - string | The amount to be paid out. |
| currency - string | The currency used for the payout. |
| status - string | The status of the payout. See Payout Statuses for more information. |
| notes - string | (Optional) notes which can be attached to the payout during creation. |

### Payout Statuses

| Status | Description |
| --- | --- |
| pending | A new payout has been created but has not yet been settled. |
| pending-authorisation | Waiting for the payout to be allowed or blocked. |
| complete | The payout has been settled. |
| cancelled | The payout has been cancelled. |
| blocked | The payout has been blocked by a policy rule or user. |

### Create Payout

This endpoint creates a payout. The response is identical to the [Get Payout](#get-payout) endpoint response.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/payouts/`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| wallet_id | The ID of the wallet the funds will be sourced from. | Yes |
| currency | Currency for the specified payout amount. | Yes |
| amount | Quoted decimal payout amount. | Yes |
| external_account_uuid | ID of the account where the payout should be made to. | Yes |
| profile_uuid | Profile ID to use for webhooks. | No |
| notes | Optional notes on Payout | No |

See [supported currencies](#supported-currencies) for currency options. Note that only fiat currencies are applicable for payouts.

**Responses**

201 Successful Response

Request:

```json
{
    "currency": "USD",
    "amount": "500",
    "external_account_uuid": "564e76c0-d0e5-4256-a4ba-d5c7805eb901",
    "notes": "Payout test",
    "wallet_id": "<YOUR_WALLET_UUID>"
}
```

Response:

```json
{
    "result": {
        "id": "b7a72d2e-9f55-4520-9811-761373a4d8e6",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "remote_uuid": "b7a72d2e-9f55-4520-9811-761373a4d8e6",
        "reference": "2IETR06CRR",
        "created_at": "2023-11-13T07:49:28.386Z",
        "to_wallet_uuid": "564e76c0-d0e5-4256-a4ba-d5c7805eb905",
        "amount": "500",
        "currency": "USD",
        "status": "Pending",
        "notes": "Payout test"
    }
}
```

400 Bad Request

Request:

```json
{
    "currency": "USD",
    "amount": "500",
    "notes": "Payout test"
}
```

Response:

```json
{
    "result": "error",
    "reason": "unknown_external_account"
}
```

### Get Payouts

This endpoint retrieves all payouts. Endpoint uses pagination and returns 25 payouts per page. Payouts are sorted by creation time in descending order.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/payouts/`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| p | None | Page number. |
| wallet_id | None | Filter payouts by wallet ID. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/payouts?p=1`

```json
{
    "result": [
        {
            "id": "1f0bb1d6-b2f3-4986-8079-0f8a09dd220a",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "1f0bb1d6-b2f3-4986-8079-0f8a09dd220a",
            "reference": "4N15MI35R8",
            "created_at": "2023-10-23T10:07:31.998Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "460",
            "currency": "USD",
            "status": "Pending",
            "notes": null
        },
        {
            "id": "55dced9b-ba42-4a41-bd13-bfaf8b1d8514",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "55dced9b-ba42-4a41-bd13-bfaf8b1d8514",
            "reference": "681EO31CWR",
            "created_at": "2023-10-23T08:12:04.158Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "850",
            "currency": "GBP",
            "status": "Pending",
            "notes": "GBP Payout"
        },
        {
            "id": "aafa2ad4-fdb7-4a4b-9ab9-77409717ffb9",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "aafa2ad4-fdb7-4a4b-9ab9-77409717ffb9",
            "reference": "3BBD5O4D6G",
            "created_at": "2023-10-20T11:16:25.484Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "1001",
            "currency": "USD",
            "status": "Pending",
            "notes": "USD Payout"
        },
        {
            "id": "d4a0d220-7893-45bd-9843-4849fb06f28c",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "d4a0d220-7893-45bd-9843-4849fb06f28c",
            "reference": "4G89MS1AZI",
            "created_at": "2023-10-20T09:51:51.791Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "1000",
            "currency": "USD",
            "status": "Pending",
            "notes": null
        },
        {
            "id": "d15e976c-c8f8-4cf9-b249-87085cf3cc6f",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "d15e976c-c8f8-4cf9-b249-87085cf3cc6f",
            "reference": "1QF8IHAC7W",
            "created_at": "2023-10-16T13:58:10.249Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "500",
            "currency": "USD",
            "status": "Pending",
            "notes": ""
        },
        {
            "id": "e0433a76-01f6-4fae-8930-8a4dddf8af48",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "e0433a76-01f6-4fae-8930-8a4dddf8af48",
            "reference": "1EEJ2A7TRT",
            "created_at": "2023-09-19T12:27:44.231Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "100",
            "currency": "USD",
            "status": "Pending",
            "notes": null
        },
        {
            "id": "8f321630-ba01-4e3a-becf-730c17298b9d",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "8f321630-ba01-4e3a-becf-730c17298b9d",
            "reference": "H24IZ20AXD",
            "created_at": "2023-09-13T11:37:24.192Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "200",
            "currency": "AUD",
            "status": "Pending",
            "notes": null
        },
        {
            "id": "676514d4-0976-4ab5-9cde-6719c0d2eabf",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "676514d4-0976-4ab5-9cde-6719c0d2eabf",
            "reference": "331WXFIAWU",
            "created_at": "2023-08-15T07:11:45.776Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "150",
            "currency": "EUR",
            "status": "Pending",
            "notes": null
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 8,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/payouts?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

### Get Payout

This endpoint retrieves a specific payout.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/payouts/[ID]`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the payout to retrieve. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/payouts/1f0bb1d6-b2f3-4986-8079-0f8a09dd220a`

```json
{
    "result": [
        {
            "id": "1f0bb1d6-b2f3-4986-8079-0f8a09dd220a",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "remote_uuid": "1f0bb1d6-b2f3-4986-8079-0f8a09dd220a",
            "reference": "4N15MI35R8",
            "created_at": "2023-10-23T10:07:31.998Z",
            "to_wallet_uuid": "a4b131d7-3d05-47a8-8892-25b6793a9876",
            "amount": "460",
            "currency": "USD",
            "status": "Pending",
            "notes": null
        }
    ]
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/payouts/1234`

```json
{
    "result": {
        "message": "payout with id 1234 not found",
        "reason": "not_found",
        "result": "error"
    }
}
```

### Payout Webhooks

Webhooks provide the exact same response format as the Get Payout API endpoint plus extra fields specified in the webhooks documentation.

You can view history of webhooks (if any) in Deus X Pay in the Payout detail view.

**Payout Webhook Statuses**

| Status | Description |
| --- | --- |
| payout_pending | Payout has been created successfully and is pending completion. |
| payout_complete | Payout has been completed. |
| payout_cancelled | Payout has been cancelled |

### Payout Webhook Examples

#### Payout Pending Webhook

```json
{
    "payout": {
        "id": "2fe3ae2d-d4b8-47d2-abf8-f122efd87e29",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "40 GBP Payout notes",
        "amount": 40,
        "status": "Pending",
        "currency": "GBP",
        "reference": "671BH2JJUO",
        "created_at": "2023-11-20T19:05:46.337Z",
        "remote_uuid": "2fe3ae2d-d4b8-47d2-abf8-f122efd87e29",
        "to_wallet_uuid": "118e3bf6-f070-4a24-8505-e551738157ae",
        "from_wallet_uuid": "3140412c-8936-5260-8f14-5f78128a8dce"
    },
    "signature": "bb5f25ed31ff03689e33f94be0d03e0e437a0fdeaf3e947ab8dc5c814330243d",
    "callback_id": "73ca0e25-f2a8-4487-8e28-53ef97e6971b",
    "callback_status": "payout_pending"
}
```

#### Payout Complete Webhook

```json
{
    "payout": {
        "id": "2fe3ae2d-d4b8-47d2-abf8-f122efd87e29",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 35,
        "notes": "40 GBP Payout notes",
        "amount": 40,
        "status": "Complete",
        "currency": "GBP",
        "reference": "671BH2JJUO",
        "created_at": "2023-11-20T19:05:46.337Z",
        "remote_uuid": "2fe3ae2d-d4b8-47d2-abf8-f122efd87e29",
        "to_wallet_uuid": "118e3bf6-f070-4a24-8505-e551738157ae",
        "from_wallet_uuid": "3140412c-8936-5260-8f14-5f78128a8dce"
    },
    "signature": "f91679afc1764a7455875be1b86e704109d6ecb6692a7dec67feed87df2b1ece",
    "callback_id": "5b9a101f-eb76-4fc8-81a1-fb392d8cfa98",
    "callback_status": "payout_complete"
}
```

#### Payment Cancelled Webhook

```json
{
    "payout": {
        "id": "5e154316-8e81-4ffd-8293-5527f980b86a",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "notes": "Cancelled Payout",
        "amount": 15,
        "status": "Cancelled",
        "currency": "AUD",
        "reference": null,
        "created_at": "2023-11-17T10:01:19.118Z",
        "remote_uuid": "5e154316-8e81-4ffd-8293-5527f980b86a",
        "to_wallet_uuid": "1d8e037e-df73-4a14-83f1-92958bb5e96b",
        "from_wallet_uuid": "143f425a-e646-4e0a-a62a-32284ed14160"
    },
    "signature": "b8a0951078beff034cf87930f0f5f1c3e97747b248a404e5837c24db3d3455ae",
    "callback_id": "62f1ccb2-a65f-4ed8-9868-ca0b219164f7",
    "callback_status": "payout_cancelled"
}
```

## Swaps

Swaps are conversions between two currencies.

### The Swap Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the Swap. |
| wallet_id - string | The ID of the wallet the funds will be swapped in. |
| from_currency - string | The currency being converted from. |
| from_amount - string | The amount being converted from. |
| to_currency - string | The currency being converted to. |
| to_amount - string | The gross amount being converted to. |
| fee - string | The fee being charged (always in to_currency). |
| to_amount_net - string | The amount being converted to net the fee. |
| status - string | The status of the swap. |
| notes - string | (Optional) Notes which can be attached to the swap at the time of creation. |
| created_at - string | The date and time the swap was created. |
| updated_at - string | The date and time the swap was updated. |

### Swap Statuses

| Status | Description |
| --- | --- |
| converting | The swap is still in progress. You should continue polling until the status changes to complete, conversion-failed or cancelled. |
| complete | The swap has completed successfully. |
| cancelled | The swap has been cancelled. |
| conversion-failed | The swap has failed. This is a final state and you cannot take any action on this swap. If you still want to proceed, a new swap should be created. |

### Create Swap

This endpoint creates a swap.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/swaps`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| wallet_id | The ID of the wallet the funds will be swapped in. | Yes |
| from_currency | Currency to swap from. | Yes |
| from_amount | Amount to be swapped in from_currency. | No * |
| to_currency | Currency to swap to. | Yes |
| to_amount | Gross amount to receive in the to_currency. | No * |
| to_amount_net | Net amount to receive in the to_currency after fees. | No * |
| notes | Optional notes on the swap. | No |

See [supported currencies](#supported-currencies) for from and to currency options.

**Amount Parameters**

- Only `from_amount` - to swap a fixed amount of the `from_currency`.
- Only `to_amount` - to receive a fixed gross amount of the `to_currency`.
- Only `to_amount_net` - to receive a fixed net amount of the `to_currency` (after fees).
- Both `from_amount` and `to_amount` - to create a limit swap (the swap executes only if the rate meets the specified amounts).

**Responses**

The response will include a `status` field indicating the swap state:

- `complete` - The swap has completed successfully.
- `conversion-failed` - The swap has failed. This is a final state and you cannot take any action on this swap. If you still want to proceed, a new swap should be created.
- `converting` - The swap is still in progress. You should continue polling until the status changes to `complete` or `conversion-failed`.
- `cancelled` - The swap has been cancelled. This is a final state and you cannot take any action on this swap.

201 Successful Response

Request:

```json
{
    "from_currency": "BTC",
    "from_amount": "1",
    "to_currency": "USD",
    "notes": "Sell BTC",
    "wallet_id": "<YOUR_WALLET_UUID>"
}
```

Response:

```json
{
    "result": [
        {
            "id": "91a77052-feb7-4022-a294-fb63c643e96a",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "from_currency": "BTC",
            "from_amount": "1",
            "to_currency": "USD",
            "to_amount": "120000",
            "to_amount_net": "119880",
            "fee": "120",
            "status": "complete",
            "notes": "BTC sale",
            "created_at": "2022-01-07T14:04:44+00:00",
            "updated_at": "2022-01-08T14:04:44+00:00"
        }
    ]
}
```

400 Bad Request

Request:

```json
{
    "from_amount": "1",
    "to_currency": "USD",
    "notes": "Sell BTC"
}
```

Response:

```json
{
    "result": "error",
    "message": "fromCurrency should not be empty, fromCurrency must be a string",
    "reason": "invalid_request"
}
```

### Get Swaps

This endpoint retrieves all swaps. It uses pagination and returns 25 swaps per page. Swaps are sorted by creation time in descending order.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/swaps`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| p | None | Page number. |
| wallet_id | None | Filter swaps by wallet ID. |
| id | None | The ID of the swap. |
| from_currency | None | Currency being swapped from. |
| to_currency | None | Currency being swapped to. |
| status | None | The status of the swap. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/swaps?p=1`

```json
{
    "result": [
        {
            "id": "91a77052-feb7-4022-a294-fb63c643e96a",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "from_currency": "BTC",
            "from_amount": "1",
            "to_currency": "USD",
            "to_amount": "120000",
            "to_amount_net": "119880",
            "fee": "120",
            "status": "complete",
            "notes": "BTC sale",
            "created_at": "2022-01-07T14:04:44+00:00",
            "updated_at": "2022-01-08T14:04:44+00:00"
        },
        {
            "id": "91a77052-feb7-4022-a294-fb63c643e96a",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "from_currency": "USD",
            "from_amount": "4000",
            "to_currency": "ETH",
            "to_amount": "1",
            "to_amount_net": "0.99",
            "fee": "0.01",
            "status": "converting",
            "notes": "Buy ETH",
            "created_at": "2022-01-07T14:04:44+00:00",
            "updated_at": "2022-01-08T14:04:44+00:00"
        },
        {
            "id": "91a77052-feb7-4022-a294-fb63c643e96a",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "from_currency": "AED",
            "from_amount": "367,240",
            "to_currency": "BTC",
            "to_amount": "1",
            "to_amount_net": "0.99",
            "fee": "0.01",
            "status": "conversion-failed",
            "notes": "Buy BTC with AED",
            "created_at": "2022-01-07T14:04:44+00:00",
            "updated_at": "2022-01-08T14:04:44+00:00"
        },
        {
            "id": "91a77052-feb7-4022-a294-fb63c643e96a",
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "from_currency": "USD",
            "from_amount": "22000",
            "to_currency": "SOL",
            "to_amount": "100",
            "to_amount_net": "99",
            "fee": "1",
            "status": "cancelled",
            "notes": "Buy SOL",
            "created_at": "2022-01-07T14:04:44+00:00",
            "updated_at": "2022-01-08T14:04:44+00:00"
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 4,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/swaps?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

### Get Swap Pricing

This endpoint retrieves indicative pricing for a swap before execution. Use this to display expected conversion amounts to users or to validate pricing before creating a swap.

**Note:** Pricing is indicative and may change between the time of quote and swap execution due to market volatility. The actual executed rate will be determined at the time the swap is created.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/swaps/pricing`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| from_currency | None | Currency to swap from. |
| from_amount | None | Amount to be swapped in the from_currency. |
| to_currency | None | Currency to swap to. |
| to_amount | None | Gross amount to receive in the to_currency. |

See [supported currencies](#supported-currencies) for from and to currency options.

**Amount Parameters**

Only specify one of the following in the request:

- `from_amount` - Get pricing based on an amount of the source currency to swap.
- `to_amount` - Get pricing based on a gross amount of the target currency to receive.

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/swaps/pricing?from_currency=BTC&to_currency=USD&from_amount=1`

```json
{
    "result": {
        "from_currency": "BTC",
        "from_amount": "1",
        "to_currency": "USD",
        "to_amount": "120000",
        "to_amount_net": "119880",
        "fee": "120"
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/swaps?to_currency=USD&from_amount=1`

```json
{
    "result": "error",
    "message": "fromCurrency should not be empty, fromCurrency must be a string",
    "reason": "invalid_request"
}
```

## Withdrawals

Withdrawals are **digital currency** payments to **external digital wallets**.

### The Withdrawal Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the Withdrawal. |
| remote_uuid - string | (Legacy) This will correspond to either the ID of the withdrawal on the legacy Deus X Pay or ‘id’ listed above. |
| wallet_id - string | The ID of the wallet the funds will be sourced from. |
| reference - string | Reference value created which is associated with the Withdrawal. |
| created_at - string | The date and time the Withdrawal was created. |
| profile_id - string | The ID of the profile which was used when the withdrawal was created. |
| address - string | The wallet address where the currency withdrawn is sent to. |
| txid - string | The blockchain hash associated with the withdrawal once it has been completed. |
| fiat_amount - string | Quoted decimal withdrawal amount, when the source is fiat. |
| fiat_currency - string | Source currency to be withdrawn from when it is a fiat currency. |
| crypto_amount - string | Quoted decimal withdrawal amount, when the source is crypto. |
| crypto_currency - string | Source currency to be withdrawn from when it is a crypto currency. |
| currency - string | Crypto currency the recipient shall receive. |
| network - string | The network the withdrawal uses. |
| tag - string | (Optional) Destination tag for the withdrawal address. Required by most exchanges to route XRP deposits to the correct account. Omitting this when sending to an exchange may result in lost funds. |
| status - string | The status of the withdrawal. |
| notes - string | (Optional) Notes which can be attached to the Withdrawal at the time of creation. |
| passthrough - string | (Optional) metadata associated with the withdrawal object. This can be given as either a regular string or JSON string. |
| amount - string | The converted amount which is withdrawn. |
| requires_approval - boolean | True if the withdrawal will require an approval before being processed. |

### Withdrawal Statuses

| Status | Description |
| --- | --- |
| pending | Waiting for the withdrawal to be settled. |
| pending-authorisation | Waiting for the withdrawal to be allowed or blocked. |
| complete | The withdrawal has been settled. |
| cancelled | The withdrawal has been cancelled. |
| failed | The processing of the withdrawal failed. |
| blocked | The withdrawal was blocked by a policy rule or user. |

### Create Withdrawal

This endpoint creates a withdrawal. The response is identical to the [Get Withdrawal](#get-withdrawal) endpoint response.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/withdrawals/`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| wallet_id | The ID of the wallet the funds will be sourced from. | Yes |
| fiat_currency | Source currency to be withdrawn from when it is a fiat currency. | No |
| fiat_amount | Quoted decimal withdrawal amount, when the source is fiat. * Required if crypto_amount or crypto_amount_net is not specified. | Yes * |
| crypto_currency | Source currency to be withdrawn from when it is a crypto currency. | No |
| crypto_amount | Quoted decimal withdrawal amount, when the source is crypto. * Required if fiat_amount or crypto_amount_net is not specified. | Yes * |
| crypto_amount_net | Net withdrawal amount to receive in the withdrawal crypto currency after fees. * Required if fiat_amount is not specified. | Yes * |
| profile_id | Profile ID for settings and webhooks. | No |
| address | The wallet address of the recipient. | Yes |
| currency | Crypto currency the recipient shall receive. | Yes |
| network | Recipient address network. | Yes |
| tag | Destination tag for the recipient address. Required by most exchanges to route XRP deposits to the correct account. Omitting this when sending to an exchange may result in lost funds. | No |
| notes | Optional notes on the withdrawal. | No |
| passthrough | Meta-data associated with the withdrawal object. This can be given as either a regular string or JSON string. | No |

See [supported currencies](#supported-currencies) for fiat and crypto currency options.

**Responses**

201 Successful Response

Request:

```json
{
    "profile_id": "<YOUR_PROFILE_UUID>",
    "fiat_currency": "USD",
    "fiat_amount": "10.00",
    "notes": "public notes",
    "passthrough": "{\"order_id\": 123}",
    "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
    "currency": "USDT",
    "network": "ETH",
    "wallet_id": "<YOUR_WALLET_UUID>"
}
```

Response:

```json
{
    "result": {
        "id": "3363aa28-7b38-4dc0-8a84-f5711c948305",
        "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
        "amount": "9.992006",
        "created_at": "2025-11-10T14:44:03.950Z",
        "currency": "USDT",
        "fee": "0.099921",
        "merchant_fee": "0",
        "fee_paid_by": "recipient",
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT",
        "fiat_amount": "10",
        "fiat_currency": "USD",
        "fiat_wallet_uuid": "",
        "from_wallet_uuid": "",
        "txid": null,
        "network": "ETH",
        "tag": null,
        "notes": "public notes",
        "passthrough": "hidden {\"order_id\": 123}",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "reference": "4BDRMOECTI",
        "remote_uuid": "3363aa28-7b38-4dc0-8a84-f5711c948305",
        "status": "pending",
        "requires_approval": false,
        "expires_at": null,
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
}
```

400 Bad Request

Request:

```json
{
    "fiat_currency": "USD",
    "fiat_amount": "150",
    "currency": "ETH",
    "network": "ETH",
    "address": "",
    "profile_id": "deb23315-1eae-46fe-929f-6f3067292493",
    "notes": "Acme Daily Withdrawal"
}
```

Response:

```json
{
    "result": "error",
    "message": "address should not be empty",
    "reason": "invalid_request"
}
```

### Cancel Withdrawal

This endpoint cancels a withdrawal if it has not been processed yet. The response is identical to the [Get Withdrawal](#get-withdrawal) endpoint response.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/withdrawals/[ID]/cancel/`

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/withdrawals/3363aa28-7b38-4dc0-8a84-f5711c948305/cancel`

```json
{
    "result": {
        "id": "3363aa28-7b38-4dc0-8a84-f5711c948305",
        "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
        "amount": "9.992006",
        "created_at": "2025-11-10T14:44:03.950Z",
        "currency": "USDT",
        "fee": "0.099921",
        "merchant_fee": "0",
        "fee_paid_by": "recipient",
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT",
        "fiat_amount": "10",
        "fiat_currency": "USD",
        "fiat_wallet_uuid": "",
        "from_wallet_uuid": "",
        "txid": null,
        "network": "ETH",
        "notes": "public notes",
        "passthrough": "hidden {\"order_id\": 123}",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "reference": "4BDRMOECTI",
        "remote_uuid": "3363aa28-7b38-4dc0-8a84-f5711c948305",
        "status": "cancelled",
        "requires_approval": false,
        "expires_at": null,
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/withdrawals/3363aa28-7b38-4dc0-8a84-f5711c948305/cancel`

```json
{
    "reason": "withdrawal_not_cancellable",
    "result": "error"
}
```

### Get Withdrawals

This endpoint retrieves all withdrawals. It uses pagination and returns 25 payouts per page. Payouts are sorted by creation time in descending order.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/withdrawals/`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| p | None | Page number. |
| wallet_id | None | Filter payouts by wallet ID. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/withdrawals?p=1`

```json
{
    "result": [
        {
            "id": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
            "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
            "amount": "9.992006",
            "created_at": "2025-11-10T14:52:05.778Z",
            "currency": "USDT",
            "fee": "0.099921",
            "merchant_fee": "0",
            "fee_paid_by": "recipient",
            "merchant_fee_currency": null,
            "recipient_fee_currency": "USDT",
            "fiat_amount": "10",
            "fiat_currency": "USD",
            "fiat_wallet_uuid": "",
            "from_wallet_uuid": "",
            "txid": "0xf9b0dce259c10e9f76e0886e2259b52b4b067f3b12a32e021ff6020c3f204e9a",
            "network": "ETH",
            "notes": "Withdrawal #84719",
            "passthrough": "84719",
            "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
            "reference": "438G8OINCC",
            "remote_uuid": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
            "status": "complete",
            "requires_approval": false,
            "expires_at": null,
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        {
            "id": "3363aa28-7b38-4dc0-8a84-f5711c948305",
            "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
            "amount": "9.992006",
            "created_at": "2025-11-10T14:44:03.950Z",
            "currency": "USDT",
            "fee": "0.099921",
            "merchant_fee": "0",
            "fee_paid_by": "recipient",
            "merchant_fee_currency": null,
            "recipient_fee_currency": "USDT",
            "fiat_amount": "10",
            "fiat_currency": "USD",
            "fiat_wallet_uuid": "",
            "from_wallet_uuid": "",
            "txid": null,
            "network": "ETH",
            "notes": "public notes",
            "passthrough": "hidden {\"order_id\": 123}",
            "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
            "reference": "4BDRMOECTI",
            "remote_uuid": "3363aa28-7b38-4dc0-8a84-f5711c948305",
            "status": "cancelled",
            "requires_approval": false,
            "expires_at": null,
            "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
    ],
    "pagination": {
        "num_pages": 4,
        "count": 42,
        "page": 1,
        "next_page": 2,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/withdrawals?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

### Get Withdrawal

This endpoint retrieves a specific withdrawal.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/withdrawals/[ID]`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the withdrawal to retrieve. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/withdrawals/3363aa28-7b38-4dc0-8a84-f5711c948305`

```json
{
    "result": {
        "id": "3363aa28-7b38-4dc0-8a84-f5711c948305",
        "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
        "amount": "9.992006",
        "created_at": "2025-11-10T14:44:03.950Z",
        "currency": "USDT",
        "fee": "0.099921",
        "merchant_fee": "0",
        "fee_paid_by": "recipient",
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT",
        "fiat_amount": "10",
        "fiat_currency": "USD",
        "fiat_wallet_uuid": "",
        "from_wallet_uuid": "",
        "to_wallet_uuid": "7e8b2e6a-9d8e-4e8a-9c1f-47d6ba0a546a",
        "txid": null,
        "network": "ETH",
        "notes": "public notes",
        "passthrough": "hidden {\"order_id\": 123}",
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "reference": "4BDRMOECTI",
        "remote_uuid": "3363aa28-7b38-4dc0-8a84-f5711c948305",
        "status": "cancelled",
        "requires_approval": false,
        "expires_at": null,
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/withdrawals/815bcee8-e4e9-4395-b8ea-6b9e5fd78f5f`

```json
{
    "result": {
        "message": "withdrawal with id 815bcee8-e4e9-4395-b8ea-6b9e5fd78f5f not found",
        "reason": "not_found",
        "result": "error"
    }
}
```

### Withdrawal Fee Settings

These settings allow merchants to specify how withdrawal fees will be deducted.

The fee settings can be changed in the Profiles section of the Deus X Pay console.

The following options are available:

#### Fee Paid By:

- Recipient: The withdrawal fee is deducted from the gross amount, resulting in a net withdrawal amount of `grossAmount - withdrawalFeeAmount`. This is the default setting.
- Merchant: The withdrawal fee is deducted separately from the merchant's respective wallet for the withdrawal currency.

#### Withdrawal Fee Currency:

The currency in which the withdrawal fee will be charged. Available when the "Fee Paid By" setting is "Merchant"

- Destination: Withdrawal fees are deducted in the destination withdrawal currency (default)
- Source: Withdrawal fees will be deducted in the source withdrawal currency

When creating a withdrawal, specifying the profile configured with the desired fee setting will apply it to the withdrawal.

### Withdrawal Webhooks

Webhooks provide the exact same response format as the Get Withdrawal API endpoint plus three the extra fields specified in the webhooks documentation.

| Status | Description |
| --- | --- |
| withdrawal_pending_approval | Waiting for the withdrawal to be approved. |
| withdrawal_pending_authorisation | Waiting for the withdrawal to be allowed or blocked. |
| withdrawal_pending | Waiting for the withdrawal to be settled. |
| withdrawal_converting | The withdrawal is undergoing conversion. |
| withdrawal_complete | The withdrawal has been settled |
| withdrawal_failed | The withdrawal process failed. |
| withdrawal_cancelled | The withdrawal has been cancelled. |
| withdrawal_rejected | The withdrawal has been rejected. |

### Withdrawal Webhook Examples

#### Withdrawal Pending Approval Webhook

```json
{
    "signature": "d1a3b9e13b0b8f291143597c2afd98e15e249a83ef33f1c81f4eb240618102e4",
    "withdrawal": {
        "id": "e9d2f822-9a12-4b17-9cc0-a838f5c3e2c0",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 0.099921,
        "txid": null,
        "notes": "withdrawal for order #123",
        "amount": 9.992006,
        "status": "Pending-Approval",
        "address": "0x607ccad8e92e79d6fab91fba5853bfc4ba43a213",
        "network": "ETH",
        "currency": "USDT",
        "reference": "5NM6XJ2PKU",
        "created_at": "2025-11-11T07:23:12.414Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 10,
        "passthrough": "{\"order_id\": 123}",
        "remote_uuid": "e9d2f822-9a12-4b17-9cc0-a838f5c3e2c0",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": "555bbad8-47bb-4a98-85b3-c1bcdda9e842",
        "requires_approval": true,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT"
    },
    "callback_id": "6db26d23-44a1-4aed-8010-3e19974e0241",
    "callback_status": "withdrawal_pending_approval"
}
```

#### Withdrawal Pending Authorisation Webhook

```json
{
    "signature": "d6ea12c74268b0a03e8d33757b8bd625fc7ae4699593b3f8383f8a270e311f2a",
    "withdrawal": {
        "id": "584e48e0-d11c-489b-8b91-8f9b016fb683",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 11.990408,
        "txid": null,
        "notes": "public notes",
        "amount": 1199.040767,
        "status": "Pending-Authorisation",
        "address": "0x607ccad8e92e79d6fab91fba5853bfc4ba43a213",
        "network": "ETH",
        "currency": "USDT",
        "reference": "3T1EFRH0UE",
        "created_at": "2025-11-11T07:17:36.109Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 1200,
        "passthrough": null,
        "remote_uuid": "584e48e0-d11c-489b-8b91-8f9b016fb683",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": "555bbad8-47bb-4a98-85b3-c1bcdda9e842",
        "requires_approval": false,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT"
    },
    "callback_id": "c233864a-b22f-41bc-9f40-20a5ca31c1d1",
    "callback_status": "withdrawal_pending_authorisation"
}
```

#### Withdrawal Pending Webhook

```json
{
    "signature": "6f118038c240a65952bcef944d11703d95f816b476596e378202535ef8c3c17c",
    "withdrawal": {
        "id": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 0.099921,
        "txid": null,
        "notes": "Withdrawal #84719",
        "amount": 9.992006,
        "status": "Pending",
        "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
        "network": "ETH",
        "currency": "USDT",
        "reference": "438G8OINCC",
        "created_at": "2025-11-10T14:52:05.778Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 10,
        "passthrough": "84719",
        "remote_uuid": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": "555bbad8-47bb-4a98-85b3-c1bcdda9e842",
        "requires_approval": false,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT"
    },
    "callback_id": "d7ee6f30-44bc-4eef-a7c2-feb4a6ab7ea1",
    "callback_status": "withdrawal_pending"
}
```

#### Withdrawal Converting Webhook

```json
{
    "signature": "860da4f0736ad3e4f522f68506a3bede8f99f2310688a700f133a255efadc053",
    "withdrawal": {
        "id": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 0.099921,
        "txid": null,
        "notes": "Withdrawal #84719",
        "amount": 9.992006,
        "status": "Converting",
        "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
        "network": "ETH",
        "currency": "USDT",
        "reference": "438G8OINCC",
        "created_at": "2025-11-10T14:52:05.778Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 10,
        "passthrough": "84719",
        "remote_uuid": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": "555bbad8-47bb-4a98-85b3-c1bcdda9e842",
        "requires_approval": false,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT"
    },
    "callback_id": "adaf18c3-4a84-4bc8-866c-d7a8aff338e7",
    "callback_status": "withdrawal_converting"
}
```

#### Withdrawal Complete Webhook

```json
{
    "signature": "3c1288ac46494dc8115f6581e49739053c179cea56ee3cdce0520c991976cc7a",
    "withdrawal": {
        "id": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 0.099921,
        "txid": "0xf9b0dce259c10e9f76e0886e2259b52b4b067f3b12a32e021ff6020c3f204e9a",
        "notes": "Withdrawal #84719",
        "amount": 9.992006,
        "status": "Complete",
        "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
        "network": "ETH",
        "currency": "USDT",
        "reference": "438G8OINCC",
        "created_at": "2025-11-10T14:52:05.778Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 10,
        "passthrough": "84719",
        "remote_uuid": "627db90d-6fa6-477b-9f2e-3d9ddde264a3",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": "555bbad8-47bb-4a98-85b3-c1bcdda9e842",
        "requires_approval": false,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT"
    },
    "callback_id": "21f605e5-9ce3-418b-963f-4c0750e64b95",
    "callback_status": "withdrawal_complete"
}
```

#### Withdrawal Failed Webhook

```json
{
    "signature": "f0aed219b7bcdcc61986f05e25a627a1750999717ca77894e5c27e0611ed6b08",
    "withdrawal": {
        "id": "ad71215e-4628-4044-b245-1e5bbc395d38",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 0.999201,
        "txid": null,
        "notes": "public notes",
        "amount": 99.920063,
        "status": "Failed",
        "address": "0x882E747C5C2E0366d4Fd6F9F95780467C6549732",
        "network": "ETH",
        "currency": "USDT",
        "reference": "2NDD9PCGJA",
        "created_at": "2025-11-10T14:29:28.937Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 100,
        "passthrough": "hidden {\"order_id\": 123}",
        "remote_uuid": "ad71215e-4628-4044-b245-1e5bbc395d38",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": "555bbad8-47bb-4a98-85b3-c1bcdda9e842",
        "requires_approval": false,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT"
    },
    "callback_id": "5096430e-9b58-45fb-89c3-33be777d22e3",
    "callback_status": "withdrawal_failed"
}
```

#### Withdrawal Cancelled Webhook

```json
{
    "signature": "9bffa390877d656f8682632b223cd4888f64062571df6a1af25c6a5f431b7753",
    "withdrawal": {
        "id": "b29ed1e1-4819-4fbc-8e8a-6d6c7fb85acd",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 0,
        "txid": null,
        "notes": "withdrawal for order #123",
        "amount": 0,
        "status": "Cancelled",
        "address": null,
        "network": null,
        "currency": null,
        "reference": "6UL8YCDHNB",
        "created_at": "2025-11-10T13:45:28.421Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 10,
        "passthrough": "{\"order_id\": 123}",
        "remote_uuid": "b29ed1e1-4819-4fbc-8e8a-6d6c7fb85acd",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": null,
        "requires_approval": true,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": null
    },
    "callback_id": "aaf11791-555a-4960-8673-63be1c63166c",
    "callback_status": "withdrawal_cancelled"
}
```

#### Withdrawal Rejected Webhook

```json
{
    "signature": "c6819837a3ff1f8f5ede46caf2cd8025fc38dacb4459809ce64c191992d71c53",
    "withdrawal": {
        "id": "e9d2f822-9a12-4b17-9cc0-a838f5c3e2c0",
        "wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "fee": 0.099921,
        "txid": null,
        "notes": "withdrawal for order #123",
        "amount": 9.992006,
        "status": "Rejected",
        "address": "0x607ccad8e92e79d6fab91fba5853bfc4ba43a213",
        "network": "ETH",
        "currency": "USDT",
        "reference": "5NM6XJ2PKU",
        "created_at": "2025-11-11T07:23:12.414Z",
        "expires_at": null,
        "profile_id": "3398834d-e27c-4d12-a0e9-5a80cd958dfc",
        "fee_paid_by": "recipient",
        "fiat_amount": 10,
        "passthrough": "{\"order_id\": 123}",
        "remote_uuid": "e9d2f822-9a12-4b17-9cc0-a838f5c3e2c0",
        "merchant_fee": 0,
        "fiat_currency": "USD",
        "to_wallet_uuid": null,
        "fiat_wallet_uuid": "7e8b4323-342c-4cde-ab92-ecd794794095",
        "from_wallet_uuid": "555bbad8-47bb-4a98-85b3-c1bcdda9e842",
        "requires_approval": true,
        "crypto_wallet_uuid": null,
        "merchant_fee_currency": null,
        "recipient_fee_currency": "USDT"
    },
    "callback_id": "4f50d65b-19ad-4370-87c5-26b0550c4c91",
    "callback_status": "withdrawal_rejected"
}
```

## Linked Wallets

A linked wallet is a secure digital wallet that you connect to your account, enabling safe and efficient withdrawals of your digital assets. By linking your wallet, you ensure that you are maintaining a high level of security for your **digital currency withdrawals**.

### The Linked Wallet Model

| Attribute | Definition |
| --- | --- |
| id - string | The unique ID of the linked wallet. |
| alias - string | The alias of the linked wallet. |
| inactive - boolean | Whether the linked wallet is inactive. |
| network - string | The network of the linked wallet. |
| currency - string | The currency of the linked wallet. |
| address - string | The wallet address of the linked wallet. |
| tag - string | (Optional) Destination tag for the linked wallet address. Required by most exchanges to route XRP deposits to the correct account. Omitting this when sending to an exchange may result in lost funds. |
| created_at - string | The date and time the linked wallet was created. |
| created_by - string | The user who created the linked wallet. |
| updated_at - string | The date and time the linked wallet was last updated. |
| updated_by - string | The user who last updated the linked wallet. |

### Create Linked Wallet

This endpoint creates a linked wallet.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/linked-wallets/`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| alias | An alias for your linked wallet. | No |
| address | The address of the wallet to link. | Yes |
| currency | Linked wallet address currency. | Yes |
| network | Linked wallet address network. | Yes |
| tag | Destination tag for the linked wallet address. Required by most exchanges to route XRP deposits to the correct account. Omitting this when sending to an exchange may result in lost funds. | No |

See [supported currencies](#supported-currencies) for currency options.

**Responses**

201 Successful Response

Request:

```json
{
    "alias": "ETH Secure Wallet",
    "address": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
    "network": "ETH",
    "currency": "ETH"
}
```

Response:

```json
{
    "id": "157580c0-2a23-49c0-86d4-4b8921576aaa",
    "alias": "ETH Secure Wallet",
    "inactive": false,
    "network": "ETH",
    "currency": "ETH",
    "address": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
    "tag": null,
    "created_at": "2024-03-12T08:52:16.766Z",
    "updated_at": "2024-03-12T08:52:16.766Z",
    "created_by": "Test User",
    "updated_by": null
}
```

400 Bad Request

Request:

```json
{
    "alias": "ETH Secure Wallet",
    "address": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
    "network": "ETH",
    "currency": "ETH"
}
```

Response:

```json
{
    "result": "error",
    "reason": "duplicate_wallet"
}
```

### Get Linked Wallets

This endpoint retrieves all linked wallets. It uses pagination and returns 25 payouts per page. Payouts are sorted by creation time in descending order.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/linked-wallets/`

**URL Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| p | Page number. | No |
| address | Filter linked wallets by address. | No |
| inactive | Filter by active/inactive linked wallets. | No |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/linked-wallets/`

```json
{
    "result": [
        {
            "id": "6cd3f915-892d-4d7d-8660-5e4e5050565f",
            "alias": "Test Wallet Linked",
            "inactive": false,
            "network": "ETH",
            "currency": "ETH",
            "address": "0x4675C7e5BaAFBFFbca748158bEcBA61ef3b0a263",
            "tag": null,
            "created_at": "2024-03-12T08:51:26.088Z",
            "updated_at": "2024-03-12T08:51:26.088Z",
            "created_by": "Test User",
            "updated_by": "Test User"
        },
        {
            "id": "157580c0-2a23-49c0-86d4-4b8921576aaa",
            "alias": "ETH Secure Wallet",
            "inactive": false,
            "network": "ETH",
            "currency": "ETH",
            "address": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
            "tag": null,
            "created_at": "2024-03-12T08:52:16.766Z",
            "updated_at": "2024-03-12T08:52:16.766Z",
            "created_by": "Test User",
            "updated_by": "Test User"
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 2,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/linked-wallets?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

### Get Linked Wallet

This endpoint retrieves a specific linked wallet by ID.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/linked-wallets/[ID]`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the linked wallet. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/linked-wallets/157580c0-2a23-49c0-86d4-4b8921576aaa`

```json
{
    "id": "157580c0-2a23-49c0-86d4-4b8921576aaa",
    "alias": "ETH Secure Wallet",
    "inactive": false,
    "network": "ETH",
    "currency": "ETH",
    "address": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
    "tag": null,
    "created_at": "2024-03-14T08:52:16.766Z",
    "updated_at": "2024-03-14T08:52:16.766Z",
    "created_by": "Test User",
    "updated_by": "Test User"
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/linked-wallets/117580c0-2a23-49c0-86d4-4b8921576aaa`

```json
{
    "result": "error",
    "message": "Linked Wallet 117580c0-2a23-49c0-86d4-4b8921576aaa not found",
    "reason": "wallet_not_found"
}
```

### Update Linked Wallet

This endpoint updates a specific linked wallet.

**HTTP Request**

`PATCH https://api.deusxpay.com/pay/v1/linked-wallets/[ID]`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the linked wallet. |

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| alias | The alias of the linked wallet. | No |
| inactive | Set the linked wallet to be active/inactive. | No |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/linked-wallets/157580c0-2a23-49c0-86d4-4b8921576aaa`

Request:

```json
{
    "alias": "New ETH Alias",
    "inactive": true
}
```

Response:

```json
{
    "id": "157580c0-2a23-49c0-86d4-4b8921576aaa",
    "alias": "New ETH Alias",
    "inactive": true,
    "network": "ETH",
    "currency": "ETH",
    "address": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
    "tag": null,
    "created_at": "2024-03-14T08:52:16.766Z",
    "updated_at": "2024-03-14T09:31:38.778Z",
    "created_by": "Test User",
    "updated_by": "Test User"
}
```

404 Not Found — Request: `https://api.deusxpay.com/pay/v1/linked-wallets/117580c0-2a23-49c0-86d4-4b8921576aaa`

Request:

```json
{
    "alias": "New ETH Alias",
    "inactive": true
}
```

Response:

```json
{
    "result": "error",
    "message": "Linked Wallet 117580c0-2a23-49c0-86d4-4b8921576aaa not found",
    "reason": "wallet_not_found"
}
```

## Bank Accounts

Bank accounts store the fiat destinations used for payouts. Each bank account is identified by a unique ID and includes the format, bank details, account holder name and approval status.

### The Bank Account Model

| Attribute | Definition |
| --- | --- |
| id - string | The ID of the bank account. |
| alias - string | A human-readable alias for the bank account. |
| format - string | The bank account format. Available values: swift, ach, sepa, bsb, payid. |
| bank_name - string | The name of the bank. |
| bank_address - string | The address of the bank. |
| bank_code - string | SWIFT/BIC, ABA routing number, or BSB number. |
| bank_account_number - string | Account number, IBAN, or PayID value. |
| bank_account_holder_name - string | The name of the bank account holder. |
| approval_status - string | The approval status of the bank account. |
| created_at - string | The date and time the bank account was created. |
| updated_at - string | The date and time the bank account was last updated. |

### Create Bank Account

This endpoint creates a bank account.

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/bank-accounts`

**Payload Parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| alias | A human-readable alias for the bank account. | Yes |
| format | The bank account format. Available values: swift, ach, sepa, bsb, payid. | Yes |
| bank_name | The name of the bank. | Yes |
| bank_address | The address of the bank. | Yes |
| bank_code | SWIFT/BIC, ABA routing number, or BSB number. | Yes |
| bank_account_number | Account number, IBAN, or PayID value. | Yes |
| bank_account_holder_name | The name of the bank account holder. | Yes |

**Responses**

201 SWIFT

Request:

```json
{
    "alias": "Primary USD Account",
    "format": "swift",
    "bank_name": "Example Bank",
    "bank_address": "123 Finance Street, New York, NY 10001",
    "bank_code": "EXBKUS33",
    "bank_account_number": "1234567890",
    "bank_account_holder_name": "John Citizen"
}
```

Response:

```json
{
    "result": {
        "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
        "alias": "Primary USD Account",
        "format": "swift",
        "bank_name": "Example Bank",
        "bank_address": "123 Finance Street, New York, NY 10001",
        "bank_code": "EXBKUS33",
        "bank_account_number": "1234567890",
        "bank_account_holder_name": "John Citizen",
        "approval_status": "pending",
        "created_at": "2026-04-16T09:00:00.000Z",
        "updated_at": "2026-04-16T09:00:00.000Z"
    }
}
```

201 ACH

Request:

```json
{
    "alias": "US Domestic Account",
    "format": "ach",
    "bank_name": "First National Bank",
    "bank_address": "456 Main Street, Chicago, IL 60601",
    "bank_code": "021000021",
    "bank_account_number": "9876543210",
    "bank_account_holder_name": "John Citizen"
}
```

Response:

```json
{
    "result": {
        "id": "c2b3d4e5-f6a7-8901-bcde-f23456789012",
        "alias": "US Domestic Account",
        "format": "ach",
        "bank_name": "First National Bank",
        "bank_address": "456 Main Street, Chicago, IL 60601",
        "bank_code": "021000021",
        "bank_account_number": "9876543210",
        "bank_account_holder_name": "John Citizen",
        "approval_status": "pending",
        "created_at": "2026-04-16T09:00:00.000Z",
        "updated_at": "2026-04-16T09:00:00.000Z"
    }
}
```

201 SEPA

Request:

```json
{
    "alias": "EUR SEPA Account",
    "format": "sepa",
    "bank_account_number": "FR7630006000011234567890189",
    "bank_account_holder_name": "John Citizen"
}
```

Response:

```json
{
    "result": {
        "id": "d3c4e5f6-a7b8-9012-cdef-345678901234",
        "alias": "EUR SEPA Account",
        "format": "sepa",
        "bank_account_number": "FR7630006000011234567890189",
        "bank_account_holder_name": "John Citizen",
        "approval_status": "pending",
        "created_at": "2026-04-16T09:00:00.000Z",
        "updated_at": "2026-04-16T09:00:00.000Z"
    }
}
```

201 BSB

Request:

```json
{
    "alias": "AUD BSB Account",
    "format": "bsb",
    "bank_code": "062-000",
    "bank_account_number": "12345678",
    "bank_account_holder_name": "John Citizen"
}
```

Response:

```json
{
    "result": {
        "id": "e4d5f6a7-b8c9-0123-defa-456789012345",
        "alias": "AUD BSB Account",
        "format": "bsb",
        "bank_code": "062-000",
        "bank_account_number": "12345678",
        "bank_account_holder_name": "John Citizen",
        "approval_status": "pending",
        "created_at": "2026-04-16T09:00:00.000Z",
        "updated_at": "2026-04-16T09:00:00.000Z"
    }
}
```

201 PayID

Request:

```json
{
    "alias": "PayID Account",
    "format": "payid",
    "bank_name": "Westpac",
    "bank_address": "275 Kent Street, Sydney NSW 2000, Australia",
    "bank_code": "",
    "bank_account_number": "john.citizen@email.com",
    "bank_account_holder_name": "John Citizen"
}
```

Response:

```json
{
    "result": {
        "id": "f5e6a7b8-c9d0-1234-efab-567890123456",
        "alias": "PayID Account",
        "format": "payid",
        "bank_name": "Westpac",
        "bank_address": "275 Kent Street, Sydney NSW 2000, Australia",
        "bank_code": "",
        "bank_account_number": "john.citizen@email.com",
        "bank_account_holder_name": "John Citizen",
        "approval_status": "pending",
        "created_at": "2026-04-16T09:00:00.000Z",
        "updated_at": "2026-04-16T09:00:00.000Z"
    }
}
```

400 Bad Request

Request:

```json
{
    "alias": "Primary USD Account",
    "format": "invalid_format",
    "bank_name": "Example Bank",
    "bank_address": "123 Finance Street, New York, NY 10001",
    "bank_code": "EXBKUS33",
    "bank_account_number": "1234567890",
    "bank_account_holder_name": "John Citizen"
}
```

Response:

```json
{
    "result": "error",
    "reason": "invalid_request",
    "message": "format must be one of the following values: swift, ach, sepa, bsb, payid"
}
```

### Get Bank Accounts

This endpoint retrieves all bank accounts. It uses pagination and returns 25 bank accounts per page.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/bank-accounts`

**Query Parameters**

| Parameter | Default | Description |
| --- | --- | --- |
| alias | None | Filter bank accounts by alias. |
| p | None | Page number. |
| size | 25 | Number of results per page. |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/bank-accounts`

```json
{
    "result": [
        {
            "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
            "alias": "Primary USD Account",
            "format": "swift",
            "bank_name": "Example Bank",
            "bank_address": "123 Finance Street, New York, NY 10001",
            "bank_code": "EXBKUS33",
            "bank_account_number": "1234567890",
            "bank_account_holder_name": "John Citizen",
            "approval_status": "approved",
            "created_at": "2026-04-16T09:00:00.000Z",
            "updated_at": "2026-04-16T09:00:00.000Z"
        },
        {
            "id": "c2b3d4e5-f6a7-8901-bcde-f23456789012",
            "alias": "EUR SEPA Account",
            "format": "sepa",
            "bank_name": "Euro Bank",
            "bank_address": "45 Rue de la Finance, 75001 Paris, France",
            "bank_code": "EUROFRPP",
            "bank_account_number": "FR7630006000011234567890189",
            "bank_account_holder_name": "John Citizen",
            "approval_status": "approved",
            "created_at": "2026-04-10T12:00:00.000Z",
            "updated_at": "2026-04-10T12:00:00.000Z"
        }
    ],
    "pagination": {
        "num_pages": 1,
        "count": 2,
        "page": 1,
        "next_page": null,
        "previous_page": null,
        "per_page": 25
    }
}
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/bank-accounts?p=one`

```json
{
    "result": {
        "message": "parameter p should be of type integer",
        "reason": "invalid page number: one",
        "result": "error"
    }
}
```

## Reports

Merchants currently download various CSV reports via the Deus X Pay UI, including Payments, Transactions, Withdrawals, Swaps and Payouts report. This endpoint gives access to that data via a REST API.

### Get a report

Reports are returned in text/csv format and contain a comma-separated list of records for the requested report.

**HTTP Request**

`GET https://api.deusxpay.com/pay/v1/reports/[report_name]`

**URL Parameters**

| Parameter | Description | Default | Required |
| --- | --- | --- | --- |
| report_name | The name of the report. Available values: payments, withdrawals, transactions, payouts, wallet, swaps. | None | Yes |
| date_from | The start date of the report. | None | Yes |
| date_to | The end date of the report. | None | Yes |
| wallet_id | The ID of the wallet to filter the report by. The wallet_id must be supplied if report_name is 'wallet'. | None | No |
| currency | The currency associated with the report. Maps to payment_currency for payments, and to_currency for swaps. The currency must be supplied if report_name is 'wallet'. | None | No |
| limit | The maximum number of records to return. | 100000 for wallet reports otherwise 1000000000 | No |
| order | The date ordering of the result. For 'wallet' reports the value cannot be desc. Available values: asc, desc. | asc | No |

**Responses**

200 Successful Response — Request: `https://api.deusxpay.com/pay/v1/reports/payments?date_from=2021-05-22T04:24:49.486Z&date_to=2024-07-22T04:24:49.486Z`

```
"Created At","Updated At","Payment ID","Parent Payment ID","Payment Addresses","Requested Currency","Requested Amount","Markup Amount","Gross Requested Amount","Payment Fee Amount","Net Requested Amount","Net Amount Credited","Payment Currency","Payment Amount","Payment Amount Received","Unprocessed Crypto Amount","Paid Status","Paid At","Status","Profile","Notes","Passthrough","User"
"2024-05-22T04:24:49.486Z","2024-05-22T04:24:49.486Z","55321c97-33a4-4fab-b606-055e3afca642",,"0x8afF237cA2dD22E19f6029d922F9502cfA281414","USD","100.00","1.00","101.00","0.01","100.99","0","ETH","0.028985","0.000000","0.000000","Unpaid","","New","Main profile",,,"john.citizen"
```

400 Bad Request — Request: `https://api.deusxpay.com/pay/v1/reports/withdrawals?date_from=2021-05-22T04:24:49.486Z`

```json
{
    "result": {
        "message": "date_to must be a valid ISO 8601 date string",
        "reason": "invalid_request",
        "result": "error"
    }
}
```

## Webhooks

Webhooks are JSON encoded POST requests made by Deus X Pay to the URL endpoint specified in the Profile that was used in the request when creating payments, payouts or withdrawals.

Webhooks expect HTTP 200 OK success status response codes.

For any other status code or timeout it will try to reach the endpoint again with an exponential time increase between retries. You can view the history of webhooks in Deus X Pay under every instance that has a webhook configured.

### Webhooks Verification

To verify webhooks from Deus X Pay you must use a Webhook Token which you can find in the Deus X App **Settings** > **Integrations**.

Always verify that the signature provided in the webhook POST data matches the one you generate on your own by signing the callback_id value with the callback_token using the following hashing algorithm:

`signature = hex(HMAC_SHA256([callback_id], key=[callback_token]))`

### Webhooks Response

All webhooks have these fields in common:

| Parameter | Description |
| --- | --- |
| callback_id | Unique webhook ID. If the webhook fails to reach endpoint, it will retry with the same ID. |
| callback_status | webhook status identifying specific event. |
| signature | Deus X Pay Signature for verification. |

For event specific response documentation see the Webhooks section for each specific endpoint.

- [Payments](#payment-webhooks)
- [Payouts](#payout-webhooks)
- [Withdrawals](#withdrawal-webhooks)

## DXP Payment Button (SDK)

A JavaScript-based payment button that can be integrated as an embedded modal within your own system, allowing you to offer an end-to-end checkout flow for instantly accepting payments on your website.

Follow these steps to offer payments using the DXP Payment Button:

- Include the Deus X Pay SDK javascript:

```html
<script type="text/javascript" src="https://static.deusxpay.com/static/js/sdk.js"></script>
```

- Add a button with the `dxp-button` class name and the following data attributes:

| Attribute | Description |
| --- | --- |
| data-product | The product or order name. |
| data-amount | The requested amount, denominated in the currency specified by data-currency. Supports both fiat and crypto-denominated amounts. Use a plain decimal string with no thousands separators (e.g. "100", not "1,00"). |
| data-currency | The currency of the requested amount. See [supported currencies](#supported-currencies) for available values. |
| data-passthrough | Optional metadata associated with the payment object, provided as a regular string. |
| data-show-payment-url | Optional. Shows an additional public payment URL, updated in real time, that can be shared or copied further. |

```html
<button class="dxp-button"
    data-product="Account deposit for a specific amount"
    data-amount="100"
    data-currency="USD"
    data-passthrough="Order 12345"
    data-show-payment-url="true">
      Click to buy
</button>
```

**Payment for any amount**

Setting `data-amount="0"` creates a payment for any amount rather than a fixed-amount purchase. In this mode, the customer can send any amount, which is automatically converted into the requested currency specified by `data-currency` and allocated on receipt, rather than being required to match a specific amount.

```html
<button class="dxp-button"
    data-product="Account deposit for any amount"
    data-amount="0"
    data-currency="USD"
    data-passthrough="Order 54321"
    data-show-payment-url="true">
      Payment for any amount
</button>
```

- Initialise the SDK using your Account ID, Profile ID, and Wallet ID, along with callbacks (if required).

| Parameter | Description |
| --- | --- |
| account | The UUID associated with your DXP account. Found in the Deus X Pay Console. |
| profile | The UUID of the payment profile. Found in the Deus X Pay Console. |
| apiEndpoint | The base URL of the Deus X Pay Console API the SDK communicates with (https://console.deusxpay.com/). |
| wallet | Specifies the multi-currency wallet to which payments will be credited, found in the DXP console. NOTE: This parameter is optional only for merchants integrated to the DXP Pay product prior to 31 March 2026; for those merchants, if omitted, it defaults to the existing "Pay" wallet UUID. Merchants integrated after this date must supply the wallet parameter explicitly. See the [Wallets](#wallets) documentation for more detail. |

```javascript
DxpSdk.setup({
    account: '<YOUR_ACCOUNT_ID>',
    profile: '<YOUR_PROFILE_ID>',
    apiEndpoint: 'https://console.deusxpay.com/',
    wallet: '<YOUR_WALLET_ID>',

    // Callbacks
    onOpen: onPaymentOpen,
    onUpdate: onPaymentUpdate,
    onIncomplete: onPaymentIncomplete,
    onSuccess: onPaymentSuccess,
    onCancel: onPaymentCancel
})

// Callback examples:
function onPaymentOpen(data, code) {
    console.log(code, data)
}

function onPaymentUpdate(data, code) {
    console.log(code, data)
}

function onPaymentIncomplete(data, code) {
    console.log(code, data)
}

function onPaymentSuccess(data, code) {
    console.log(code, data)
}

function onPaymentCancel(data, code) {
    console.log(code, data)
}
```

**Important:** these callbacks fire client-side as the payment status updates through its lifecycle, and are intended for UI/UX purposes only (e.g. showing a confirmation message). It is crucial not to rely solely on client-side data received during onSuccess, onUpdate, and onIncomplete events, as they are vulnerable to manipulation. For secure processing of transaction data, exclusively trust server-to-server webhooks, configured separately as JSON-encoded webhooks on your payment Profile, not the client-side callbacks above.

- (Optional) When the flow has been completed, the modal can be closed programmatically using:

```javascript
DxpSdk.destroy()
```

### Payment Button Example

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <link rel="icon" href="/favicon.ico"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>SDK</title>
    <style>
        html, body {
            height: 100%;
            padding: 0;
            margin: 0;
            font-family: sans-serif;
        }

        body {
            -webkit-font-smoothing: antialiased;
            padding: 0;
            margin: 0;
            height: 100%;
            width: 100%;
            display: flex;
            align-items: center;
        }

        body div.cont {
            display: flex;
            flex: 1;
            flex-direction: column;
            width: 100%;
            justify-items: center;
            justify-content: center;
            align-items: center;
            text-align: center;
        }

        body div.cont p {
            margin-bottom: 10px;
        }

        .btn {
            font-size: 15px;
            padding: 10px;
            color: white !important;
            background-color: #496cd2;
            text-decoration: none !important;
            border-radius: 5px;
            display: inline-block;
        }
    </style>
    <script type="text/javascript" src="https://static.deusxpay.com/static/js/sdk.js"></script>
</head>
<body>
<div class="cont dxp">
    <div style="min-width: 400px; padding: 20px;">
        <div id="target"></div>
    </div>
    <p>
        <button class="btn dxp-button"
                data-product="Account deposit for a specific amount"
                data-amount="100"
                data-currency="USD"
                data-passthrough="Order 12345"
                data-show-payment-url="true">
            Click to deposit $100
        </button>
    </p>
    <p>
        <button class="btn dxp-button"
                data-product="Account deposit for any amount"
                data-amount="0"
                data-currency="USD"
                data-passthrough="Order 54321"
                data-show-payment-url="true">
            Click to deposit any amount
        </button>
    </p>
</div>

<script type="text/javascript">
    function onPaymentOpen(data, code) {
        console.log(code, data)
    }

    function onPaymentUpdate(data, code) {
        console.log(code, data)
    }

    function onPaymentIncomplete(data, code) {
        console.log(code, data)
    }

    function onPaymentSuccess(data, code) {
        console.log(code, data)
    }

    function onPaymentCancel(data, code) {
        console.log(code, data)
    }

    document.addEventListener('DOMContentLoaded', () => {
        DxpSdk.setup({
            account: '<YOUR_ACCOUNT_ID>',
            profile: '<YOUR_PROFILE_ID>',
            apiEndpoint: 'https://console.deusxpay.com/',
            wallet: '<YOUR_WALLET_ID>',
            onOpen: onPaymentOpen,
            onUpdate: onPaymentUpdate,
            onIncomplete: onPaymentIncomplete,
            onSuccess: onPaymentSuccess,
            onCancel: onPaymentCancel,
        })
    })
</script>
</body>
</html>
```

## Policy Engine

The Deus X Pay Policy Engine enables rules to be applied to withdrawals and other system entities. The API facilitates user approval of associated entities. Eg Withdrawals.

### Policy Approval Allow

This endpoint allows an API key to approve a withdrawal (or other entity).

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/approvals/[ID]/allow`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the withdrawal or other system entity. |

**Payload Parameters**

There is no payload associated with the API call

**Responses**

204 Successful Response — Request: no body — Response: no body

400 Bad Request — Request: no body

```json
{
    "result": "error",
    "message": "the user is not found in the approvers list",
    "reason": "invalid_request"
}
```

### Policy Approval Block

This endpoint allows an API key to deny/block a withdrawal (or other entity).

**HTTP Request**

`POST https://api.deusxpay.com/pay/v1/approvals/[ID]/block`

**URL Parameters**

| Parameter | Description |
| --- | --- |
| ID | The ID of the withdrawal or other system entity. |

**Payload Parameters**

There is no payload associated with the API call

**Responses**

204 Successful Response — Request: no body — Response: no body

400 Bad Request — Request: no body

```json
{
    "result": "error",
    "message": "the user is not found in the approvers list",
    "reason": "invalid_request"
}
```

## Errors

### Error Payload

In the event of an error, a non-200 error code will be returned, and the response body will be a json object with three fields:

1. **result** - which will always be "error".
2. **reason** - which will be one of the string constants.
3. **result** - a human-readable string with additional error information.

### HTTP Error Codes

| Error Code | Meaning |
| --- | --- |
| 400 | Bad Request – Your request is invalid. |
| 401 | Unauthorized – Your API key or signature is wrong. |
| 403 | Forbidden – Not enough permissions. |
| 404 | Not Found – The specified resource could not be found. |
| 405 | Method Not Allowed – You tried to access endpoint with an invalid method. |
| 500 | Internal Server Error |
| 503 | Service Unavailable |

## Manual interventions for payment processing

### Cancel payment (New payments)

When a payment has not yet received any crypto, the Cancel button will allow you to remove the payment details from the public invoice link and prevent automatic conversions. This does not prevent customers from transferring crypto to the cancelled payment's blockchain address, in which case the payment will become "Address Reuse" to alert you of the manual intervention required to resolve the payment

### Crypto amount transferred does not match payment amount

Paying with crypto is unlike paying with a credit card; rather, it's similar to accepting payment using Direct bank transfer. Correspondingly, the customer must transfer the crypto amount to an address using a crypto wallet of their choice. Only once the deposit is confirmed and within the defined amount, the payment will be set to Complete.

Deus X Pay will send webhooks to your merchant website with as much information as possible to inform the customer of any problems. In some cases, [manual intervention will be required](#manual-interventions-for-payment-processing) to resolve the payment. In some cases, the Deus X Pay merchant console is required when resolving payments. Below are the descriptions of each action.

### Manual Conversion (Incomplete, Overpaid, Address Reuse)

In situations of under/overpayment or additional payments made to completed purchase payments, any unprocessed amounts can be manually processed. After processing, you will receive the amount in the desired conversion currency.

- For overpayments and additional payments, the existing payment will become Complete.
    - A conversion for the excess amount will be processed under a related payment ID, linked to the original parent payment ID
    - The related payment will share the same notes and passthrough as the parent payment
    - (Optional) A payment_complete webhook will be sent for both payment IDs upon successful conversion. The related payment webhook will include a _parent_payment_id_ attribute
- For incomplete amounts, the existing payment will be updated to Complete and contain the converted amount.
    - (Optional) A payment_complete webhook will be sent for the payment upon conversion

### Return unprocessed crypto (Incomplete, Overpaid, Address Reuse payments)

In situations where there is an unprocessed crypto amount, you may click "Return" to send back the unconverted amount to your customer. A fee may be applicable - please review your agreed fee schedule

### Re-evaluate payment (New, Incomplete, Failed payments)

When a payment is Unpaid (New / Incomplete / Failed), clicking the "Re-evaluate" button will update the payment amount and amounts received based on the latest pricing.

## Payment Tolerance

Payment tolerances enable you to automatically process payment amounts received, when these payment amounts would ordinarily require manual processing. The setting is a percentage-based value which calculates the lowest or highest amount that will be converted when the payment amount received differs from the payment amount requested.

The applicable payment fee will be charged on the processed amount.

### How to set the payment tolerance

In the Profiles section of the Deus X Pay console, the payment tolerance percentage can be set per payment currency.

Once a payment tolerance has been set, any payments created with the respective profile will adopt the tolerance setting.

Payment tolerances may be set to any value from 0% - 100%. By default, the tolerance is set to 0%.

**Note:** If 100% payment tolerance has been specified, any amount received will automatically be processed. If 0% payment tolerance is specified, the payment tolerance feature will not apply.

Editing an existing profile tolerance % after creating a payment with the same profile will have no effect on the previously created payments.

Should you wish to remove the payment tolerance, setting the percentage to 0 will ensure that any payments above or below the tolerable amount will remain Incomplete or Overpaid until a manual intervention.

**Example: Underpayment Tolerance**

1. Underpayment tolerance = 2%
2. Requested amount = 100 USD
3. Markup = 10%
4. Payment fee = 1%
5. Gross requested amount = requested amount + markup % = 100 USD + 10% = 110 USD
6. Tolerable amount = gross requested amount - tolerance % = 110 USD - 2% = 107.8 USD
7. Payment fee = Processed amount * payment fee percentage = 107.8 * 1% = 1.078 USD

If the customer sends any amount greater than or equal to the underpayment tolerable amount, the payment will be processed automatically.

**Example: Overpayment Tolerance**

1. Overpayment tolerance = 2%
2. Requested amount = 100 USD
3. Markup = 10%
4. Payment fee = 1%
5. Gross requested amount = requested amount + markup % = 100 USD + 10% = 110 USD
6. Tolerable amount = gross requested amount + tolerance % = 110 USD + 2% = 112.2 USD
7. Payment fee = Processed amount * payment fee percentage = 112.2 * 1% = 1.12 USD

If the customer sends any amount less than or equal to the overpayment tolerable amount, the payment will be processed automatically.

The payment fee will be charged on the credited amount, i.e. the amount which was processed.

## Exceptions in blockchain payment processing

### Minimum Deposit Amount

Due to the nature of the blockchain, there are situations where cryptocurrency holders or providers transfer insignificant crypto amounts ("dust") to payment addresses generated by Deus X Pay. This causes the payment status to change and become flagged in the "Requires Attention" banner without possibility of resolution.

Most of these dust transfers occur for stablecoin payments (USDT, USDC) and are for amounts less than 0.01 USDT / USDC.

There is a minimum deposit amount to mitigate the effects of dust transfers. Any amounts below the minimum deposit will be ignored and will not affect the payment status.

The minimum deposit amount is set as follows:

- 0.000001 BTC
- 0.000001 ETH
- 0.01 USDC
- 0.01 USDT

### Wrong currency paid

A customer may choose one cryptocurrency, but accidentally send another.

Most of the time, Deus X Pay is unable to detect these incorrect currencies. If undetected, the payment will simply remain "New". You may be able to resolve this dilemma with our support team's help.

If Deus X Pay is able to detect the incorrect currency transaction, it will notify of the mismatch. You may refund the incorrect currency, and the customer is then free to transfer the correct currency.

### Reused destination address

Nothing prevents a customer from accidentally (or intentionally) sending crypto to an address that has already been used for a past payment. You can configure how Deus X Pay handles address reuse when creating payments.

Purchase payments become Complete once they have been automatically or manually converted. If a customer deposits more crypto to an already Complete payment, the status will be updated to "Address Reuse" and no conversion will take place (requires manual intervention). See [purchase payments workflow](#purchase-payments)

Account payments are automatically converted upon receipt of the transaction. The payment will automatically become Complete once any amount is received and allocated. Each deposit will generate a new payment ID. No manual intervention is required to Complete the payment. See [account payments workflow](#account-payments)

### Market price volatility

The payment amount displayed is based on the latest indicative pricing. The relative volatility of the price of cryptocurrencies may result in significant fluctuations over a short period of time.

### Delays in Blockchain confirmation

Please note that it can take anywhere between a few seconds to a few minutes for Deus X Pay's wallet provider to receive the transaction on the blockchain, depending on the currency and blockchain network.

### Know your transaction (KYT) screening

All incoming payments/deposits are screened via Deus X Pay's Anti-Money Laundering (AML) software. If our AML service flags a transaction as potentially risky, then it will require manual review & approval by Deus X Pay compliance. This may result in slight delays in payment processing.