# TransVoucher API (v1.0.0) — Complete API Reference

TransVoucher API allows you to create and manage cryptocurrency payment intents for your customers. Accept fiat payments and receive cryptocurrency settlements.

**Contact:** TransVoucher Support · [support@trans-voucher.com](mailto:support@trans-voucher.com) · [Website](https://trans-voucher.com)
**Terms of Service:** [View](https://trans-voucher.com/terms-of-service)

---

## Base URLs

- **`https://api.trans-voucher.com/v1.0`** — Production server
- **`https://sandbox-api.trans-voucher.com/v1.0`** — Sandbox server

---

## Authentication

### ApiKeyAuth

- **Type:** apiKey
- **In:** header

Your API key from the TransVoucher dashboard

### ApiSecretAuth

- **Type:** apiKey
- **In:** header

Your API secret from the TransVoucher dashboard

---

## Endpoints

### GET /

**API Status**

Check if the API is active and get basic information

**Authentication:** None required

**Responses:**

#### ✅ 200 — API is active

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | No | Example: `TransVoucher Production API 1.0` |
| `status` | string | No | Example: `active` |
| `environment` | string | No | Example: `production` |


### POST /payment/create

**Create Payment Intent**

Create a new payment intent/link for a customer to complete payment

**Authentication:** ApiKeyAuth, ApiSecretAuth

**Request Body (required):**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | number(double) | No | Payment amount in fiat currency. Required unless is_price_dynamic is true. When is_price_dynamic is true, customers can enter their own amount during checkout. Example: `100.5` |
| `currency` | string | No | Fiat currency code (default: USD) Example: `USD` |
| `title` | string | Yes | Payment title/description Example: `Order #12345` |
| `description` | string | No | Additional payment description Example: `Purchase of premium subscription` |
| `redirect_url` | string(uri) | No | URL to redirect to after payment (deprecated, use success_url and cancel_url) Example: `https://example.com/payment/complete` |
| `success_url` | string(uri) | No | URL to redirect to after successful payment Example: `https://example.com/payment/success` |
| `cancel_url` | string(uri) | No | URL to redirect to if payment is cancelled Example: `https://example.com/payment/cancel` |
| `metadata` | object | No | Custom metadata to attach to the payment (returned in webhooks) Example: `{"order_id":"12345","customer_id":"cust_abc123"}` |
| `customer_details` | object | No | Customer information |
| `theme` | string (dark|light) | No | UI theme for payment page Example: `light` |
| `lang` | string (en|es|fr|de|it|pt|ru|zh|ja|ko|tr|ka) | No | Language code for payment page Example: `en` |
| `default_payment_method` | string (card|apple-pay|google-pay) | No | Default payment method to pre-select or force Example: `card` |
| `payment_method_forced` | boolean | No | If true, only the default_payment_method will be available. If false, user can choose other methods |
| `expires_at` | string(date-time) | No | When the payment link expires Example: `2024-12-31T23:59:59Z` |
| `custom_fields` | object | No | Custom fields to collect from customer Example: `{"company_name":"Acme Corp"}` |
| `multiple_use` | boolean | No | Whether the payment link can be used multiple times |
| `cancel_on_first_fail` | boolean | No | Cancel payment link after first failed attempt |
| `is_price_dynamic` | boolean | No | Whether the customer can enter their own amount |

**Responses:**

#### ✅ 201 — Payment intent created successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | object | No |  |

#### ❌ 400 — Bad request

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Invalid request parameters"
}
```

#### ❌ 401 — Authentication failed

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Invalid API credentials"
}
```

#### ❌ 422 — Validation error

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Validation failed",
    "errors": {
        "amount": [
            "The amount field is required."
        ],
        "title": [
            "The title field is required."
        ]
    }
}
```

#### ❌ 500 — Internal server error

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "An internal error occurred"
}
```


### GET /payment/status/{referenceId}

**Get Payment Status**

Retrieve the current status of a payment by transaction ID

**Authentication:** ApiKeyAuth, ApiSecretAuth

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `referenceId` | string | Yes | The transaction ID |

**Responses:**

#### ✅ 200 — Payment status retrieved successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | object | No |  |

#### ❌ 401 — Authentication failed

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Invalid API credentials"
}
```

#### ❌ 404 — Resource not found

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Transaction not found"
}
```


### GET /payment/list

**List Payments**

Retrieve a paginated list of payments with optional filtering

**Authentication:** ApiKeyAuth, ApiSecretAuth

