Create Invoice

Create Invoice API Endpoint

POST https://payid19.com/api/v1/create_invoice

Requests

Parameters to be sent to the service are as follows:

Input Name Type Required Description
public_key String Yes your public key
private_key String Yes your private key
test Integer No, default null if the value is 1 it is a test invoice, if the value is null it is a live invoice
email String No Email or buyer.
merchant_id String No ID of merchant.
order_id String No ID of order.
customer_id Integer No ID of buyer.
price_amount Decimal Yes price of product
price_currency String No, default USD Currency (default: USD). Alternatively, you can set USD, EUR, GBP and other currencys, show all supported currencies
add_fee_to_price Integer no, default null if the value is 1 add fee to price

*when used, it increases erroneous transfers and decreases sales.

title String no title of invoice
description String no description of invoice
banned_coins NEW JSON no Coins that you do not want to use to receive payments.

example: ["BTC","ETH","USDT-ERC20"]

*Bitcoin, Ethereum and USDT-ERC20 addresses are not give to your customers.

example 2: ["USDT","BNB"]

*USDT (all network)and Bnb addresses are not give to your customers.

callback_url String no Merchant callback URL for payment result notification if payment success

result values is :private_key(for compare yours), id, email, merchant_id, order_id, customer_id, price_amount, price_currency, amount, amount_currency, add_fee_to_price, title, description, ref_url, cancel_url, success_url, callback_url, ip, test, created_at, expiration_date

Tries 3 times, once every 5 minutes, until it reaches HTTP code 200

It requires a public domain(not ip address and localhost), if you dont have one yet you can use ngrok or webhook.site for testing.

cancel_url String no cancel url
success_url String no success url
expiration_date Integer no, default 12, max 12 expiration date hourly
margin_ratio Integer no We've seen people send a lot of underpaid amounts (usually under 1 USDd) as getting paid in crypto is a new payment method. The amount you write in this field is ignored and the payment is considered successful, even if it is missing. for example: if you type 1 (1 USDT) here and generate an invoice to receive payment of 5 USDT, the payment will be considered successful even if you receive 4 USDT, but your customer will be considered unsuccessful if the payment is 3.9 USDT (If you typed 2, 3.9 USDT would also be considered successful.)
white_label NEW Integer no To create an invoice with your own logo, your own style and brand, send it as 1 and receive a list of coins you can receive payment from as JSON. For detailed information and More

Response

Parameters to be returned from the service are as follows:

Input Name Type Description
status String success or error
message String error message if status is error or invoice url if status is success

Sample Codes


Create Invoice Sample

                        
<?php
$url = 'https://payid19.com/api/v1/create_invoice';  // The API endpoint URL for creating an invoice
                            
$post = [  
    'public_key' => 'yourpublickey',  // Your public API key to authenticate the request
    'private_key' => 'yourprivatekey',  // Your private API key for secure authentication
    'email' => '[email protected]',  // The email associated with the customer
    'price_amount' => 725,  // The amount for the invoice (in USD)
    'price_currency' => 'USD',  // Currency in which the price is specified (USD in this case)
    'merchant_id' => 5,  // Merchant's unique ID in the system
    'order_id' => 11,  // Unique ID for the order being processed
    'customer_id' => 12,  // Unique ID for the customer placing the order
    'test' => 1,  // Test mode flag (1 means this is a test request)
    'title' => 'title',  // Title of the invoice
    'description' => 'description',  // Description of the invoice
    'add_fee_to_price' => 1,  // If true (1), any fees will be added to the total price
    //'banned_coins' => json_encode(array("BTC", "ETH", "USDT-ERC20")),  // Optional: Specify banned coins for this payment
    'cancel_url' => 'https://yourcancelurl',  // URL to redirect the user if they cancel the payment
    'success_url' => 'https://yoursuccessurl',  // URL to redirect the user upon successful payment
    'callback_url' => 'http://yourcallbackurl',  // URL where the payment result will be sent via webhook
    'expiration_date' => 12,  // Time in hours when the invoice will expire
    'margin_ratio' => 1.5  // Optional margin ratio for price adjustments
    //'white_label' => 1  // Optional flag for white-labeling the invoice
]; 
                            
