Create Invoice

you can create invoice

Note: your API key must have the "Invoices" permission.

The Create Invoice endpoint allows you to generate a new invoice for your customers. You can specify the amount, currency, and other optional details to customize the invoice according to your needs.

POST https://api.payhubix.com/v1/invoices/

Request Header:

Name	Type	Description
X-Api-Key*	string	Your API key for authentication and authorization.

Request Body:

Name	Type	Description	Required
currency_amount*	float	The amount of the invoice. This must be greater than 0, This amount must be related to the currency_symbol.	Yes
currency_symbol*	string	The symbol of the Fiat (e.g., USD, EUR).	Yes
customer_email	string	The email of the customer. Must be a valid email format (maximum 200 characters).	No
time_for_payment*	string	The time allowed for payment in the format HH:MM (e.g., 2:20 for 2 hours and 20 minutes).	Yes
currencies*	array	An array of integers representing crypto currency types.	Yes
shop_id	string	The unique ID of your shop.	No
order_id	string	A unique identifier for the order (maximum 100 characters).	No
order_description	string	A brief description of the order (maximum 200 characters).	No
redirect_url	string	The URL to which the user is redirected after completing the invoice payment, canceling it, or when the invoice expires.	No

An example of request body:

{
  "currency_amount": 1,
  "currency_symbol": "USD",
  "customer_email": "[e-mail]",
  "time_for_payment": "02:00",
  "currencies": [1],
  "shop_id": "absc-123456-qwerty...",
  "order_id": "#12325425",
  "order_description": "macbook air m3",
  "callback_url": "https://example.com/callback"
}

Note: thecurrenciesfield should be IDs of Supported Cryptos and the currency_symbolfield should be IDs of Supported Fiat.

Response

