📃Invoices

Introduction

Invoices are a powerful tool for businesses to bill customers for goods or services. Sonic Payment Gateway provides a simple and secure way to create, manage, and track invoices. In this section, we will cover how to create, retrieve, update, and delete invoices using our API.

Create an invoice

To create an invoice, you will need to make a POST request to the /invoices endpoint. You can include the following parameters in the request body:

Parameter	Type	Description
amount	integer	The total amount of the invoice in the smallest denomination of the currency (e.g. cents for USD)
currency	string	The ISO 4217 currency code
customer_email	string	The email address of the customer
customer_name	string	The name of the customer
line_items	array	An array of line items for the invoice. Each line item should include the following parameters: name, amount, and quantity.
due_date	string (YYYY-MM-DD)	The date the invoice is due in ISO 8601 format
metadata	object	Additional metadata to associate with the invoice

Creating an invoice

POST https://api.sonicpay.org/invoices

Request Body

Name	Type	Description
amount*	10000
currency*	USDT
customer_email*	[e-mail]
customer_name*	John Doe
line_items*	"name": "Product 1", "amount": 5000, "quantity": 2
due_date*	2022-05-30
metadata*	"order_id": "12345"

201: Created Invoice Created

{
"id": "f6a2f7f-3400-4f47-8973-fa8bb2f5d483",
"reference": "INV-12345",
"amount": 10000,
"currency": "USDT",
"status": "Paid",
"metadata": {
"customer_name": "John Doe"
},
"createdAt": "2022-07-01T12:00:00.000Z",
"updatedAt": "2022-07-01T12:00:00.000Z"
}

Here is an example curl request for creating an invoice:

curl --location --request POST 'https://api.sonicpay.org/invoices' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 10000,
    "currency": "USDT",
    "customer_email": "[e-mail]",
    "customer_name": "John Doe",
    "line_items": [
        {
            "name": "Product 1",
            "amount": 5000,
            "quantity": 2
        },
        {
            "name": "Product 2",
            "amount": 2500,
            "quantity": 1
        }
    ],
    "due_date": "2022-05-30",
    "metadata": {
        "order_id": "12345"
    }
}'

Get an invoice

To retrieve an invoice, you will need to make a GET request to the /invoices/{invoice_id} endpoint, where {invoice_id} is the ID of the invoice you wish to retrieve.

GET https://api.sonicpay.org/invoices/invoice_id

Path Parameters

Name	Type	Description
invoice_id*	32322

Headers

Name	Type	Description
Content-Type*	application/json
Authorization: Bearer*	your_api_key

200: OK

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "5f0efa72-f2b9-4b5d-9c1b-8f8f1e0b0c2d",
    "name": "Invoice 1",
    "description": "This is an invoice for product 1",
    "amount": 100,
    "currency": "Doge",
    "created_at": "2022-01-19T00:00:00.000Z",
    "updated_at": "2022-01-19T00:00:00.000Z",
    "status": "paid"
}

Update an invoice

To update an invoice, you will need to make a PUT request to the /invoices/{invoice_id} endpoint, where {invoice_id} is the ID of the invoice you wish to update. You can include any of the parameters from the create invoice request in the request body.

PATCH PATCH https://api.sonicpay.org/invoices/{invoice_id}

Path Parameters

Name	Type	Description
invoice_id*	23424
Authorization: Bearer*	your_api_key
Content-Type*	application/json

Request Body

Name	Type	Description
description*	New Description
amount*	100
currency*	Doge
shipping*	Pending
metadata*	"order_id": "12345"

200: OK

{
    "id": "invoice_id",
    "description": "New Description",
    "amount": 15.5,
    "currency": "USD",
    "status": "unpaid",
    "created_at": "2022-09-05T16:35:22.986Z",
    "updated_at": "2022-09-05T16:35:22.986Z",
    "shipping": {
      "amount": 2,
      "address": {
        "name": "John Smith",
        "address1": "123 Main St",
        "address2": "Apt 456",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      }
    },
    "metadata": {
      "order_id": "12345"
    }
}

204: No Content

{
    // Response
}

This endpoint is used to update an existing invoice. The following parameters can be updated:

Parameter	Type	Description
description	string	A description of the invoice
amount	number	The total amount of the invoice
currency	string	The currency of the invoice (e.g. USD, EUR, etc.)
shipping	object	An object containing information about the shipping costs associated with the invoice. Can contain the following properties:<br>- amount: The amount of the shipping costs<br>- address: An object containing information about the shipping address. Can contain the following properties:<br> - name: The name of the recipient<br> - address1: The first line of the shipping address<br> - address2: The second line of the shipping address (optional)<br> - city: The city of the shipping address<br> - state: The state of the shipping address<br> - country: The country of the shipping address<br> - postal_code: The postal code of the shipping address
metadata	object	An object containing additional information about the invoice

Example Request

curl -X PATCH https://api.sonicpay.org/invoices/invoice_id \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "description": "New Description",
    "amount": 15.5,
    "shipping": {
      "amount": 2,
      "address": {
        "name": "John Smith",
        "address1": "123 Main St",
        "address2": "Apt 456",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      }
    },
    "metadata": {
      "order_id": "12345"
    }
  }'

Example Response:

{
    "id": "invoice_id",
    "description": "New Description",
    "amount": 15.5,
    "currency": "USD",
    "status": "unpaid",
    "created_at": "2022-09-05T16:35:22.986Z",
    "updated_at": "2022-09-05T16:35:22.986Z",
    "shipping": {
      "amount": 2,
      "address": {
        "name": "John Smith",
        "address1": "123 Main St",
        "address2": "Apt 456",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      }
    },
    "metadata": {
      "order_id": "12345"
    }
}

Get all Invoices

Make a GET request to the /invoices endpoint. This will return a list of all invoices associated with your account, including their ID, status, and amount.

GET https://api.sonicpay.org/v1/invoices

Headers

Name	Type	Description
Authorization: Bearer	YOUR_API_KEY

200: OK

HTTP/1.1 200 OK
Content-Type: application/json
{
    "meta": {
        "total_count": 10,
        "page": 1,
        "per_page": 20
    },
    "data": [
        {
            "id": "5f0efa72-f2b9-4b5d-9c1b-8f8f1e0b0c2d",
            "name": "Invoice 1",
            "description": "This is an invoice for product 1",
            "amount": 100,
            "currency": "USDC",
            "created_at": "2022-01-19T00:00:00.000Z",
            "updated_at": "2022-01-19T00:00:00.000Z",
            "status": "paid"
        },
        {
            "id": "5f0efa72-f2b9-4b5d-9c1b-8f8f1e0b0c2e",
            "name": "Invoice 2",
            "description": "This is an invoice for product 2",
            "amount": 200,
            "currency": "USDC",
            "created_at": "2022-01-19T00:00:00.000Z",
            "updated_at": "2022-01-19T00:00:00.000Z",
            "status": "unpaid"
        }
    ]
}

curl -X GET https://api.sonicpay.org/v1/invoices \
-H 'Authorization: Bearer YOUR_API_KEY'

You can also include query parameters to filter the invoices returned in the response. For example, you can filter by invoice status (paid, unpaid, etc) or by a specific date range.

curl -X GET https://api.sonicpay.org/v1/invoices?status=paid&start_date=2022-01-01&end_date=2022-12-31 \
-H 'Authorization: Bearer YOUR_API_KEY'

Alternatively, you can use the Sonic Payment Gateway SDK to get all invoices in your desired programming language. The SDK will handle the API call and return the result in a format that is easy to work with in your code.

sonicPayment.getAllInvoices(
  {
    status: "paid",
    start_date: "2022-01-01",
    end_date: "2022-12-31",
  },
  (error, invoices) => {
    if (error) {
      console.log(error);
    } else {
      console.log(invoices);
    }
  }
);

Response:

{
  "invoices": [
    {
      "id": "inv_1D5sV2eZgKYlo2C",
      "status": "paid",
      "amount": 100,
      "date": "2022-05-01T12:00:00Z",
      "payment_link_id": "pl_1D5sV2eZgKYlo2C",
      "metadata": {
        "customer_name": "John Doe"
      }
    },
    {
      "id": "inv_1D5sV2eZgKYlo2C",
      "status": "paid",
      "amount": 50,
      "date": "2022-05-15T12:00:00Z",
      "payment_link_id": "pl_1D5sV2eZgKYlo2C",
      "metadata": {
        "customer_name": "Jane Smith"
      }
    }
  ]
}