$ch = curl_init();  // Initialize a new cURL session
curl_setopt($ch, CURLOPT_URL, $url);  // Set the API URL for the request
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);  // Enable SSL certificate verification for security
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // Return the response instead of outputting it
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post));  // Attach the data as a URL-encoded POST request
$result = curl_exec($ch);  // Execute the cURL request and store the result
curl_close($ch);  // Close the cURL session to free up resources
                            
if (json_decode($result)->status == 'error') {  // If the API response status is 'error'
    // Handle error
    echo json_decode($result)->message[0];  // Output the first error message
} else {  
    // Handle success
    echo json_decode($result)->message;  // Output the success message
}


                                
                            
                                  
    const axios = require('axios'); // Import axios for making HTTP requests

    // Data to be sent in the POST request (required parameters for creating an invoice)
    const postData = {
        public_key: 'yourpublickey', // Public key to access the API
        private_key: 'yourprivatekey', // Private key to access the API
        email: '[email protected]', // Customer's email address associated with the invoice
        price_amount: 725, // The amount of the invoice (725 USD)
        price_currency: 'USD', // The currency of the invoice (USD)
        merchant_id: 5, // Merchant's unique ID
        order_id: 11, // Order ID for tracking the order
        customer_id: 12, // Customer's unique ID
        test: 1, // Test mode flag (1 for yes, 0 for no)
        title: 'title', // Title of the invoice
        description: 'description', // Description of the invoice
        add_fee_to_price: 1, // Flag indicating whether to add processing fees to the price
        // banned_coins: JSON.stringify(["BTC", "ETH", "USDT-ERC20"]), // (Optional) Array of banned cryptocurrencies
        cancel_url: 'https://yourcancelurl', // URL to redirect the user if payment is canceled
        success_url: 'https://yoursuccessurl', // URL to redirect the user after successful payment
        callback_url: 'http://yourcallbackurl', // URL for sending payment result updates (webhook)
        expiration_date: 12, // Invoice expiration time (in hours)
        margin_ratio: 1.5 // The margin ratio to apply on the invoice price
        // white_label: 1 // (Optional) White-label option flag
    };

    // Make the POST request using axios
    axios.post('https://payid19.com/api/v1/create_invoice', postData)
    .then(response => {
        const result = response.data; // Get the response data
        if (result.status === 'error') {
            // If there's an error in the response
            console.log(result.message[0]); // Log the error message
        } else {
            // If the request is successful
            console.log(result.message); // Log the success message
        }
    })
    .catch(error => {
        // Handle any errors that occur during the request
        console.error(`Error: ${error.message}`);
    });
                          
                      
                        
import requests  # Import the requests library for making HTTP requests

# Data to be sent in the POST request (required parameters for creating an invoice)
post_data = {
    'public_key': 'yourpublickey',  # Public key to access the API
    'private_key': 'yourprivatekey',  # Private key to access the API
    'email': '[email protected]',  # Customer's email address associated with the invoice
    'price_amount': 725,  # The amount of the invoice (725 USD)
    'price_currency': 'USD',  # The currency of the invoice (USD)
    'merchant_id': 5,  # Merchant's unique ID
    'order_id': 11,  # Order ID for tracking the order
    'customer_id': 12,  # Customer's unique ID
    'test': 1,  # Test mode flag (1 for yes, 0 for no)
    'title': 'title',  # Title of the invoice
    'description': 'description',  # Description of the invoice
    'add_fee_to_price': 1,  # Flag indicating whether to add processing fees to the price
    'cancel_url': 'https://yourcancelurl',  # URL to redirect the user if payment is canceled
    'success_url': 'https://yoursuccessurl',  # URL to redirect the user after successful payment
    'callback_url': 'https://yourcallbackurl',  # URL for sending payment result updates (webhook)
    'expiration_date': 12,  # Invoice expiration time (in hours)
    'margin_ratio': 1.5  # The margin ratio to apply on the invoice
}