Name	Type	Description
invoice_url*	string	URL to view the invoice.
currency_amount*	float	The original amount for the invoice.
remaining_currency_amount*	float	The remaining unpaid amount.
currency_symbol*	string	The symbol of the currency used (USD, e.g.).
link*	string	Unique identifier for the invoice.
transfer_fee_by*	string	Specifies who covers the transfer fee. Either Customer or Merchant.
service_fee_by*	string	Specifies who covers the service fee. Either Customer or Merchant.
service_fee_percent*	float	The percentage of the service fee.
status*	string	The current status of the invoice (Created, Pending, Paid,Canceled,Partially, PartiallyExpired,Expired).
customer_email	string	Email address of the customer (nullable).
manual_customer_email	string	Manually provided customer email (nullable).
created_at*	string	Timestamp of when the invoice was created.
expire_at*	string	Timestamp of when the invoice will expire.
pure_expire_time*	string	Time duration in HH:MM before the invoice expires.
order_id	string	Unique identifier for the order (nullable).
order_description	string	Description of the order (nullable).
shop.name*	string	The name of the shop that issued the invoice.
shop.website	string	The website of the shop (nullable).
shop.shop_id*	string	Unique identifier for the shop.
shop.transfer_fee_by*	string	Who covers the transfer fee for the shop. Either Customer or Merchant.
shop.service_fee_by*	string	Who covers the service fee for the shop. Either Customer or Merchant.
shop.logo_url	string	URL to the logo of the shop (nullable).
currencies[].currency_id*	uint	Unique identifier for the currency.
currencies[].currency_name*	string	Name of the currency (e.g., Bitcoin, Ethereum).
currencies[].currency_status*	string	Status of the currency (Enable or Disable).
currencies[].currency_symbol*	string	The symbol of the currency (e.g., BTC, ETH).
currencies[].currency_type*	string	Type of currency (Fiat or Crypto).
currencies[].currency_icon_url*	string	URL to the currency's icon.
currencies[].network_id*	uint	Unique identifier for the currency network (e.g., Ethereum, Tron).
currencies[].network_symbol*	string	Symbol of the network.
currencies[].network_status*	string	Status of the network (Enable or Disable).
currencies[].network_name*	string	Name of the network (e.g., Ethereum, Tron).
currencies[].network_icon_url*	string	URL to the network's icon.
currencies[].fee_withdraw*	float	Fee for withdrawal in this currency.
currencies[].fee_payment*	float	Fee for payment in this currency.
currencies[].minimum_withdraw*	float	Minimum amount required to withdraw in this currency.
currencies[].precision*	int	Decimal precision for the currency.
currencies[].withdrawable*	bool	Indicates if the currency is withdrawable.
currencies[].paymentable*	bool	Indicates if the currency can be used for payments.
payments	array	Payment details, if available.
selected_payment	object	Details of the selected payment option.
redirect_url	string	The URL to which the user is redirected after completing the invoice payment, canceling it, or when the invoice expires.
payments[].currency_amount*	float	The original currency amount for the payment.
payments[].remaining_currency_amount*	float	The remaining amount of the currency to be paid.
payments[].transfer_fee	float	Transfer fee, if applicable (nullable).
payments[].service_fee	float	Service fee, if applicable (nullable).
payments[].ratio	float	Exchange rate ratio, if applicable (nullable).
payments[].crypto_amount	float	Original amount of cryptocurrency to be paid.
payments[].final_crypto_amount	float	Final calculated amount of cryptocurrency required.
payments[].received_crypto_amount	float	Amount of cryptocurrency received.
payments[].remaining_crypto_amount	float	Remaining amount of cryptocurrency to be received.
payments[].memo	string	Memo or description for the payment (nullable).
payments[].address	string	Address to which the cryptocurrency should be sent (nullable).
payments[].status*	string	Current status of the payment (Created, Pending, etc.).
payments[].created_at*	string	Timestamp when the payment was created.
payments[].expire_time*	string	Expiration time for the payment.
payments[].pure_expire_time*	string	Expiration duration in HH:MM.
payments[].selected_currency	object	Details of the selected currency.
payments[].transactions	array	List of related payment transactions.
payments[].transactions[].tx_hash*	string	Hash of the transaction on the blockchain.
payments[].transactions[].scanner_link*	string	URL to the transaction on the blockchain explorer (nullable).

Node: The current status of the invoice. Possible values are: Created, Pending, Paid,Canceled,Partially, PartiallyExpired,Expired

Note: All times are UTC.

An example of response:

200: OK

{
    "error": false,
    "number": 0,
    "message": {
        "invoice_url": "https://payhubix.com/pay/INV-LUE9K66Q",
        "currency_amount": 1,
        "remaining_currency_amount": 1,
        "currency_symbol": "USD",
        "link": "INV-LUE9K66Q",
        "transfer_fee_by": "Customer",
        "service_fee_by": "Merchant",
        "service_fee_percent": 1,
        "status": "Created",
        "customer_email": "[e-mail]",
        "manual_customer_email": null,
        "created_at": "2024-09-30 20:58:22.354937 +0000 UTC",
        "expire_at": "2024-09-30 22:58:22.354377 +0000 UTC",
        "pure_expire_time": "02:00",
        "order_id": "#12325425",
        "order_description": "macbook air m3",
        "shop": {
            "name": "Amazon",
            "website": "https://www.amazon.com/",
            "shop_id": "absc-123456-qwerty...",
            "transfer_fee_by": "Customer",
            "service_fee_by": "Merchant",
            "logo_url": null
        },
        "currencies": [
             {
                "currency_id": 115,
                "currency_name": "USDC",
                "currency_symbol": "USDC",
                "currency_type": "Crypto",
                "precision": 6,
                "withdrawable": true,
                "paymentable": false,
                "depositable": false,
                "currency_icon_url": "https://payhubixstorage.darkube.app/payhubix/coins_icons/USDC_logo.jpg",
                "network_id": 8,
                "network_symbol": "ARBITRUM",
                "network_status": "Disable",
                "network_name": "Arbitrum",
                "network_icon_url": "https://payhubixstorage.darkube.app/payhubix/network_icons/arbitrum_logo.jpg",
                "network_scanner_url": "https://arbiscan.io/tx/",
                "fee_withdraw": 0.6,
                "fee_payment": 0.5,
                "minimum_withdraw": 2,
                "minimum_deposit": 2,
                "is_native": false,
                "tag": "stable-coins",
                "supports_memo": false
             }
        ],
        "payments": null,
        "selected_payment": null,
        "redirect_url": "https://example.com/callback"
    }
}

