# Welcome!

## Welcome to VitePay Documentation

Welcome to VitePay! Here you'll find all the documentation you need to get up and running with VitePay & VitePay API.

## Want to jump right in?

Feeling like an eager beaver? Jump in to the quick start docs and get making your first request:

{% content-ref url="/pages/FIFZgjiqyMjcQTLkXyEt" %}
[Quick Start](/quick-start)
{% endcontent-ref %}

## Want to deep dive?

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:

{% content-ref url="/pages/yp2BRDtETUuyTp38lc7V" %}
[API Reference](/reference/api-reference)
{% endcontent-ref %}

## Open Source

VitePay is open source under **CC BY-NC-ND 4.0.**

GitHub Link: <https://github.com/imalfect/VitePay>


# Quick Start

## Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

You can generate an API key on <https://pay.imal.dev/register.html>

## Make your first invoice

To make your first request, send an authenticated request to the createTransaction endpoint. This will create a transaction.

## Create a new transaction

<mark style="color:green;">`POST`</mark> `https://pay.imal.dev/api/createTransaction`

Creates a new transaction.

#### Request Body

| Name                                          | Type   | Description                                                                                            |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| key<mark style="color:red;">\*</mark>         | string | Your merchant API key.                                                                                 |
| description<mark style="color:red;">\*</mark> | string | Description of the transaction (eg. Invoice #63729)                                                    |
| tokenid<mark style="color:red;">\*</mark>     | string | tti\_ of the vite token used for the transaction                                                       |
| amount<mark style="color:red;">\*</mark>      | String | RAW Amount of the token used for the transaction                                                       |
| memoprefix                                    | String | Prefix for the memo used in the transaction (eg. "gifts" would result in something like "gifts823729") |
| destination<mark style="color:red;">\*</mark> | String | Address the funds should be sent to.                                                                   |
| redirecturl<mark style="color:red;">\*</mark> | String | "Back to merchant" URL                                                                                 |

{% tabs %}
{% tab title="200 Transaction successfully created" %}

```javascript
{
  "code": 1,
  "id": "927192719",
  "expires": "192019281",
  "url": "https://pay.imal.dev/pay/82837829"
}
```

{% endtab %}

{% tab title="400: Bad Request memoPrefix too long" %}

```javascript
{
  "code": 2
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid TokenID" %}

```javascript
{
  "code": 3
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect destination address" %}

```javascript
{
  "code": 4
}
```

{% endtab %}

{% tab title="400: Bad Request Amount is NaN (Not a number)" %}

```javascript
{
  "code": 5
}
```

{% endtab %}

{% tab title="400: Bad Request Redirect URL invalid or empty." %}

```javascript
{
  "code": 7
}
```

{% endtab %}

{% tab title="400: Bad Request Description too long (max. 75 characters)" %}

```javascript
{
  "code": 6
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid API Key" %}

```javascript
{
  "code": 8
}
```

{% endtab %}

{% tab title="500: Internal Server Error SQL/Server Error" %}

```javascript
{
  "code": 500
}
```

{% endtab %}
{% endtabs %}

Take a look at how you might call this method using `curl`:

{% tabs %}
{% tab title="curl" %}

```
curl --location --request POST 'https://pay.imal.dev/api/createTransaction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": "AFJIOAs98ksks9",
    "description": "Invoice #92828",
    "tokenid": "tti_5649544520544f4b454e6e40",
    "amount": "100000000000000000000",
    "memoprefix": "gifts",
    "destination": "vite_2ff6ffebcf03638b20072c9b40a49778e894420ddf58e40df5",
    "redirecturl": "https://example.com"
}'
```

{% endtab %}
{% endtabs %}


# VitePay Transaction Process

1. merchants create transactions via API, each TX has a unique Vite address created as an "escrow" or "middleman" address.
2. user can be directed to a unique payment portal with payment instructions and a countdown timer
3. user must send correct amount to the middleman address before the transaction expires
4. once enough confirmations on middleman address, TX is considered processed and funds are send to the merchant's address (no need to wait for confirmations on this end)

###

<br>


# API Reference

Dive into the specifics of each API endpoint by checking out our complete documentation.

## Transactions

Everything related to transactions:

{% content-ref url="/pages/GhR0itDpU1gKMkbFgS4p" %}
[getTransaction](/reference/api-reference/gettransaction)
{% endcontent-ref %}

{% content-ref url="/pages/MoXkVHgMANjTC9MEpycH" %}
[createTransaction](/reference/api-reference/createtransaction)
{% endcontent-ref %}


# createTransaction

## Creating a new transaction

## Create a new transaction

<mark style="color:green;">`POST`</mark> `https://pay.imal.dev/api/createTransaction`

Creates a new transaction.

#### Request Body

| Name                                          | Type   | Description                                                                                            |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| key<mark style="color:red;">\*</mark>         | string | Your merchant API key.                                                                                 |
| description<mark style="color:red;">\*</mark> | string | Description of the transaction (eg. Invoice #63729)                                                    |
| tokenid<mark style="color:red;">\*</mark>     | string | tti\_ of the vite token used for the transaction                                                       |
| amount<mark style="color:red;">\*</mark>      | String | RAW Amount of the token used for the transaction                                                       |
| memoprefix                                    | String | Prefix for the memo used in the transaction (eg. "gifts" would result in something like "gifts823729") |
| destination<mark style="color:red;">\*</mark> | String | Address the funds should be sent to.                                                                   |
| redirecturl<mark style="color:red;">\*</mark> | String | "Back to merchant" URL                                                                                 |

{% tabs %}
{% tab title="200 Transaction successfully created" %}

```javascript
{
  "code": 1,
  "id": "927192719",
  "expires": "192019281",
  "url": "https://pay.imal.dev/pay/82837829"
}
```

{% endtab %}

{% tab title="400: Bad Request memoPrefix too long" %}

```javascript
{
  "code": 2
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid TokenID" %}

```javascript
{
  "code": 3
}
```

{% endtab %}

{% tab title="400: Bad Request Incorrect destination address" %}

```javascript
{
  "code": 4
}
```

{% endtab %}

{% tab title="400: Bad Request Amount is NaN (Not a number)" %}

```javascript
{
  "code": 5
}
```

{% endtab %}

{% tab title="400: Bad Request Redirect URL invalid or empty." %}

```javascript
{
  "code": 7
}
```

{% endtab %}

{% tab title="400: Bad Request Description too long (max. 75 characters)" %}

```javascript
{
  "code": 6
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid API Key" %}

```javascript
{
  "code": 8
}
```

{% endtab %}

{% tab title="500: Internal Server Error SQL/Server Error" %}

```javascript
{
  "code": 500
}
```

{% endtab %}
{% endtabs %}


# getTransaction

Get an existing transaction status.

## Checking transaction status

## Check transaction status

<mark style="color:green;">`POST`</mark> `https://pay.imal.dev/api/getTransaction`

#### Request Body

| Name                                   | Type   | Description                   |
| -------------------------------------- | ------ | ----------------------------- |
| txID<mark style="color:red;">\*</mark> | String | Transaction ID (eg. 28376237) |

{% tabs %}
{% tab title="200: OK Transaction exists, waiting for payment" %}

```javascript
{
  "code": 1,
  "memo": "l28618911",
  "mmAddress": "vite_2ff6ffebcf03638b20072c9b40a49778e894420ddf58e40df5",
  "amount": "100000000000000000000",
  "tokenId": "tti_5649544520544f4b454e6e40",
  "txCode": "1",
  "expirationTime": "1655840368",
  "tokenSymbol": "VITE",
  "tokenDecimals": "18",
  "description": "hello%20this%20is%description",
  "merchantVerified": true,
  "merchantName": "iMalFect"
}
```

{% endtab %}

{% tab title="200: OK undefined" %}

```javascript
{
  "code": 1,
  "txCode": 2
}
```

{% endtab %}

{% tab title="200: OK Transaction exists, awaiting confirmations" %}

```javascript
{
  "code": 1,
  "memo": "l28618911",
  "mmAddress": "vite_2ff6ffebcf03638b20072c9b40a49778e894420ddf58e40df5",
  "amount": "100000000000000000000",
  "tokenId": "tti_5649544520544f4b454e6e40",
  "txCode": "1",
  "expirationTime": "1655840368",
  "tokenSymbol": "VITE",
  "tokenDecimals": "18",
  "description": "hello%20this%20is%description",
  "merchantVerified": true,
  "merchantName": "iMalFect",
  "confirmations": 57
}
```

{% endtab %}

{% tab title="200: OK Transaction successful" %}

```javascript
{
  "code": 1,
  "txCode": 3
}
```

{% endtab %}

{% tab title="404: Not Found Transaction ID doesn't exist" %}

```javascript
{
  "code": 2
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server Issue 1" %}

```javascript
{
  "code": 500
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server Issue 2" %}

```javascript
{
  "code": 600
}
```

{% endtab %}
{% endtabs %}


# Transactions table

* Table name: transactions
* Columns: 14

## Brief Columns description

* merchantName: type: text, escaped merchant name
* txDescription: type:text, description of the transaction
* txToken: type:varchar(100), tti\_ of the token used for the transaction
* txAmount: type:text, raw amount of the token used for the transaction
* mmSeed: type:text, AES256 encrypted middleman account seed
* mmAddress: type:varchar(100), address of the middleman account
* txMemo: type:text, memo of the transaction
* txDeadline: type:varchar(100), unix timestamp of the transaction expiration
* txID: type:varchar(100), transaction ID
* txDestination: type:varchar(100), merchant's vite address
* mechantVerified: type:varchar(100), status of merchant verification (true/false)
* txHash: type:varchar(100), hash of the transaction that confirmations should be awaited for
* redirectURL: type:text, "Back to merchant" URL
* css: type:text, optional css used to style the merchant's name, settable in merchants table


# Merchants table

* Table name: merchants
* Columns: 4

## Brief Columns description

* name: type:varchar(100), escaped merchant name
* apikey: type:varchar(100), sha256 hashed API key
* verified: type:varchar(100), (true/false) merchant verified status
* css: type:text, optional css to style merchant's name on the payment page


# expiredTransactions table

* Table name: expiredTransactions
* Columns: 12

## Brief Columns description

* merchantName: type: text, escaped merchant name
* txDescription: type:text, description of the transaction
* txToken: type:varchar(100), tti\_ of the token used for the transaction
* txAmount: type:text, raw amount of the token used for the transaction
* mmSeed: type:text, AES256 encrypted middleman account seed
* mmAddress: type:varchar(100), address of the middleman account
* txMemo: type:text, memo of the transaction
* txID: type:varchar(100), transaction ID
* txDestination: type:varchar(100), merchant's vite address
* txHash: type:varchar(100), hash of the transaction that confirmations should be awaited for
* redirectURL: type:text, "Back to merchant" URL
* txStatus: type:varchar(100), status code for the transaction

## Status Codes in the database

* 3 => Transaction was successful
* 2 => Transaction expired
* 4 => Transaction manually cancelled by database admin


# Setting up a self-hosted instance

## Requirements:

* An Linux/Windows server
* MariaDB Installed
* In case of commercial use (for self-hosted only!) permission from iMalFect (check License.md on GitHub)

## Setup

1\. Create a VitePay SQL Database using the dump provided

2\. Copy the .env.example file as .env and edit details, more description about the .env file here

3\. Replace the public reCaptcha key with yours in the registerMerchant html file

4\. Run "npm start" in order to run the webserver

5\. Visit the webserver

6\. You're all set! Contact imalfect#7015 on discord for support!


# .env file variables

Example .env file:

```
SERVER_PORT=8086 # Port where the server should run
WEB_URL=http://example.com # Url of the server (with port)
CAPTCHA=eadjfij4tfy4wuf4wuyfhg4u # reCaptcha secret (make sure to also put the public in the merchant register page!!)dotRATE_LIMIT=10 # How many requests can be made per minute
RATE_LIMIT=10 # How many requests can be made per minute
    ## Database config ##
DB_HOST=1.2.3.4 # database ip
DB_USER=administator
DB_PASS=12345678
# Name of the database you created #
DB_NAME=VitePay
# Passphrase to encrypt database entries (seeds) #
ENCRYPT_KEY=kduw28
    ## Merchant Config ##
# Length of the API key generated (recommended 12-32)#
APIKEY_LENGTH=18

    ## Vite Config ##
# Node URL (HTTP not WebSocket!)
NODE_URL=https://node-vite.imal.dev
```

* SERVER\_PORT => Port on which the webserver should run on.
* WEB\_URL => URL of the VitePay instance
* CAPTCHA => reCaptcha Secret
* RATE\_LIMIT => Limit on how many requests can be made on specific routes.
* DB\_HOST => MariaDB Server IP
* DB\_USER => MariaDB Server username
* DB\_PASS => MariaDB User password
* DB\_NAME => Name of the VitePay database
* ENCRYPT\_KEY => Passphrase used to encrypt database entries (seeds)
* APIKEY\_LENGTH => How long should API keys be (recommended 12-32)
* NODE\_URL => Vite Node HTTP url


# How to verify merchants

Verifying merchants gives them a blue tick next to the name.

A: It's simple: just change the "verified" column in the merchants table, on selected merchant's row to "true"


# FAQ

## Q: Can I use my own website, and simply fetch the data with the API instead of the payment link?

{% hint style="success" %}
Yes! Just make sure to add "Powered by <mark style="color:blue;">VitePay</mark>" in the footer for example with link to <mark style="color:blue;">VitePay</mark>'s website.
{% endhint %}

## Q: I've found a bug, how can I help?

{% hint style="info" %}
If you've found a bug and know how to solve it, open a <mark style="color:yellow;">pull request</mark> at our <mark style="color:orange;">GitHub</mark>, if you don't know how to solve it, open an <mark style="color:yellow;">issue</mark>.
{% endhint %}

## Q: What are the fees?

{% hint style="success" %} <mark style="color:blue;">VitePay</mark> has absolutely <mark style="color:green;">no fees</mark>.
{% endhint %}

## Q: Can I use <mark style="color:blue;">VitePay</mark> for my online store?

{% hint style="success" %} <mark style="color:green;">Of course!</mark>
{% endhint %}