Invoices

Invoice API Methods and Refference

Parameters

Invoice ID

Id is unique identifier that represents Invoice object for quering details of specific invoice

Parent ID

Parent id points to relative invoice that was parent in the chain of invoices. Sometimes we need to make several tranches, thats how we can bind several invoices into chain.

Client ID

Client id is a identifier of your customer. Its represents a unique UUID v4 that pointers to specific user or customer to whom you direct your invoice. If you have account managment system, you may input user's id in your DB as client_id to easy bind your user's payments separate from others.

Total

Amount of funds needed to complete invoice. It's depends on choosen currency in invoice body while creating, to calculate current rates and amount that left to pay.

Paid

Represents amount of funds to current invoice currency that was already submited as paid in one or several transactions.

Type

Type of invoice. For now we support "payment" only.

Status

Status of the invoice represents it's current stage. It may be ACTIVE / SUCCESS / CANCELED.

You cannot cancel invoices with SUCCESS statuses.

Created At

Represents timestamp when invoice was created.

Updated At

Represents timestamp of new transactions appears in the Invoice or invoice status changes.

Products

See products API section

Payload

See payload section

API Refference

Get Invoices List

Retrieves a list of all invoices associated with the authenticated merchant. Results are paginated and can be filtered by status.

GEThttps://api.simplepay.ai/invoice

Query parameters

Response

200401

List of invoices successfully retrieved

Body

application/json

idstring (uuid)

Unique identifier of the invoice

parent_idnullable string (uuid)

ID of the parent invoice if this is a child invoice

client_idstring (uuid)

ID of the client who needs to pay this invoice

totalstring (decimal)

Total amount to be paid in the specified currency

paidstring (decimal)

Amount that has been paid so far

typeenum

Type of the invoice, currently only 'payment' is supported

payment

statusenum

Current status of the invoice:

• active - waiting for payment
• success - fully paid
• canceled - payment cancelled

activesuccesscanceled

payloadnullable object

Additional custom data associated with the invoice

created_atstring (date-time)

Timestamp when the invoice was created

updated_atstring (date-time)

Timestamp of the last invoice update

currencyCurrency (object)

Represents a fiat currency

productsarray of ProductInInvoice (object)

List of products included in this invoice

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.simplepay.ai/invoice?v=2', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "parent_id": "123e4567-e89b-12d3-a456-426614174000",
    "client_id": "123e4567-e89b-12d3-a456-426614174000",
    "total": "text",
    "paid": "text",
    "type": "payment",
    "status": "active",
    "created_at": "2025-01-22T07:57:47.588Z",
    "updated_at": "2025-01-22T07:57:47.588Z",
    "currency": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "symbol": "text",
      "code": 0
    },
    "products": [
      {
        "count": 0,
        "product": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "description": "text",
          "image": "https://example.com",
          "created_at": "2025-01-22T07:57:47.588Z",
          "updated_at": "2025-01-22T07:57:47.588Z",
          "prices": [
            {
              "price": 0,
              "currency": {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "symbol": "text",
                "code": 0
              }
            }
          ]
        }
      }
    ]
  }
]

Create Invoice

Creates a new invoice for specified amount and currency. The invoice can be associated with specific products.

POSThttps://api.simplepay.ai/invoice

Authorization

bearerAuth

Query parameters

Body

application/json

app_id*string (uuid)

ID of the merchant application

typeenum

Type of invoice, currently only 'payment' is supported

payment

client_id*string (uuid)

ID of the client who needs to pay

currency*string

Three-letter currency code (e.g., USD)

total*number

Total amount to be paid

Response

201400401

Invoice successfully created

Body

application/json

idstring (uuid)

Unique identifier of the invoice

parent_idnullable string (uuid)

ID of the parent invoice if this is a child invoice

client_idstring (uuid)

ID of the client who needs to pay this invoice

totalstring (decimal)

Total amount to be paid in the specified currency

paidstring (decimal)

Amount that has been paid so far

typeenum

Type of the invoice, currently only 'payment' is supported

payment

statusenum

Current status of the invoice:

• active - waiting for payment
• success - fully paid
• canceled - payment cancelled

activesuccesscanceled

payloadnullable object

Additional custom data associated with the invoice

created_atstring (date-time)

Timestamp when the invoice was created

updated_atstring (date-time)

Timestamp of the last invoice update

currencyCurrency (object)

Represents a fiat currency

productsarray of ProductInInvoice (object)

