v1.3
OAS 3.1.0

SimplePay API

Overview

Our API is constantly being improved. This specification reflects the current endpoints directly from our codebase.

We provide hand-crafted client libraries for some programming languages that cover most endpoints, as well as versioning, security, and validation logic described in this specification. We generally recommend using them to consume our API.

This specification is intended for developers who, for some reason, choose not to use the official client libraries or those who want to generate a client library for a language that is not yet officially supported.

Authentication

Our API supports several authentication methods:

  • Personal Access Token (referred to as PAT)
    Intended for server-side use in the context of a specific user, for managing the user's account.
    It can be obtained in the Service Tokens section of the SimpleID portal.

  • App Token (referred to as AppToken)
    Intended for server-side use in the context of a specific app, to perform tasks required for the app's operation.
    It can be obtained in the API keys section of app settings in the Console.

  • OAuth 2 (referred to as OAuth2)
    Intended for server-side use to manage accounts on behalf of users, after obtaining their consent.
    Token can be obtained when someone signing in to your app using SimplePay as an OIDC provider.
    You can create an OAuth Client to implement this integration in the OAuth Clients section of the Console.

  • Cookie (referred to as Cookie)
    Intended for use in browsers, primarily by our own frontends. It is described here only for reference and is generally not recommended for use by third parties (except perhaps by curious individuals experimenting with our API for fun or engaging in creative automation).

Support for authentication methods may vary from endpoint to endpoint.

Versioning

Most API endpoints use versioning. Each endpoint has its own independent version history, which is unrelated to the version of this specification.

The version should be passed as the v query parameter. The value of this parameter is an integer that represents the major (backward-incompatible) version.

Changes are considered backward-incompatible if one or more request parameters or response properties are removed, renamed, or have their types changed, or if one or more required request parameters are added.

The addition of response properties is considered backward-compatible, and the version is not incremented in such cases. API consumers should be designed to ignore any unknown response properties without producing errors.

Parameters, properties, and endpoints not explicitly defined in this specification should be treated as internal or experimental and may change at any time without prior notice or version increment.

Idempotency

Some endpoints that mutate data or perform actions (POST, PUT, DELETE) supports idempotency.

You may pass random UUIDv4 as the Idempotency-Key header, and subsequent requests with the same key will return the same status code and response body, without performing any mutations or actions.

This behavior is not guaranteed for requests made in more than 24 hours after the first one.

CSRF Protection

Some endpoints that mutate data (POST, PUT, DELETE) are protected against CSRF.

When using Cookie authentication method (what normally you should avoid), you should pass an anti-CSRF token as the X-Csrf-Token header.

To obtain this token, you should make a request to a GET endpoint in the same group and then pass the received X-Csrf-Token header along with the csrf_ cookie in subsequent requests.

In other words, call GET /something before POST /something.

Anti-CSRF token lifetime is 1 hour.

Rate limits

Currently there is no rate limits set, however we may introduce them in future without prior notice. You will likely never get anywhere near them unless you intentionally spam our API, but you may decide to implement graceful retries in your consumer.

In case rate limit triggered, 429 status code will be returned with Retry-After header, that indicates how many seconds consumer should wait before repeating the request.

No authentication selected
Client Libraries
Curl Shell

Invoices​

Invoice is a main entity in our system.

When you want to accept payment from your customer, you should create and provide him an Invoice, which contain total in fiat currency and order summary - just like a paper one.

This endpoint group intended to manage invoices.

Invoices Endpoints

Transactions​

Transaction is an entity, that represents an attempt of your customer to pay Invoice.

Transactions are created by customer from frontend, when he starts a payment attempt. Each Invoice may have multiple transactions, so customer may pay in installments, until required total be reached.

This endpoint group intended to manage transactions.

Transactions Endpoints

Currencies​

Methods for managing fiat currencies

Currencies Endpoints

Cryptocurrencies​

