# Introduction

The Fizen Pay API provides a simple and powerful REST API to integrate CryptoCurrencies payments into your business or application.

## Authentication <a href="#authentication" id="authentication"></a>

Most requests to the Payment API must be authenticated with an API key. You can create an API key in your [Settings](https://merchant.fizen.io/dashboard/) page after creating a Fizen Pay account.

Authenticated API requests should be made with a `X-FP-API-KEY` header. Your secret API key should be passed as the value.

If authentication fails, a JSON object with an error message will be returned as a response along with HTTP status 401 Unauthorized.

## Pagination <a href="#pagination" id="pagination"></a>

All GET endpoints which return an object list support pagination with pagination information inside the URL queries. This means that to get all objects, you need to paginate through the results. Default limit is set to 10 but values up to 100 are permitted.

| Query  | Description                                  | Default        |
| ------ | -------------------------------------------- | -------------- |
| page   | The page number                              | 1 (first page) |
| limit  | The number of items in page. Up to 100 items | 10             |
| search | Search some fields of items by given text    | empty          |

## Errors

All error messages include a `statusCode` identifier and a pre-defined`message`. , which is used for address the error and localize a human readable message. For example:

`{ "message": "SECURITY.INVALID_OTP", "statusCode": 401 }`

{% content-ref url="/pages/twiJA7UYNY3hXvumoDzW" %}
[Getting Started](/getting-started)
{% endcontent-ref %}

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


# Process Flow

The instructions below show how Users, Merchants process with Fizen Pay for payment requests.

![Process flow](https://2424647213-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff67IkjlWYtXbtgpmwU0A%2Fuploads%2FCxuVrZbifwjR2SphuyC5%2FScreen%20Shot%202022-03-18%20at%2018.32.00.png?alt=media\&token=c560dfdd-7c69-402e-9273-88ab6eb5424b)

### Charge status

Based on the certain payment status, the charge status should be updated accordingly:

* **NEW**: Merchant has been newly created a charge for a payment order.
* **PENDING**: The payment has been made by user transaction on the blockchain and waiting for confirmation.
* **COMPLETED**: The transaction is confirmed and the payment amount has met the expectation.
* **EXPIRED**: No transaction has been detected until the expired time. (1 day after the charge is created)
* **UNRESOLVED**: The transaction is confirmed and the payment amount has NOT met the expectation. There are 5 contexts for UNRESOLVED payment as described below.
  * [ ] **UNRESOLVED - UNDERPAID**: The amount is less than expected.
  * [ ] **UNRESOLVED - OVERPAID**: The amount is greater than expected.
  * [ ] **UNRESOLVED - MULTIPLE:** There are more than 1 transaction sent for 1 payment.
  * [ ] **UNRESOLVED - DELAYED:** The transaction has been sent after the expired time.
  * [ ] **UNRESOLVED - OTHER**: Other unsuccessful payment reasons.
* **RESOLVED**: The merchant has marked an UNRESOLVED payment as resolved
* **CANCELLED**: The merchant has canceled the payment. Only NEW charges can be canceled.
* **REFUNDED**: The merchant has marked a payment as refunded. The refund process is made by the merchant outside of Fizen Pay. Fizen Pay doesn't manage this process.


# Getting Started

A quick start guide can be good to help merchants get up and running with your API in a few steps.


# Register

Merchant must create an account at Register Page before making all authorized requests to the system.

{% hint style="info" %}
You can make requests to Fizen Pay directly on the **Web app** by logged-in account or make external requests (from: e-commerce platforms, your applications/systems...) by **API keys**.
{% endhint %}

1. Register an account on Sandbox environment for developing or testing purposes
   * <https://merchant-testmode.fizen.io/signup>
2. Register a production account to launch your business:
   * &#x20;<https://merchant.fizen.io/signup>


# Environment

There are 2 environments for merchant integration. All functions should work fine on the Sandbox environment before integrating on the Production environment.

* **Sandbox**:&#x20;
  * Web app: <https://merchant-testmode.fizen.io>
  * Register page: <https://merchant-testmode.fizen.io/signup>
  * API endpoint: <https://api-sandbox.fizen.io/api/integration/v1>
* **Production**:
  * Web app: <https://merchant.fizen.io>
  * Register page: <https://merchant.fizen.io/signup>
  * API endpoint: <https://pay-api.fizen.io/api/integration/v1>


# Get your API keys

There are 2 environments for merchant integration. All functions should work fine on the Sandbox environment before integrating on the Production environment.

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 from your **Setting page** at any time.

* Generate on [Sandbox](https://merchant-testmode.fizen.io/dashboard/settings) environment
* Or Generate on [Production](https://merchant.fizen.io/dashboard/settings) environment


# Make your first API request

To make your first request, send an authenticated request to the /charges endpoint. This will create a charge.

## Create a charge.

<mark style="color:green;">`POST`</mark> `/charges`

To create a charge, following information should be included in payload request&#x20;

More details at [Create a charge](/reference/api-reference/charges/create-a-charge)

#### Request Body

| Name                                          | Type   | Description                                            |
| --------------------------------------------- | ------ | ------------------------------------------------------ |
| name<mark style="color:red;">\*</mark>        | string | Name of the charge                                     |
| description                                   | string | Description of the charge                              |
| logoUrl                                       | string | Charge image URL                                       |
| metadata                                      | string | Metadata associated with the charge                    |
| localPrice<mark style="color:red;">\*</mark>  | object | amount: Charge amount, currency: Charge local currency |
| redirectUrl<mark style="color:red;">\*</mark> | string | Redirect URL when charge payment is completed          |
| cancelUrl<mark style="color:red;">\*</mark>   | string | Cancel URL                                             |

{% tabs %}
{% tab title="201: Created Charge successfully created" %}

```javascript
{
    "statusCode": 201,
    "time": "2022-03-09T09:27:14.456Z",
    "data": {
    // Charge data come here
    },
    "total": 0
}
```

{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For testing purpose, after create a charge, you can still cancel the charge by using [Cancel a charge](/reference/api-reference/charges/cancel-a-charge) API. Prefer full API documents in the next sections.
{% endhint %}


# API Reference

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

## Charges

All the methods associated with `CRUD`ing or operating actions for charges.&#x20;

{% content-ref url="/pages/GNOfT9hSobXf3SizM08r" %}
[Charges](/reference/api-reference/charges)
{% endcontent-ref %}


# Charges

To request a cryptocurrency payment, you create a charge. You can create, view or update your charges.

## Charge resource

{% hint style="info" %}
**Note**: Since cryptocurrency payments are push payments, a charge will expire after a waiting period (payment window) if no payment has been detected. Charges are identified by a unique code.
{% endhint %}

#### Fields

| FIELD                   | TYPE         | DESCRIPTION                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                      | string       | Charge id                                                                                                                                                                                                                                                                                                                                                             |
| transactionType         | string       | Enum value. One of `EXTERNAL, PRODUCT_CHECKOUT, INVOICE`                                                                                                                                                                                                                                                                                                              |
| amountReceived          | Object       | List of payments of this charge.                                                                                                                                                                                                                                                                                                                                      |
| merchantId              | string       | Id of owner/creator                                                                                                                                                                                                                                                                                                                                                   |
| name                    | string       | Charge name                                                                                                                                                                                                                                                                                                                                                           |
| description             | string       | Charge description                                                                                                                                                                                                                                                                                                                                                    |
| pricingType             | string       | Enum value. One of `no_price, fixed_price`                                                                                                                                                                                                                                                                                                                            |
| status                  | string       | Enum value. One of `NEW, PENDING, COMPLETED, EXPIRED, UNRESOLVED, RESOLVED, CANCELLED, REFUNDED`                                                                                                                                                                                                                                                                      |
| context                 | string       | For charges with `UNRESOLVED` status, additional context is provided. Context can be one of the following: `UNDERPAID`, `OVERPAID`, `DELAYED`, `MULTIPLE`, `MANUAL`, `OTHER`                                                                                                                                                                                          |
| localCurrency           | string       | Local currency used for the charge. Default is `USD`                                                                                                                                                                                                                                                                                                                  |
| localPrice              | Object       | <p>Charge price by local currency. This object has 2 fields.<br><code>amount</code>: Charge amount.<br><code>currency</code>: local currency used</p>                                                                                                                                                                                                                 |
| fizenpayFeePerc         | number       | FizenPay service fee. Initialized with `0.5`, mean FizenPay will cut out 0.5% value of payments                                                                                                                                                                                                                                                                       |
| flexiblePaymentSettings | Object       | <p>Flexible payment settings at the time that the charge is created. This object has 3 fields.<br><code>type</code>: Enum value. One of <code>ABSOLUTE, RELATIVE.</code><br><code>underPaymentThresholdValue</code>: value that merchant accept for underpaid payment.<br><code>overPaymentThresholdValue</code>: value that merchant accept of overpaid payment.</p> |
| metadata                | any          | Self defined metadata provided creator.                                                                                                                                                                                                                                                                                                                               |
| logoUrl                 | string       | Merchant logo URL. This logo will be displayed on the payment screen.                                                                                                                                                                                                                                                                                                 |
| redirectUrl             | string       | Redirect URL                                                                                                                                                                                                                                                                                                                                                          |
| cancelUrl               | string       | Cancel URL                                                                                                                                                                                                                                                                                                                                                            |
| hostedUrl               | string       | Hosted URL which is generated by FizenPay                                                                                                                                                                                                                                                                                                                             |
| timeline                | Object Array | <p>Charge status changes. This object has 3 fields.<br><code>status</code>: changed status.<br><code>context</code>: Context that status is changed to <code>UNRESOLVED</code>.<br><code>time</code>: the time that status changed</p>                                                                                                                                |
| code                    | string       | Unique charge code. Generated by FizenPay                                                                                                                                                                                                                                                                                                                             |
| resolvedRemark          | string       | Any remark when merchant resolves an unresolved charge.                                                                                                                                                                                                                                                                                                               |
| expiredAt               | Date         | Expired time if there is no payment is made for this charge                                                                                                                                                                                                                                                                                                           |
| createdAt               | Date         | Time that charge is created                                                                                                                                                                                                                                                                                                                                           |
| updatedAt               | Date         | Time that charge is last updated                                                                                                                                                                                                                                                                                                                                      |
| amountRequested         | string       | Local currency or Crypto currency requested to pay                                                                                                                                                                                                                                                                                                                    |
| currencyType            | string       | `LOCAL_CURRENCY` or `CRYPTO_CURRENCY`. The type of currency is requested to pay                                                                                                                                                                                                                                                                                       |
| cryptoSlug              | string       | Crypto slug of crypto currency requested if currencyType= `CRYPTO_CURRENCY`                                                                                                                                                                                                                                                                                           |
|                         |              |                                                                                                                                                                                                                                                                                                                                                                       |

You can explore more details of  charge actions by go through next API document details

#### Object `amountReceived`

| FIELD           | TYPE   | DESCRIPTION                                 |
| --------------- | ------ | ------------------------------------------- |
| crypto          | string | Cryptocurrency symbol                       |
| cryptoAmount    | string | Paid amount by crypto                       |
| localAmount     | string | Paid amount converted to local currency     |
| localCurrency   | string | Local currency symbol                       |
| transactionHash | string | Blockchain transaction hash for the payment |

#### Object `timeline`

| FIELD   | TYPE   | DESCRIPTION                                                                                           |
| ------- | ------ | ----------------------------------------------------------------------------------------------------- |
| status  | string | Status of charge. One of: NEW, PENDING, COMPLETED, EXPIRED, UNRESOLVED, RESOLVED, CANCELLED, REFUNDED |
| context | string | Context detail if the charge is UNRESOLVED. One of: OVERPAID, UNDERPAID, MULTIPLE, DELAYED, OTHER     |

### JSON sample

```
{
  "data": {
    "addresses": {
      "bnb-bsc": {
        "address": "0x0000000000000000000000000000000000000000",
        "cmcId": 1839,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "busd-bsc": {
        "address": "0x718f381412b0ec0B9a6f69a77E3c7128C75E77B5",
        "cmcId": 4687,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "doge-bsc": {
        "address": "0x6aed42281c7bE19fa5f7a6ee5d873B85A5306bFe",
        "cmcId": 74,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "eth-bsc": {
        "address": "0x17fA95F49e69F82766C7930D4035b2973fbe95b8",
        "cmcId": 2396,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "luna-bsc": {
        "address": "0xc4E4FE5FcB38fE9D3BC327e384A57105955C9F9d",
        "cmcId": 4172,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "shib-bsc": {
        "address": "0x00A7D83B69C8c9223438F0Aca93453c89e0E66Ac",
        "cmcId": 5994,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdc-bsc": {
        "address": "0x3a943EFa37979952DE37168aE7D9B2E8723D9316",
        "cmcId": 3408,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdt-bsc": {
        "address": "0x53653887c75d611A8EfbdA2c1FB97CFD17Bfff71",
        "cmcId": 825,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      }
    },
    "amountReceived": [
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849013",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849113",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "code": "ML1A7PJ3F3PY",
    "context": "MULTIPLE",
    "createdAt": "2022-05-23T06:58:49.557Z",
    "currencyType": "LOCAL_CURRENCY",
    "customerEmail": "test@gmail.com",
    "customerName": "",
    "exchangeRateByUSD": "1",
    "exchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "expiredAt": "2022-05-24T06:58:49.544Z",
    "fizenpayFeePerc": "33",
    "flexiblePaymentSettings": {
      "overPaymentCurrency": "USD",
      "overPaymentThresholdValue": "2000",
      "type": "RELATIVE",
      "underPaymentCurrency": "USD",
      "underPaymentThresholdValue": "50"
    },
    "hostedUrl": "https://payment.fizen.io/commerce/charges/ML1A7PJ3F3PY",
    "id": "628b30a923ed950008b950a9",
    "localCurrency": "USD",
    "localExchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "localPrice": {
      "amount": "0.2",
      "currency": "USD"
    },
    "merchant": {
      "email": "test@gmail.com",
      "name": null
    },
    "merchantId": "628603dd75ebdf00083568dc",
    "name": "INVOICE - ML1A7PJ3F3PY",
    "payment": {
      
    },
    "pricing": {
      "bnb-bsc": {
        "amount": "0.000614952066849013",
        "cmcId": 1839,
        "currency": "BNB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "614952066849013"
      },
      "busd-bsc": {
        "amount": "0.199891971552207288",
        "cmcId": 4687,
        "currency": "BUSD",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199891971552207288"
      },
      "doge-bsc": {
        "amount": "2.311447916104313901",
        "cmcId": 74,
        "currency": "DOGE",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "2311447916104313901"
      },
      "eth-bsc": {
        "amount": "0.000097520429224721",
        "cmcId": 2396,
        "currency": "WETH",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "97520429224721"
      },
      "luna-bsc": {
        "amount": "1033.239104414727143858",
        "cmcId": 4172,
        "currency": "LUNA",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "1033239104414727143858"
      },
      "shib-bsc": {
        "amount": "16404.238360024876160848",
        "cmcId": 5994,
        "currency": "SHIB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "16404238360024876160848"
      },
      "usdc-bsc": {
        "amount": "0.199920431500040177",
        "cmcId": 3408,
        "currency": "USDC",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199920431500040177"
      },
      "usdt-bsc": {
        "amount": "0.200178833393318847",
        "cmcId": 825,
        "currency": "USDT",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "200178833393318847"
      }
    },
    "pricingType": "fixed_price",
    "showLogo": true,
    "status": "UNRESOLVED",
    "supportEmail": "test@gmail.com",
    "timeline": [
      {
        "context": null,
        "status": "NEW",
        "time": "2022-05-23T06:58:49.557Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:01:41.758Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "COMPLETED",
        "time": "2022-05-23T07:01:51.660Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:02:18.664Z",
        "transactionDetail": null
      },
      {
        "context": "MULTIPLE",
        "status": "UNRESOLVED",
        "time": "2022-05-23T07:02:24.639Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "transactionType": "INVOICE",
    "updatedAt": "2022-05-26T09:04:10.037Z"
  },
  "statusCode": 200,
  "time": "2022-08-02T16:31:36.674Z",
  "total": 0
}
```


# Create a charge

Create a charge for merchant with the given information in the request payload

## Create a charge

<mark style="color:green;">`POST`</mark> `/charges`

#### Request Body

| Name                                         | Type   | Description                                                        |
| -------------------------------------------- | ------ | ------------------------------------------------------------------ |
| name                                         | string | Charge name                                                        |
| description                                  | string | Charge description                                                 |
| logoUrl                                      | string | Charge image URL                                                   |
| localPrice<mark style="color:red;">\*</mark> | Object | <p>amount: Charge amount</p><p>currency: Charge local currency</p> |
| metadata                                     | any    | Self defined metadata                                              |
| redirectUrl                                  | string | Redirect URL                                                       |
| cancelUrl                                    | string | Cancel URL                                                         |

{% tabs %}
{% tab title="201: Created Charge is created successfully" %}

```javascript
{
    "statusCode": 201,
    "time": "2022-01-12T16:32:37.178Z",
    "data": {
        "code": "_PM3TX-7nVNY4K1pDqz8u",
        "hostedUrl": "https://payment.fizen.io/commerce/charges/_PM3TX-7nVNY4K1pDqz8u"
    },
}
```

{% endtab %}

{% tab title="401: Unauthorized Request is unauthorized" %}

```javascript
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

#### Example request:

```
curl --location --request POST 'https://pay-api.fizen.io/api/integration/v1/charges' \
--header 'X-FP-API-KEY: 7abd3993-daf7-4322-84c6-c86e04b3d884' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Charge name",
    "description": "Charge description",
    "localPrice": {
        "amount": 100,
        "currency": "USD"
    },
    "metadata": {
        "orderId": "order-id1",
        "orderKey": "key1",
        "source": "some-ecommerce"
    },
    "logoUrl": "https://logo-url.com/image.png",
    "redirectUrl": "https://ecommerce-endpoint.com/redirect-url",
    "cancelUrl": "https://ecommerce-endpoint.com/cancel-url"
}'
```

#### Example response:

```
{
    "statusCode": 201,
    "time": "2022-01-12T16:32:37.178Z",
    "data": {
        "code": "OST1FNY35QDL",
        "hostedUrl": "https://payment.fizen.io/commerce/charges/OST1FNY35QDL"
    },
}
```


# List charges

Lists all the charges belong to you.

## List charges.&#x20;

<mark style="color:blue;">`GET`</mark> `/charges`

{% tabs %}
{% tab title="200: OK All charges are listed" %}

{% endtab %}

{% tab title="401: Unauthorized Request is unauthorized" %}

```javascript
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

See [Pagination](/#pagination) for common request parameters. Besides, you can get all charges by specific status with parameter `status`. See more status at [Charge Status](/process-flow#charge-status)

#### Example request:

```
curl --location --request GET 'https://pay-api.fizen.io/api/integration/v1/charges' \
--header 'X-FP-API-KEY: 7abd3993-daf7-4322-84c6-c86e04b3d884'
```

#### Example response:

```
{
  "statusCode": 200,
  "time": "2022-04-18T04:46:14.070Z",
  "data": [
    {
      "addresses": {
        "bnb-bsc": {
          "address": "0x0000000000000000000000000000000000000000",
          "cmcId": 1839,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        },
        "busd-bsc": {
          "address": "0x718f381412b0ec0B9a6f69a77E3c7128C75E77B5",
          "cmcId": 4687,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        },
        "doge-bsc": {
          "address": "0x6aed42281c7bE19fa5f7a6ee5d873B85A5306bFe",
          "cmcId": 74,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        },
        "eth-bsc": {
          "address": "0x17fA95F49e69F82766C7930D4035b2973fbe95b8",
          "cmcId": 2396,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        },
        "luna-bsc": {
          "address": "0xc4E4FE5FcB38fE9D3BC327e384A57105955C9F9d",
          "cmcId": 4172,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        },
        "shib-bsc": {
          "address": "0x00A7D83B69C8c9223438F0Aca93453c89e0E66Ac",
          "cmcId": 5994,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        },
        "usdc-bsc": {
          "address": "0x3a943EFa37979952DE37168aE7D9B2E8723D9316",
          "cmcId": 3408,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        },
        "usdt-bsc": {
          "address": "0x53653887c75d611A8EfbdA2c1FB97CFD17Bfff71",
          "cmcId": 825,
          "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
          "network": "binance-smart-chain-testnet"
        }
      },
      "amountReceived": [
        {
          "crypto": "BNB",
          "cryptoAmount": "0.000614952066849013",
          "localAmount": "0.2",
          "localCurrency": "USD",
          "transactionHash": "0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
        },
        {
          "crypto": "BNB",
          "cryptoAmount": "0.000614952066849113",
          "localAmount": "0.2",
          "localCurrency": "USD",
          "transactionHash": "0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
        }
      ],
      "code": "ML1A7PJ3F3PY",
      "context": "MULTIPLE",
      "createdAt": "2022-05-23T06:58:49.557Z",
      "currencyType": "LOCAL_CURRENCY",
      "customerEmail": "test@gmail.com",
      "customerName": "",
      "exchangeRateByUSD": "1",
      "exchangeRates": {
        "bnb-bsc-usd": "325.2286003765969",
        "busd-bsc-usd": "1.0005404341502755",
        "doge-bsc-usd": "0.08652585187256893",
        "eth-bsc-usd": "2050.8523351464096",
        "luna-bsc-usd": "0.00019356603824367347",
        "shib-bsc-usd": "0.000012191971099821102",
        "usdc-bsc-usd": "1.0003980008414488",
        "usdt-bsc-usd": "0.9991066318536912"
      },
      "expiredAt": "2022-05-24T06:58:49.544Z",
      "fizenpayFeePerc": "33",
      "flexiblePaymentSettings": {
        "overPaymentCurrency": "USD",
        "overPaymentThresholdValue": "2000",
        "type": "RELATIVE",
        "underPaymentCurrency": "USD",
        "underPaymentThresholdValue": "50"
      },
      "hostedUrl": "https://payment.fizen.io/commerce/charges/ML1A7PJ3F3PY",
      "id": "628b30a923ed950008b950a9",
      "localCurrency": "USD",
      "localExchangeRates": {
        "bnb-bsc-usd": "325.2286003765969",
        "busd-bsc-usd": "1.0005404341502755",
        "doge-bsc-usd": "0.08652585187256893",
        "eth-bsc-usd": "2050.8523351464096",
        "luna-bsc-usd": "0.00019356603824367347",
        "shib-bsc-usd": "0.000012191971099821102",
        "usdc-bsc-usd": "1.0003980008414488",
        "usdt-bsc-usd": "0.9991066318536912"
      },
      "localPrice": {
        "amount": "0.2",
        "currency": "USD"
      },
      "merchant": {
        "email": "test@gmail.com",
        "name": null
      },
      "merchantId": "628603dd75ebdf00083568dc",
      "name": "INVOICE - ML1A7PJ3F3PY",
      "payment": {
        
      },
      "pricing": {
        "bnb-bsc": {
          "amount": "0.000614952066849013",
          "cmcId": 1839,
          "currency": "BNB",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "614952066849013"
        },
        "busd-bsc": {
          "amount": "0.199891971552207288",
          "cmcId": 4687,
          "currency": "BUSD",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "199891971552207288"
        },
        "doge-bsc": {
          "amount": "2.311447916104313901",
          "cmcId": 74,
          "currency": "DOGE",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "2311447916104313901"
        },
        "eth-bsc": {
          "amount": "0.000097520429224721",
          "cmcId": 2396,
          "currency": "WETH",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "97520429224721"
        },
        "luna-bsc": {
          "amount": "1033.239104414727143858",
          "cmcId": 4172,
          "currency": "LUNA",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "1033239104414727143858"
        },
        "shib-bsc": {
          "amount": "16404.238360024876160848",
          "cmcId": 5994,
          "currency": "SHIB",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "16404238360024876160848"
        },
        "usdc-bsc": {
          "amount": "0.199920431500040177",
          "cmcId": 3408,
          "currency": "USDC",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "199920431500040177"
        },
        "usdt-bsc": {
          "amount": "0.200178833393318847",
          "cmcId": 825,
          "currency": "USDT",
          "decimal": 18,
          "network": "binance-smart-chain-testnet",
          "networkId": "97",
          "transferAmount": "200178833393318847"
        }
      },
      "pricingType": "fixed_price",
      "showLogo": true,
      "status": "UNRESOLVED",
      "supportEmail": "test@gmail.com",
      "timeline": [
        {
          "context": null,
          "status": "NEW",
          "time": "2022-05-23T06:58:49.557Z",
          "transactionDetail": null
        },
        {
          "context": null,
          "status": "PENDING",
          "time": "2022-05-23T07:01:41.758Z",
          "transactionDetail": null
        },
        {
          "context": null,
          "status": "COMPLETED",
          "time": "2022-05-23T07:01:51.660Z",
          "transactionDetail": "https://testnet.bscscan.com/tx/0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
        },
        {
          "context": null,
          "status": "PENDING",
          "time": "2022-05-23T07:02:18.664Z",
          "transactionDetail": null
        },
        {
          "context": "MULTIPLE",
          "status": "UNRESOLVED",
          "time": "2022-05-23T07:02:24.639Z",
          "transactionDetail": "https://testnet.bscscan.com/tx/0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
        }
      ],
      "transactionType": "INVOICE",
      "updatedAt": "2022-05-26T09:04:10.037Z"
    }
  ],
  "total": 1
}
```


# Charge details

Retrieves the details of a charge that has been previously created. Supply the unique charge code that was returned when the charge was created.

## Get charge details

<mark style="color:blue;">`GET`</mark> `/charges/code/{chargeCode}`

#### Path Parameters

| Name                                         | Type   | Description                                   |
| -------------------------------------------- | ------ | --------------------------------------------- |
| chargeCode<mark style="color:red;">\*</mark> | string | Charge code returned when a charge is created |

{% tabs %}
{% tab title="200: OK Charge information" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized Request is unauthorized" %}

```javascript
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

#### Example request

```
curl --location --request GET 'https://pay-api.fizen.io/api/integration/v1/charges/code/OST1FNY35QDL' \
--header 'X-FP-API-KEY: 601609e7-6ef9-4344-9b14-10f0d2116970'
```

#### Example response

```
{
  "statusCode": 200,
  "time": "2022-04-18T04:46:49.871Z",
  "data": {
    "addresses": {
      "bnb-bsc": {
        "address": "0x0000000000000000000000000000000000000000",
        "cmcId": 1839,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "busd-bsc": {
        "address": "0x718f381412b0ec0B9a6f69a77E3c7128C75E77B5",
        "cmcId": 4687,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "doge-bsc": {
        "address": "0x6aed42281c7bE19fa5f7a6ee5d873B85A5306bFe",
        "cmcId": 74,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "eth-bsc": {
        "address": "0x17fA95F49e69F82766C7930D4035b2973fbe95b8",
        "cmcId": 2396,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "luna-bsc": {
        "address": "0xc4E4FE5FcB38fE9D3BC327e384A57105955C9F9d",
        "cmcId": 4172,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "shib-bsc": {
        "address": "0x00A7D83B69C8c9223438F0Aca93453c89e0E66Ac",
        "cmcId": 5994,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdc-bsc": {
        "address": "0x3a943EFa37979952DE37168aE7D9B2E8723D9316",
        "cmcId": 3408,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdt-bsc": {
        "address": "0x53653887c75d611A8EfbdA2c1FB97CFD17Bfff71",
        "cmcId": 825,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      }
    },
    "amountReceived": [
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849013",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849113",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "code": "ML1A7PJ3F3PY",
    "context": "MULTIPLE",
    "createdAt": "2022-05-23T06:58:49.557Z",
    "currencyType": "LOCAL_CURRENCY",
    "customerEmail": "test@gmail.com",
    "customerName": "",
    "exchangeRateByUSD": "1",
    "exchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "expiredAt": "2022-05-24T06:58:49.544Z",
    "fizenpayFeePerc": "33",
    "flexiblePaymentSettings": {
      "overPaymentCurrency": "USD",
      "overPaymentThresholdValue": "2000",
      "type": "RELATIVE",
      "underPaymentCurrency": "USD",
      "underPaymentThresholdValue": "50"
    },
    "hostedUrl": "https://payment.fizen.io/commerce/charges/ML1A7PJ3F3PY",
    "id": "628b30a923ed950008b950a9",
    "localCurrency": "USD",
    "localExchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "localPrice": {
      "amount": "0.2",
      "currency": "USD"
    },
    "merchant": {
      "email": "test@gmail.com",
      "name": null
    },
    "merchantId": "628603dd75ebdf00083568dc",
    "name": "INVOICE - ML1A7PJ3F3PY",
    "payment": {
      
    },
    "pricing": {
      "bnb-bsc": {
        "amount": "0.000614952066849013",
        "cmcId": 1839,
        "currency": "BNB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "614952066849013"
      },
      "busd-bsc": {
        "amount": "0.199891971552207288",
        "cmcId": 4687,
        "currency": "BUSD",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199891971552207288"
      },
      "doge-bsc": {
        "amount": "2.311447916104313901",
        "cmcId": 74,
        "currency": "DOGE",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "2311447916104313901"
      },
      "eth-bsc": {
        "amount": "0.000097520429224721",
        "cmcId": 2396,
        "currency": "WETH",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "97520429224721"
      },
      "luna-bsc": {
        "amount": "1033.239104414727143858",
        "cmcId": 4172,
        "currency": "LUNA",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "1033239104414727143858"
      },
      "shib-bsc": {
        "amount": "16404.238360024876160848",
        "cmcId": 5994,
        "currency": "SHIB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "16404238360024876160848"
      },
      "usdc-bsc": {
        "amount": "0.199920431500040177",
        "cmcId": 3408,
        "currency": "USDC",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199920431500040177"
      },
      "usdt-bsc": {
        "amount": "0.200178833393318847",
        "cmcId": 825,
        "currency": "USDT",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "200178833393318847"
      }
    },
    "pricingType": "fixed_price",
    "showLogo": true,
    "status": "UNRESOLVED",
    "supportEmail": "test@gmail.com",
    "timeline": [
      {
        "context": null,
        "status": "NEW",
        "time": "2022-05-23T06:58:49.557Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:01:41.758Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "COMPLETED",
        "time": "2022-05-23T07:01:51.660Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:02:18.664Z",
        "transactionDetail": null
      },
      {
        "context": "MULTIPLE",
        "status": "UNRESOLVED",
        "time": "2022-05-23T07:02:24.639Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "transactionType": "INVOICE",
    "updatedAt": "2022-05-26T09:04:10.037Z"
  }
}
```


# Cancel a charge

Cancels a charge that has been previously created. Supply the unique charge code that was returned when the charge was created.

{% hint style="info" %}
**Note:** Only new charges can be successfully canceled. Once payment is detected, charge can no longer be canceled.
{% endhint %}

## Cancel a newly added charge

<mark style="color:green;">`POST`</mark> `/charges/{chargeCode}/cancel/`

#### Path Parameters

| Name                                         | Type   | Description |
| -------------------------------------------- | ------ | ----------- |
| chargeCode<mark style="color:red;">\*</mark> | string | Charge code |

{% tabs %}
{% tab title="201: Created Cancel successfully" %}

```javascript
{
    "statusCode": 201,
    "time": "2022-03-12T18:12:59.255Z",
    "total": 0
}
```

{% endtab %}

{% tab title="401: Unauthorized Request is unauthorized" %}

```javascript
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

#### Example request

```
curl --location --request POST 'https://pay-api.fizen.io/api/integration/v1/charges/code/OST1FNY35QDL/cancel' \
--header 'X-FP-API-KEY: -7abd3993-daf7-4322-84c6-c86e04b3d884'
```

#### Example response

```
{
    "statusCode": 201,
    "time": "2022-03-12T18:17:58.957Z",
    "total": 0
}
```


# Resolve a charge

Resolve a charge that has been previously marked as unresolved. Supply the unique charge code that was returned when the charge was created.

{% hint style="info" %}
**Note**: Only unresolved charges can be successfully resolved. For more on unresolved charges, check out at [Charge timeline](/reference/api-reference/charges#charge-resource)
{% endhint %}

## Resolve an unresolved charge

<mark style="color:green;">`POST`</mark> `/charges/{chargeCode}/resolve/`

#### Path Parameters

| Name                                         | Type   | Description |
| -------------------------------------------- | ------ | ----------- |
| chargeCode<mark style="color:red;">\*</mark> | string | Charge code |

{% tabs %}
{% tab title="201: Created Cancel successfully" %}

```javascript
{
    "statusCode": 201,
    "time": "2022-03-12T18:12:59.255Z",
    "total": 0
}
```

{% endtab %}

{% tab title="401: Unauthorized Request is unauthorized" %}

```javascript
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

#### Example request

```
curl --location --request POST 'https://pay-api.fizen.io/api/integration/v1/charges/code/OST1FNY35QDL/resolve' \
--header 'X-FP-API-KEY: 7abd3993-daf7-4322-84c6-c86e04b3d884'
```

#### Example response

```
{
    "statusCode": 201,
    "time": "2022-03-12T18:17:58.957Z",
    "total": 0
}
```


# Refund a charge

Marks a charge as Refunded (to payer). Supply the unique charge code that was returned when the charge was created.

## Marks a charge as Refuned

<mark style="color:green;">`POST`</mark> `/charges/{chargeCode}/refund/`

#### Path Parameters

| Name                                         | Type   | Description |
| -------------------------------------------- | ------ | ----------- |
| chargeCode<mark style="color:red;">\*</mark> | string | Charge code |

{% tabs %}
{% tab title="201: Created Cancel successfully" %}

```javascript
{
    "statusCode": 201,
    "time": "2022-03-12T18:12:59.255Z",
    "total": 0
}
```

{% endtab %}

{% tab title="401: Unauthorized Request is unauthorized" %}

```javascript
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

#### Example request

```
curl --location --request POST 'https://pay-api-sandbox.fizen.io/charges/code/OST1FNY35QDL/refund' \
--header 'X-FP-API-KEY: 7abd3993-daf7-4322-84c6-c86e04b3d884'
```

#### Example response

```
{
    "statusCode": 201,
    "time": "2022-03-12T18:17:58.957Z",
    "total": 0
}
```


# Utilities

All PUBLIC utilities


# Fiat to cryptocurrency

API tool for Fiat - Cryptocurrency conversion.

## Convert amount of local currency to amount of cryptocurrency

<mark style="color:blue;">`GET`</mark> `/api/web-app-public/v1/fiat-to-crypto`

Given a local currency amount and get list of converted amount of currencies.&#x20;

#### Query Parameters

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| localCurrency<mark style="color:red;">\*</mark> | string | Local currencies (e.g. USD) |
| amount<mark style="color:red;">\*</mark>        | number | Amount of local currency    |

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

```javascript
{
    "statusCode": 200,
    "time": "2022-03-25T08:30:18.898Z",
    "data": [
        {
            "amount": "99.83213408110765933476",
            "currency": "ZUSD"
        },
        {
            "amount": "0.0320582476405797326",
            "currency": "ETH"
        },
        {
            "amount": "100.03200298550301245994",
            "currency": "DAI"
        },
        {
            "amount": "0.24301542140633748644",
            "currency": "BNB"
        },
        {
            "amount": "4.80081695306537292273",
            "currency": "DOT"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Example request

```

curl --request GET 'https://pay-api.fizen.io/api/web-app-public/v1/fiat-to-crypto?localCurrency=VND&amount=2285000'

```

#### Example response

```
{
    "statusCode": 200,
    "time": "2022-03-30T09:42:33.218Z",
    "data": [
        {
            "amount": "100.01265294317923090184",
            "currency": "ZUSD",
            "rate": {
                "zusd-usd": 0.9998661369252846,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "0.02947918646313458955",
            "currency": "ETH",
            "rate": {
                "eth-usd": 3392.1989355778396,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "100.03576833430465586231",
            "currency": "DAI",
            "rate": {
                "dai-usd": 0.9996350965962809,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "83.72868243800639074246",
            "currency": "ADA",
            "rate": {
                "ada-usd": 1.1943250751137322,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "0.94300372741050238309",
            "currency": "LUNA",
            "rate": {
                "luna-usd": 106.043340058204,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "3656108.67217743673451114906",
            "currency": "SHIB",
            "rate": {
                "shib-usd": 0.000027351283538951845,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "698.87851728068146583566",
            "currency": "DOGE",
            "rate": {
                "doge-usd": 0.14308533238514815,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "115.96834015121021730291",
            "currency": "XRP",
            "rate": {
                "xrp-usd": 0.8622979755643441,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "0.22900566720994254838",
            "currency": "BNB",
            "rate": {
                "bnb-usd": 436.6672063633726,
                "vnd-usd": 22850.167962
            }
        },
        {
            "amount": "4.48951866655644138637",
            "currency": "DOT",
            "rate": {
                "dot-usd": 22.273939005280365,
                "vnd-usd": 22850.167962
            }
        }
    ]
}
```


# Webhooks

Webhooks make the integration with Fizen Pay easier by allowing you to subscribe to a set of charge events.

You can subscribe to the events by going to your [Settings page](https://merchant.fizen.io/dashboard/settings) and adding a new webhook subscription. When you create a new subscription, you can specify what events you would like to receive updates for. Below is the list of all available webhook events:

| EVENT             | DESCRIPTION                                                      | CHARGE STATUS |
| ----------------- | ---------------------------------------------------------------- | ------------- |
| charge.created    | A new charge is created                                          | NEW           |
| charge.canceled   | A new charge is canceled                                         | CANCELED      |
| charge.completed  | A payment is made for the charge and the conditions are met.     | COMPLETED     |
| charge.unresolved | A payment is made for the charge and the conditions are NOT met. | UNRESOLVED    |
| charge.resolved   | The UNRESOLVED charge is marked as resolved by the owner         | RESOLVED      |
| charge.refunded   | The charge is marked as refunded by the owner                    | REFUNDED      |

## Webhook details

The event topic, signature, and id are included in the headers of the response to the webhook endpoint. The headers are: *`x-fp-webhook-topic, x-fp-webhook-signature,`* and *`x-fp-webhook-id`* corresponding

```
Header:

x-fp-webhook-topic: "charge.completed"
x-fp-webhook-signature: "2acb37d82dd72e76ebfe08294c5e71a38918b49f76a9fd393b7aeb3d842fb895"
x-fp-webhook-id: "624c247239eba8000801eee3"
```

[The charge details](/reference/api-reference/charges) are included in the body of the response.&#x20;

### Event Payload example

```
{
  "charge": {
    "addresses": {
      "bnb-bsc": {
        "address": "0x0000000000000000000000000000000000000000",
        "cmcId": 1839,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "busd-bsc": {
        "address": "0x718f381412b0ec0B9a6f69a77E3c7128C75E77B5",
        "cmcId": 4687,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "doge-bsc": {
        "address": "0x6aed42281c7bE19fa5f7a6ee5d873B85A5306bFe",
        "cmcId": 74,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "eth-bsc": {
        "address": "0x17fA95F49e69F82766C7930D4035b2973fbe95b8",
        "cmcId": 2396,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "luna-bsc": {
        "address": "0xc4E4FE5FcB38fE9D3BC327e384A57105955C9F9d",
        "cmcId": 4172,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "shib-bsc": {
        "address": "0x00A7D83B69C8c9223438F0Aca93453c89e0E66Ac",
        "cmcId": 5994,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdc-bsc": {
        "address": "0x3a943EFa37979952DE37168aE7D9B2E8723D9316",
        "cmcId": 3408,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      },
      "usdt-bsc": {
        "address": "0x53653887c75d611A8EfbdA2c1FB97CFD17Bfff71",
        "cmcId": 825,
        "contract": "0x237B15c5ddA7809fC1Cb0d1a8bD31F5eA232Cc24",
        "network": "binance-smart-chain-testnet"
      }
    },
    "amountReceived": [
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849013",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "crypto": "BNB",
        "cryptoAmount": "0.000614952066849113",
        "localAmount": "0.2",
        "localCurrency": "USD",
        "transactionHash": "0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "code": "ML1A7PJ3F3PY",
    "context": "MULTIPLE",
    "createdAt": "2022-05-23T06:58:49.557Z",
    "currencyType": "LOCAL_CURRENCY",
    "customerEmail": "test@gmail.com",
    "customerName": "",
    "exchangeRateByUSD": "1",
    "exchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "expiredAt": "2022-05-24T06:58:49.544Z",
    "fizenpayFeePerc": "33",
    "flexiblePaymentSettings": {
      "overPaymentCurrency": "USD",
      "overPaymentThresholdValue": "2000",
      "type": "RELATIVE",
      "underPaymentCurrency": "USD",
      "underPaymentThresholdValue": "50"
    },
    "hostedUrl": "https://payment.fizen.io/commerce/charges/ML1A7PJ3F3PY",
    "id": "628b30a923ed950008b950a9",
    "localCurrency": "USD",
    "localExchangeRates": {
      "bnb-bsc-usd": "325.2286003765969",
      "busd-bsc-usd": "1.0005404341502755",
      "doge-bsc-usd": "0.08652585187256893",
      "eth-bsc-usd": "2050.8523351464096",
      "luna-bsc-usd": "0.00019356603824367347",
      "shib-bsc-usd": "0.000012191971099821102",
      "usdc-bsc-usd": "1.0003980008414488",
      "usdt-bsc-usd": "0.9991066318536912"
    },
    "localPrice": {
      "amount": "0.2",
      "currency": "USD"
    },
    "merchant": {
      "email": "test@gmail.com",
      "name": null
    },
    "merchantId": "628603dd75ebdf00083568dc",
    "name": "INVOICE - ML1A7PJ3F3PY",
    "payment": {
      
    },
    "pricing": {
      "bnb-bsc": {
        "amount": "0.000614952066849013",
        "cmcId": 1839,
        "currency": "BNB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "614952066849013"
      },
      "busd-bsc": {
        "amount": "0.199891971552207288",
        "cmcId": 4687,
        "currency": "BUSD",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199891971552207288"
      },
      "doge-bsc": {
        "amount": "2.311447916104313901",
        "cmcId": 74,
        "currency": "DOGE",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "2311447916104313901"
      },
      "eth-bsc": {
        "amount": "0.000097520429224721",
        "cmcId": 2396,
        "currency": "WETH",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "97520429224721"
      },
      "luna-bsc": {
        "amount": "1033.239104414727143858",
        "cmcId": 4172,
        "currency": "LUNA",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "1033239104414727143858"
      },
      "shib-bsc": {
        "amount": "16404.238360024876160848",
        "cmcId": 5994,
        "currency": "SHIB",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "16404238360024876160848"
      },
      "usdc-bsc": {
        "amount": "0.199920431500040177",
        "cmcId": 3408,
        "currency": "USDC",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "199920431500040177"
      },
      "usdt-bsc": {
        "amount": "0.200178833393318847",
        "cmcId": 825,
        "currency": "USDT",
        "decimal": 18,
        "network": "binance-smart-chain-testnet",
        "networkId": "97",
        "transferAmount": "200178833393318847"
      }
    },
    "pricingType": "fixed_price",
    "showLogo": true,
    "status": "UNRESOLVED",
    "supportEmail": "test@gmail.com",
    "timeline": [
      {
        "context": null,
        "status": "NEW",
        "time": "2022-05-23T06:58:49.557Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:01:41.758Z",
        "transactionDetail": null
      },
      {
        "context": null,
        "status": "COMPLETED",
        "time": "2022-05-23T07:01:51.660Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x08c60c38a600e63905b19a2775b1d662a846c06f726bfeb5c0f419a2c58422bc"
      },
      {
        "context": null,
        "status": "PENDING",
        "time": "2022-05-23T07:02:18.664Z",
        "transactionDetail": null
      },
      {
        "context": "MULTIPLE",
        "status": "UNRESOLVED",
        "time": "2022-05-23T07:02:24.639Z",
        "transactionDetail": "https://testnet.bscscan.com/tx/0x1ef2640f920c46ee02b82d079e9a83a1cc602063325609c7b66f9c0a920faaea"
      }
    ],
    "transactionType": "INVOICE",
    "updatedAt": "2022-05-26T09:04:10.037Z"
  }
}
```

## Edit webhook

You can specify the topics that you want to receive and test the topics for the integration by clicking on Edit button beside the Webhook endpoint in the Setting page.

![](https://2424647213-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff67IkjlWYtXbtgpmwU0A%2Fuploads%2FGaioi4wqnmJW3N3NJKEa%2FScreen%20Shot%202022-04-18%20at%2017.20.15.png?alt=media\&token=ba5deb96-7720-468a-8334-d08f4f3595b1)

## Securing webhooks <a href="#securing-webhooks" id="securing-webhooks"></a>

\
Every webhook request includes an `x-fp-webhook-signature` header. This header contains the [SHA256 HMAC](https://www.freeformatter.com/hmac-generator.html) signature of the raw request payload, computed using your webhook shared secret as the key. You can obtain your shared webhook secret from your [Settings Page](https://merchant.fizen.io/dashboard/settings) . Always make sure that you verify the webhook signature before acting on it inside your system.

![](https://2424647213-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff67IkjlWYtXbtgpmwU0A%2Fuploads%2FBCQ2qHkWFsvhsiGaXl3x%2FScreen%20Shot%202022-04-18%20at%2017.17.18.png?alt=media\&token=5fe603c5-babb-4d96-8b27-8f46dd95d9e0)

<br>


# Sandbox

Sandbox Environment


# Production

Production environment