List of products included in this invoice

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.simplepay.ai/invoice?v=2', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "app_id": "123e4567-e89b-12d3-a456-426614174000",
      "client_id": "123e4567-e89b-12d3-a456-426614174000",
      "currency": "text",
      "total": 0
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "client_id": "123e4567-e89b-12d3-a456-426614174000",
  "total": "text",
  "paid": "text",
  "type": "payment",
  "status": "active",
  "created_at": "2025-01-22T07:57:47.588Z",
  "updated_at": "2025-01-22T07:57:47.588Z",
  "currency": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "text",
    "code": 0
  },
  "products": [
    {
      "count": 0,
      "product": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "image": "https://example.com",
        "created_at": "2025-01-22T07:57:47.588Z",
        "updated_at": "2025-01-22T07:57:47.588Z",
        "prices": [
          {
            "price": 0,
            "currency": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "symbol": "text",
              "code": 0
            }
          }
        ]
      }
    }
  ]
}

Get Invoice Details

Retrieves detailed information about a specific invoice

GEThttps://api.simplepay.ai/invoice/{id}

Path parameters

id*string (uuid)

Invoice ID

Query parameters

Response

200401404

Invoice details successfully retrieved

Body

application/json

idstring (uuid)

Unique identifier of the invoice

parent_idnullable string (uuid)

ID of the parent invoice if this is a child invoice

client_idstring (uuid)

ID of the client who needs to pay this invoice

totalstring (decimal)

Total amount to be paid in the specified currency

paidstring (decimal)

Amount that has been paid so far

typeenum

Type of the invoice, currently only 'payment' is supported

payment

statusenum

Current status of the invoice:

• active - waiting for payment
• success - fully paid
• canceled - payment cancelled

activesuccesscanceled

payloadnullable object

Additional custom data associated with the invoice

created_atstring (date-time)

Timestamp when the invoice was created

updated_atstring (date-time)

Timestamp of the last invoice update

currencyCurrency (object)

Represents a fiat currency

productsarray of ProductInInvoice (object)

List of products included in this invoice

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.simplepay.ai/invoice/{id}?v=2', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "client_id": "123e4567-e89b-12d3-a456-426614174000",
  "total": "text",
  "paid": "text",
  "type": "payment",
  "status": "active",
  "created_at": "2025-01-22T07:57:47.588Z",
  "updated_at": "2025-01-22T07:57:47.588Z",
  "currency": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "text",
    "code": 0
  },
  "products": [
    {
      "count": 0,
      "product": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "image": "https://example.com",
        "created_at": "2025-01-22T07:57:47.588Z",
        "updated_at": "2025-01-22T07:57:47.588Z",
        "prices": [
          {
            "price": 0,
            "currency": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "symbol": "text",
              "code": 0
            }
          }
        ]
      }
    }
  ]
}

Cancel Invoice

Cancels an active invoice. Cancelled invoices cannot receive payments. Only active invoices can be cancelled.

DELETEhttps://api.simplepay.ai/invoice/{id}

Path parameters

id*string (uuid)

Invoice ID to cancel

Query parameters

Response

200401404409

Invoice successfully cancelled

Body

application/json

idstring (uuid)

Unique identifier of the invoice

parent_idnullable string (uuid)

ID of the parent invoice if this is a child invoice

client_idstring (uuid)

ID of the client who needs to pay this invoice

totalstring (decimal)

Total amount to be paid in the specified currency

paidstring (decimal)

Amount that has been paid so far

typeenum

Type of the invoice, currently only 'payment' is supported

payment

statusenum

Current status of the invoice:

• active - waiting for payment
• success - fully paid
• canceled - payment cancelled

activesuccesscanceled

payloadnullable object

Additional custom data associated with the invoice

created_atstring (date-time)

Timestamp when the invoice was created

updated_atstring (date-time)

Timestamp of the last invoice update

currencyCurrency (object)

Represents a fiat currency

productsarray of ProductInInvoice (object)

List of products included in this invoice

Request

JavaScriptCurlPythonHTTP

const response = await fetch('https://api.simplepay.ai/invoice/{id}?v=2', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "client_id": "123e4567-e89b-12d3-a456-426614174000",
  "total": "text",
  "paid": "text",
  "type": "payment",
  "status": "active",
  "created_at": "2025-01-22T07:57:47.588Z",
  "updated_at": "2025-01-22T07:57:47.588Z",
  "currency": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "text",
    "code": 0
  },
  "products": [
    {
      "count": 0,
      "product": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "image": "https://example.com",
        "created_at": "2025-01-22T07:57:47.588Z",
        "updated_at": "2025-01-22T07:57:47.588Z",
        "prices": [
          {
            "price": 0,
            "currency": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "symbol": "text",
              "code": 0
            }
          }
        ]
      }
    }
  ]
}