Methods for managing cryptocurrencies

Cryptocurrencies Endpoints

Apps​

Methods for managing applications

Apps Endpoints

List apps​

Query Parameters
  • v
    const: 
    1
    required

    Endpoint version

    • 1
Responses
GET/app
import type { HttpError } from '@simplepay-ai/api-client';
import { Client } from '@simplepay-ai/api-client';

const api = new Client({
    apiKey: '...',
});

try {
    const apps = await api.app.list();

    console.log('Apps:', apps);
} catch (e) {
    if (e instanceof HttpError) {
        const error = e as HttpError;

        console.log('HttpError:', error);
    }
}


[
  {
    "id": "9aca19fe-f314-4328-88e6-09b337aad2dd",
    "name": "Simple Pizza",
    "description": "The best place to try authentic Italian pizza",
    "slug": "simple-pizza",
    "image": "https://example.com/image.webp",
    "url": "https://example.com",
    "token": "Ppc5kj4qZSmCcRLiDBfMBC3sWgrIATmKoPxYAPe3BAtYFxIEFceBUp9XaQJS53Kc",
    "environment": "development",
    "created_at": "2024-07-31T00:48:53Z",
    "updated_at": "2024-07-31T00:49:28Z"
  }
]

OK

Create app​

Query Parameters
  • v
    const: 
    1
    required

    Endpoint version

    • 1
Headers
  • X-Csrf-Token
    string uuid

    Anti-CSRF token

    This header is only required when using Cookie authentication method. It should be set to value of X-Csrf-Token header returned by any GET method in same group

Cookies
  • csrf_
    string uuid

    Anti-CSRF cookie

    This cookie is only required when using Cookie authentication method. It will be set after calling any GET method in same group, and normally will be added to subsequent requests automatically by browser

Body
application/json
name
string
min: 
1
max: 
255
required

App name

ExampleSimple Pizza
description
string | null
min: 
1
max: 
1000

App description

ExampleThe best place to try authentic Italian pizza
slug
string | null
min: 
1
max: 
255

App slug

Examplesimple-pizza
image
string | null

App image (uploaded file name)

See: Get upload target

Example2df345e0-b657-4b4e-96b8-c5a924f7c01e.jpg
url
string
max: 
1000uri
required

App URL

Examplehttps://example.com
environment
string enum
required

App environment

Examplesdevelopmentproduction
  • development
  • production
Responses
POST/app
import type { AppCreateErrors, HttpError, ValidationError } from '@simplepay-ai/api-client';
import { AppEnvironment, Client } from '@simplepay-ai/api-client';

const api = new Client({
    apiKey: '...',
});

try {
    const app = await api.app.create({
        name: 'Simple Pizza',
        description: 'The best place to try authentic Italian pizza',
        slug: 'simple-pizza',
        url: 'https://example.com',
        environment: AppEnvironment.Development,
    });

    console.log('App:', app);
} catch (e) {
    if (e instanceof ValidationError) {
        const error = e as ValidationError<AppCreateErrors>;

        console.log('ValidationError:', error);
    }
    if (e instanceof HttpError) {
        const error = e as HttpError;

        console.log('HttpError:', error);
    }
}


{
  "id": "9aca19fe-f314-4328-88e6-09b337aad2dd",
  "name": "Simple Pizza",
  "description": "The best place to try authentic Italian pizza",
  "slug": "simple-pizza",
  "image": "https://example.com/image.webp",
  "url": "https://example.com",
  "token": "Ppc5kj4qZSmCcRLiDBfMBC3sWgrIATmKoPxYAPe3BAtYFxIEFceBUp9XaQJS53Kc",
  "environment": "development",
  "created_at": "2024-07-31T00:48:53Z",
  "updated_at": "2024-07-31T00:49:28Z"
}

Created

Get app​

Path Parameters
  • id
    oneOf
    required

    App ID or slug

    App ID

    App slug

