Create Invoice (Shop)

you can create invoice

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

POST https://api.payhubix.com/v1/payment/shops/019242e7-d18f-788f-813e-a2c72177e172/invoices/

Note: you must insert shop_id in path param request.

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

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

callback_url

string

A URL where payment status notifications will be sent (maximum 200 characters).

No

An example of request body:

{
  "currency_amount": 1,
  "currency_symbol": "USD",
  "customer_email": "customer@example.com",
  "time_for_payment": "02:00",
  "currencies": [1],
  "order_id": "#12325425",
  "order_description": "macbook air m3",
  "callback_url": "https://example.com/callback"
}

Note: thecurrenciesfield should be IDs of Supported Currencies 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.

callback_url

string

URL to which the payment result will be sent.

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:

{
    "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": "customer@example.com",
        "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": "019242e7-d18f-788f-813e-a2c72177e172",
            "transfer_fee_by": "Customer",
            "service_fee_by": "Merchant",
            "logo_url": null
        },
        "currencies": [
            {
                "currency_id": 1,
                "currency_name": "Tron",
                "currency_status": "Enable",
                "currency_symbol": "TRX",
                "currency_type": "Crypto",
                "currency_icon_url": "https://payhubixstorage.darkube.app/payhubix/coins_icons/TRX_logo.jpg",
                "slug": "",
                "network_id": 1,
                "network_symbol": "TRX",
                "network_status": "Enable",
                "network_name": "Tron",
                "network_icon_url": "https://payhubixstorage.darkube.app/payhubix/network_icons/TRX_logo.jpg",
                "network_scanner_url": "",
                "fee_withdraw": 0,
                "fee_payment": 0,
                "minimum_withdraw": 0,
                "precision": 0,
                "withdrawable": false,
                "paymentable": false,
                "status": "",
                "is_native": false
            }
        ],
        "payments": null,
        "selected_payment": null,
        "callback_url": "https://example.com/callback"
    }
}

Example codes:

curl -X POST https://api.payhubix.com/v1/payment/shops/019242e7-d18f-788f-813e-a2c72177e172/invoices/ \
-H "Content-Type: application/json" \
-H "X-Api-key: YOUR_API_KEY" \
-d '{
  "currency_amount": 1,
  "currency_symbol": "USD",
  "customer_email": "customer@example.com",
  "time_for_payment": "02:00",
  "currencies": [1],
  "order_id": "#12325425",
  "order_description": "macbook air m3",
  "callback_url": "https://example.com/callback"
}'

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

Last updated