401: Unauthorized

{
    "error": true,
    "number": 401,
    "message": "Unauthorized access to api"
}

403: Forbidden

{
    "error": true,
    "number": 403,
    "message": "You don't have permission to access this resource."
}

500: Something went wrong

{
    "error": true,
    "number": 500,
    "message": "Oops! Something went wrong on our end."
}

Example codes:

cURL

curl -X POST https://api.payhubix.com/v1/invoices/ \
-H "Content-Type: application/json" \
-H "X-Api-key: YOUR_API_KEY" \
-d '{
  "currency_amount": 1,
  "currency_symbol": "USD",
  "customer_email": "[e-mail]",
  "time_for_payment": "02:00",
  "currencies": [1],
  "shop_id": "absc-123456-qwerty...",
  "order_id": "#12325425",
  "order_description": "macbook air m3",
  "redirect_url": "https://example.com/callback"
}'

Python

import requests

headers = {
    'Content-Type': 'application/json',
    'X-Api-key': 'YOUR_API_KEY',
}

json_data = {
    'currency_amount': 1,
    'currency_symbol': 'USD',
    'customer_email': '[e-mail]',
    'time_for_payment': '02:00',
    'currencies': [
        1,
    ],
    'shop_id': 'absc-123456-qwerty...',
    'order_id': '#12325425',
    'order_description': 'macbook air m3',
    'redirect_url': 'https://example.com/callback',
}

response = requests.post('https://api.payhubix.com/v1/invoices/', headers=headers, json=json_data)

Node.js

import axios from 'axios';

const response = await axios.post(
  'https://api.payhubix.com/v1/invoices/',
  {
    'currency_amount': 1,
    'currency_symbol': 'USD',
    'customer_email': '[e-mail]',
    'time_for_payment': '02:00',
    'currencies': [
      1
    ],
    'shop_id': 'absc-123456-qwerty...',
    'order_id': '#12325425',
    'order_description': 'macbook air m3',
    'redirect_url': 'https://example.com/callback'
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-Api-key': 'YOUR_API_KEY'
    }
  }
);

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://api.payhubix.com/v1/invoices/', [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-Api-key'    => 'YOUR_API_KEY'
    ],
    'json' => [
        'currency_amount' => 1,
        'currency_symbol' => 'USD',
        'customer_email' => '[e-mail]',
        'time_for_payment' => '02:00',
        'currencies' => [
            1
        ],
        'shop_id': 'absc-123456-qwerty...',
        'order_id' => '#12325425',
        'order_description' => 'macbook air m3',
        'redirect_url' => 'https://example.com/callback'
    ]
]);

Golang

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"strings"
)

func main() {
	client := &http.Client{}
	var data = strings.NewReader(`{
  "currency_amount": 1,
  "currency_symbol": "USD",
  "customer_email": "[e-mail]",
  "time_for_payment": "02:00",
  "currencies": [1],
  "shop_id": "absc-123456-qwerty...",
  "order_id": "#12325425",
  "order_description": "macbook air m3",
  "redirect_url": "https://example.com/callback"
}`)
	req, err := http.NewRequest("POST", "https://api.payhubix.com/v1/invoices/", data)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-key", "YOUR_API_KEY")
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	bodyText, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", bodyText)
}

Note: Please make sure to replace YOUR_API_KEY in the code snippets with your actual merchant API key