**Query Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `to_date` | string(date) | No | Filter payments to this date (YYYY-MM-DD) |

**Responses:**

#### ✅ 200 — Payments retrieved successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | object | No |  |

#### ❌ 400 — Bad request

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Invalid request parameters"
}
```

#### ❌ 401 — Authentication failed

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Invalid API credentials"
}
```

#### ❌ 422 — Validation error

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Validation failed",
    "errors": {
        "amount": [
            "The amount field is required."
        ],
        "title": [
            "The title field is required."
        ]
    }
}
```


### GET /payment-link/status/{paymentLinkId}

**Get Payment Link Status**

Retrieve the status of a payment link by its ID

**Authentication:** ApiKeyAuth, ApiSecretAuth

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `paymentLinkId` | string | Yes | The payment link ID |

**Responses:**

#### ✅ 200 — Payment link status retrieved successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | object | No |  |

#### ❌ 401 — Authentication failed

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Invalid API credentials"
}
```

#### ❌ 404 — Resource not found

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Transaction not found"
}
```


### GET /currencies

**Get Active Currencies**

Retrieve all active processing currencies

**Authentication:** None required

**Responses:**

#### ✅ 200 — Currencies retrieved successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | array[object] | No |  |


### GET /networks

**Get Active Networks**

Retrieve all active settlement networks (blockchain networks)

**Authentication:** None required

**Responses:**

#### ✅ 200 — Networks retrieved successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | array[object] | No |  |


### GET /commodities

**Get Active Commodities**

Retrieve all active settlement commodities (cryptocurrencies)

**Authentication:** None required

**Responses:**

#### ✅ 200 — Commodities retrieved successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `success` | boolean | No | Example: `1` |
| `data` | array[object] | No |  |


### GET /conversion-rate/{network}/{commodity}/{fiatCurrency}/{paymentMethod}

**Get Conversion Rate**

Get the current conversion rate for a network, commodity, and fiat currency pair

**Authentication:** None required

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `network` | string | Yes | Network short_code (use /networks endpoint to see available values) |
| `commodity` | string | Yes | Commodity short_code (use /commodities endpoint to see available values) |
| `fiatCurrency` | string | Yes | Fiat currency code (use /currencies endpoint to see available values) |
| `paymentMethod` | string | Yes | Payment method (e.g., card, bank_transfer) |

**Responses:**

#### ✅ 200 — Conversion rate retrieved successfully

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `data` | object | No |  |

#### ❌ 400 — Bad request

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `error` | boolean | No | Example: `1` |
| `message` | string | No | Error message Example: `Invalid request` |
| `errors` | object | No | Validation errors (only for 422 responses) |

Example:

```json
{
    "error": true,
    "message": "Invalid request parameters"
}
```


### POST /payment/webhook

**Receive Payment Webhooks (Your Server)**

This endpoint represents YOUR webhook endpoint that will receive payment events from TransVoucher. You must configure this URL in your merchant dashboard. All webhook requests include X-Webhook-Signature header for verification using HMAC SHA256 with your endpoint secret.

**Authentication:** None required

**Header Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-Webhook-Signature` | string | Yes | HMAC SHA256 signature of the request body (format: sha256=<hex>). Verify this using your endpoint secret. |

**Request Body (required):**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event` | string (payment_intent.created|payment_intent.attempting|payment_intent.processing|payment_intent.succeeded|payment_intent.failed|payment_intent.cancelled|payment_intent.expired|system.health_check) | No | Event type |
| `timestamp` | string(date-time) | No | Webhook event timestamp |
| `data` | oneOf | No |  |

**Responses:**

#### ✅ 200 — Webhook acknowledged. Always return 2xx to confirm receipt — whether you processed the event or intentionally skipped it. Returning 2xx with an optional informative body (e.g. {"status":"skipped","reason":"duplicate"}) is the correct way to skip a webhook.

#### ❌ 4xx — Do NOT return 4xx codes. Any 4xx response is treated the same as 5xx — a failure that will be retried. If you intentionally want to skip or ignore a webhook, return 200 instead.

#### ❌ 5xx — Unexpected error on your end. We will retry delivery automatically on this schedule: after 1 min, 3 min, 10 min, 30 min, then every hour indefinitely. If no successful delivery occurs for 15 continuous hours and more than 100 failures accumulate, webhook delivery will be automatically disabled for your sales channel and you will be notified.


---

*Generated by [CleanDocs](https://cleandocs.dev) — AI-readable API documentation*