# Make the POST request using the requests library
try:
    response = requests.post('https://payid19.com/api/v1/create_invoice', json=post_data)  # Send POST request with JSON data

    # Check if the response status code indicates an error
    if response.status_code == 422:
        print('422 Error:', response.json())  # Log the response data for 422 error
    else:
        result = response.json()  # Get the response data in JSON format
        if result['status'] == 'error':
            print(result['message'][0])  # Log the error message
        else:
            print(result['message'])  # Log the success message

except requests.exceptions.RequestException as e:
    # Handle any exceptions that occur during the request
    print(f'Error: {e}')  # Print the error message


Catch Callback Sample

                    
<?php
$data = json_decode(file_get_contents('php://input')); //catch request data
                        
if($data->privatekey!="your privatekey"){ //compare private keys 
    die;
}
....and the other things

                    
                
                        
const express = require('express'); // Import the Express framework
const bodyParser = require('body-parser'); // Import body-parser to handle JSON data

const app = express(); // Create an Express application
const PORT = process.env.PORT || 3000; // Set the port for the application

app.use(bodyParser.json()); // Use body-parser middleware to parse JSON data

app.post('/your-endpoint', (req, res) => { // Define a POST route
    const data = req.body; // Catch request data

    if (data.privatekey !== "your privatekey") { // Compare private keys
        return res.status(403).send('Forbidden'); // Return 403 Forbidden if the key is invalid
    }

    // Continue with further processing if the key is valid
    res.send('Private key is valid!'); // Send a success response
});

app.listen(PORT, () => { // Start the server
    console.log(`Server is running on port ${PORT}`); // Log the server status
});
            
        
            
from flask import Flask, request, jsonify  # Import Flask and necessary modules

app = Flask(__name__)  # Create a Flask application

@app.route('/your-endpoint', methods=['POST'])  # Define a POST route
def handle_request():
    data = request.get_json()  # Catch request data

    # Check if the private key is valid
    if data.get('privatekey') != "your privatekey":  # Compare private keys
        return jsonify({'error': 'Invalid private key'}), 403  # Return error response

    # Continue with other processing...
    return jsonify({'message': 'Private key is valid!'}), 200  # Return success response

if __name__ == '__main__':
    app.run(port=5000)  # Start the Flask server on port 5000


Scenario

  1. Customer Initiates the Payment:
    The customer selects an item or service from your website and proceeds to the checkout page. On the checkout page, they choose to pay using cryptocurrency via Payid19 and are redirected to the Payid19 payment page.
  2. Payment is Processed by Payid19:
    Payid19 receives the payment request, processes the cryptocurrency transaction, and monitors the blockchain confirmations. Once the required confirmations are met, Payid19 marks the payment as successful.
  3. Webhook is Triggered:
    Payid19 triggers a webhook to the callback URL you provided. The webhook contains payment details, such as the transaction ID, payment status (successful), cryptocurrency used, amount paid, and order information.
  4. Your Server Receives the Webhook:
    Your server processes the webhook data, confirms that the payment was successful, and updates the order status to "paid" in your database.
  5. Order Confirmation and Additional Actions:
    Your server may send a confirmation email to the customer and update your inventory. You can also start order fulfillment, such as shipping or granting access to digital products/services.
  6. Server Responds to Payid19:
    Your server sends a 200 OK response back to Payid19, confirming that the webhook was processed. This ensures Payid19 does not resend the webhook.
  7. Customer Receives Confirmation:
    The customer receives an email confirming their payment and order status. They may also be redirected to a success page on your website.
  8. Final Order Processing:
    You can now proceed with shipping the product, or granting immediate access to digital goods or services based on the successful payment.
Are you a developer? Please look at our New Developer Referral Program , Earn %50.