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

200

List of invoices successfully retrieved

application/json

Represents a payment invoice in the system

idstring · uuidOptional

Unique identifier of the invoice

parent_idstring · uuid · nullableOptional

ID of the parent invoice if this is a child invoice

client_idstring · uuidOptional

ID of the client who needs to pay this invoice

totalstring · decimalOptional

Total amount to be paid in the specified currency

paidstring · decimalOptional

Amount that has been paid so far

typestring · enumOptional

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

Possible values:

statusstring · enumOptional

Current status of the invoice:

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

Possible values:

payloadobject · nullableOptional

Additional custom data associated with the invoice

created_atstring · date-timeOptional

Timestamp when the invoice was created

updated_atstring · date-timeOptional

Timestamp of the last invoice update

401

Unauthorized - Invalid or missing authentication token

get

/invoice

HTTPcURLJavaScriptPython

GET /invoice?v=2 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": "2026-02-27T21:43:14.310Z",
    "updated_at": "2026-02-27T21:43:14.310Z",
    "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": "2026-02-27T21:43:14.310Z",
          "updated_at": "2026-02-27T21:43:14.310Z",
          "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

bearerAuth

AuthorizationstringRequired

Authorization token must be included in the Authorization header. Example: Authorization: Bearer YOUR_TOKEN app_secret from API Keys section

Query parameters

vinteger · enumRequired

API version, must be 2

Possible values:

Body

application/json

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

201

Invoice successfully created

application/json

400

Invalid request parameters

401

Unauthorized - Invalid or missing authentication token

post

/invoice

HTTPcURLJavaScriptPython

POST /invoice?v=2 HTTP/1.1
Host: api.simplepay.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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": "2026-02-27T21:43:14.310Z",
  "updated_at": "2026-02-27T21:43:14.310Z",
  "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": "2026-02-27T21:43:14.310Z",
        "updated_at": "2026-02-27T21:43:14.310Z",
        "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

200

Invoice details successfully retrieved

application/json

Represents a payment invoice in the system

idstring · uuidOptional

Unique identifier of the invoice

parent_idstring · uuid · nullableOptional

ID of the parent invoice if this is a child invoice

client_idstring · uuidOptional

ID of the client who needs to pay this invoice

totalstring · decimalOptional

Total amount to be paid in the specified currency

paidstring · decimalOptional

Amount that has been paid so far

typestring · enumOptional

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

Possible values:

statusstring · enumOptional

Current status of the invoice:

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

Possible values:

payloadobject · nullableOptional

Additional custom data associated with the invoice

created_atstring · date-timeOptional

Timestamp when the invoice was created

updated_atstring · date-timeOptional

Timestamp of the last invoice update

401

Unauthorized - Invalid or missing authentication token

404

Invoice not found

get

/invoice/{id}

HTTPcURLJavaScriptPython

GET /invoice/{id}?v=2 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": "2026-02-27T21:43:14.310Z",
  "updated_at": "2026-02-27T21:43:14.310Z",
  "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": "2026-02-27T21:43:14.310Z",
        "updated_at": "2026-02-27T21:43:14.310Z",
        "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

bearerAuth

AuthorizationstringRequired

Authorization token must be included in the Authorization header. Example: Authorization: Bearer YOUR_TOKEN app_secret from API Keys section

Path parameters

idstring · uuidRequired

Invoice ID to cancel

Query parameters

vinteger · enumRequired

API version, must be 2

Possible values:

Responses

200

Invoice successfully cancelled

application/json

Represents a payment invoice in the system

idstring · uuidOptional

Unique identifier of the invoice

parent_idstring · uuid · nullableOptional

ID of the parent invoice if this is a child invoice

client_idstring · uuidOptional

ID of the client who needs to pay this invoice

totalstring · decimalOptional

Total amount to be paid in the specified currency

paidstring · decimalOptional

Amount that has been paid so far

typestring · enumOptional

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

Possible values:

statusstring · enumOptional

Current status of the invoice:

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

Possible values:

payloadobject · nullableOptional

Additional custom data associated with the invoice

created_atstring · date-timeOptional

Timestamp when the invoice was created

updated_atstring · date-timeOptional

Timestamp of the last invoice update

401

Unauthorized - Invalid or missing authentication token

404

Invoice not found

409

Invoice cannot be cancelled (wrong status)

delete

/invoice/{id}

HTTPcURLJavaScriptPython

DELETE /invoice/{id}?v=2 HTTP/1.1
Host: api.simplepay.ai
Authorization: Bearer YOUR_SECRET_TOKEN
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": "2026-02-27T21:43:14.310Z",
  "updated_at": "2026-02-27T21:43:14.310Z",
  "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": "2026-02-27T21:43:14.310Z",
        "updated_at": "2026-02-27T21:43:14.310Z",
        "prices": [
          {
            "price": 1,
            "currency": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "symbol": "text",
              "code": 1
            }
          }
        ]
      }
    }
  ]
}