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

get

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

Query parameters

vinteger · enumRequired

API version, must be 2

Possible values:

Responses

get

HTTPcURLJavaScriptPython

GET /invoice HTTP/1.1
Host: api.simplepay.ai
Accept: */*

[
  {
    "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",
    "payload": {},
    "created_at": "2025-04-24T22:31:14.327Z",
    "updated_at": "2025-04-24T22:31:14.327Z",
    "currency": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "symbol": "text",
      "code": 1
    },
    "products": [
      {
        "count": 1,
        "product": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "description": "text",
          "image": "https://example.com",
          "created_at": "2025-04-24T22:31:14.327Z",
          "updated_at": "2025-04-24T22:31:14.327Z",
          "prices": [
            {
              "price": 1,
              "currency": {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "symbol": "text",
                "code": 1
              }
            }
          ]
        }
      }
    ]
  }
]

Create Invoice

post

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

Authorizations

Query parameters

vinteger · enumRequired

API version, must be 2

Possible values:

Body

app_idstring · uuidRequired

ID of the merchant application

typestring · enumOptional

Type of invoice, currently only 'payment' is supported

Possible values:

client_idstring · uuidRequired

ID of the client who needs to pay

currencystringRequired

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

totalnumberRequired

Total amount to be paid

Responses

post

HTTPcURLJavaScriptPython

POST /invoice HTTP/1.1
Host: api.simplepay.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 145

{
  "app_id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "payment",
  "client_id": "123e4567-e89b-12d3-a456-426614174000",
  "currency": "text",
  "total": 1
}

{
  "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",
  "payload": {},
  "created_at": "2025-04-24T22:31:14.327Z",
  "updated_at": "2025-04-24T22:31:14.327Z",
  "currency": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "text",
    "code": 1
  },
  "products": [
    {
      "count": 1,
      "product": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "image": "https://example.com",
        "created_at": "2025-04-24T22:31:14.327Z",
        "updated_at": "2025-04-24T22:31:14.327Z",
        "prices": [
          {
            "price": 1,
            "currency": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "symbol": "text",
              "code": 1
            }
          }
        ]
      }
    }
  ]
}

Get Invoice Details

get

Retrieves detailed information about a specific invoice

Path parameters

idstring · uuidRequired

Invoice ID

Query parameters

vinteger · enumRequired

API version, must be 2

Possible values:

Responses

get

HTTPcURLJavaScriptPython

GET /invoice/{id} HTTP/1.1
Host: api.simplepay.ai
Accept: */*

{
  "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",
  "payload": {},
  "created_at": "2025-04-24T22:31:14.327Z",
  "updated_at": "2025-04-24T22:31:14.327Z",
  "currency": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "text",
    "code": 1
  },
  "products": [
    {
      "count": 1,
      "product": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "image": "https://example.com",
        "created_at": "2025-04-24T22:31:14.327Z",
        "updated_at": "2025-04-24T22:31:14.327Z",
        "prices": [
          {
            "price": 1,
            "currency": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "symbol": "text",
              "code": 1
            }
          }
        ]
      }
    }
  ]
}

Cancel Invoice

delete

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

Authorizations

Path parameters

idstring · uuidRequired

Invoice ID to cancel

Query parameters

vinteger · enumRequired

API version, must be 2

Possible values:

Responses

delete

HTTPcURLJavaScriptPython

DELETE /invoice/{id} HTTP/1.1
Host: api.simplepay.ai
Authorization: Bearer JWT
Accept: */*

{
  "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",
  "payload": {},
  "created_at": "2025-04-24T22:31:14.327Z",
  "updated_at": "2025-04-24T22:31:14.327Z",
  "currency": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "symbol": "text",
    "code": 1
  },
  "products": [
    {
      "count": 1,
      "product": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "image": "https://example.com",
        "created_at": "2025-04-24T22:31:14.327Z",
        "updated_at": "2025-04-24T22:31:14.327Z",
        "prices": [
          {
            "price": 1,
            "currency": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "symbol": "text",
              "code": 1
            }
          }
        ]
      }
    }
  ]
}