Query Parameters
  • v
    const: 
    1
    required

    Endpoint version

    • 1
Responses
GET/app/{id}
import type { HttpError } from '@simplepay-ai/api-client';
import { Client } from '@simplepay-ai/api-client';

const api = new Client({
    apiKey: '...',
});

const appId = '9aca19fe-f314-4328-88e6-09b337aad2dd';

try {
    const app = await api.app.get(appId);

    console.log('App:', app);
} catch (e) {
    if (e instanceof HttpError) {
        const error = e as HttpError;

        console.log('HttpError:', error);
    }
}


{
  "id": "9aca19fe-f314-4328-88e6-09b337aad2dd",
  "name": "Simple Pizza",
  "description": "The best place to try authentic Italian pizza",
  "slug": "simple-pizza",
  "image": "https://example.com/image.webp",
  "url": "https://example.com"
}

OK

Update app​

Path Parameters
  • id
    string uuid
    required

    App ID

    Example9aca19fe-f314-4328-88e6-09b337aad2dd
Query Parameters
  • v
    const: 
    1
    required

    Endpoint version

    • 1
Headers
  • X-Csrf-Token
    string uuid

    Anti-CSRF token

    This header is only required when using Cookie authentication method. It should be set to value of X-Csrf-Token header returned by any GET method in same group

Cookies
  • csrf_
    string uuid

    Anti-CSRF cookie

    This cookie is only required when using Cookie authentication method. It will be set after calling any GET method in same group, and normally will be added to subsequent requests automatically by browser

Body
application/json
name
string
min: 
1
max: 
255

App name

ExampleSimple Pizza
description
string | null
min: 
1
max: 
1000

App description

ExampleThe best place to try authentic Italian pizza
slug
string | null
min: 
1
max: 
255

App slug

Examplesimple-pizza
image
string | null

App image (uploaded file name)

See: Get upload target

Example2df345e0-b657-4b4e-96b8-c5a924f7c01e.jpg
url
string
max: 
1000uri

App URL

Examplehttps://example.com
token
boolean

Regenerate app token

Responses
PUT/app/{id}
import type { AppUpdateErrors, HttpError, ValidationError } from '@simplepay-ai/api-client';
import { AppEnvironment, Client } from '@simplepay-ai/api-client';

const api = new Client({
    apiKey: '...',
});

try {
    const app = await api.app.update({
        name: 'Simple Pizza',
        description: 'The best place to try authentic Italian pizza',
        slug: 'simple-pizza',
        url: 'https://example.com',
        environment: AppEnvironment.Development,
    });

    console.log('App:', app);
} catch (e) {
    if (e instanceof ValidationError) {
        const error = e as ValidationError<AppUpdateErrors>;

        console.log('ValidationError:', error);
    }
    if (e instanceof HttpError) {
        const error = e as HttpError;

        console.log('HttpError:', error);
    }
}


{
  "id": "9aca19fe-f314-4328-88e6-09b337aad2dd",
  "name": "Simple Pizza",
  "description": "The best place to try authentic Italian pizza",
  "slug": "simple-pizza",
  "image": "https://example.com/image.webp",
  "url": "https://example.com",
  "token": "Ppc5kj4qZSmCcRLiDBfMBC3sWgrIATmKoPxYAPe3BAtYFxIEFceBUp9XaQJS53Kc",
  "environment": "development",
  "created_at": "2024-07-31T00:48:53Z",
  "updated_at": "2024-07-31T00:49:28Z"
}

OK

App Cryptocurrencies​

Methods for managing app cryptocurrencies

App Cryptocurrencies Endpoints

App Addresses​

Methods for managing app addresses

App Addresses Endpoints

Personal Access Tokens​

Methods for managing Personal Access Tokens

Personal Access Tokens Endpoints

OAuth2 Sessions​

Methods for managing OAuth2 Sessions

OAuth2 Sessions Endpoints

Webhooks

Models