NAV Navbar
shell javascript

Business API Reference

This website documents the public API for PlasmaPay Business

You can view code examples in the dark area to the right; switch the programming language of the examples with the tabs in the top right.

Authentication

curl -X GET -H "content-type: application/json" -H "authorization: Bearer <API_KEY>"
https://app.plasmapay.com/business/api/v1/public/ping
const xhr = new XMLHttpRequest();
xhr.onload = function () {
    // Handle xhr.status and xhr.responseText
};
xhr.open('GET', 'https://app.plasmapay.com/business/api/v1/public/ping', true);
xhr.withCredentials = true;
xhr.setRequestHeader('authorization','Bearer API_KEY');
req.setRequestHeader('content-type','application/json');
xhr.send();

The PlasmaPay Business API uses API keys to authenticate requests. You can view and manage your API keys in the Business Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer 341a90c6-eed9-4358-aa35-3b1cfbef2d9e".

Also you can pass your API KEY throw the query param apiKey

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Invoice


ENDPOINTS:

GET 'https://app.plasmapay.com/business/api/v1/public/ping'

POST 'https://app.plasmapay.com/business/api/v1/public/invoices'

GET 'https://app.plasmapay.com/business/api/v1/public/invoices'

GET 'https://app.plasmapay.com/business/api/v1/public/invoices/:extId'

DELETE 'https://app.plasmapay.com/business/api/v1/public/invoices/:extId'


ENDPOINTS:

GET 'https://app.plasmapay.com/business/api/v1/public/ping'

POST 'https://app.plasmapay.com/business/api/v1/public/invoices'

GET 'https://app.plasmapay.com/business/api/v1/public/invoices'

GET 'https://app.plasmapay.com/business/api/v1/public/invoices/:extId'

DELETE 'https://app.plasmapay.com/business/api/v1/public/invoices/:extId'

Invoices are statements of amounts owed by a customer, and are either generated one-off.

They contain invoice items, and proration adjustments that may be caused by subscription upgrades/downgrades (if necessary).

Note that finalizing the invoice, when automatic, does not happen immediately as the invoice is created. PlasmaPay would sent a webhook after success invoice payment. If you (and the platforms you may have connected to) have no webhooks configured, PlasmaPay provides an API that can be called to figure out invoice status.

PlasmaPay applies any customer credit on the account before determining the amount due for the invoice (i.e., the amount that will be actually charged).

GET /ping

Test your connection using API KEY.

curl 
  -X GET 
  -H "content-type: application/json" 
  -H "authorization: Bearer <API_KEY>"
  https://app.plasmapay.com/business/api/v1/public/ping
const xhr = new XMLHttpRequest();
xhr.onload = function () {
    // Handle xhr.status and xhr.responseText
};
xhr.open('GET', 'https://app.plasmapay.com/business/api/v1/public/ping', true);
xhr.withCredentials = true;
xhr.setRequestHeader('authorization','Bearer API_KEY');
req.setRequestHeader('content-type','application/json');
xhr.send();

RESPONSE

200 Ok
Content-Type: application/json

BODY

{ 
  "message": "pong ;)"
}

In order to test your connection to the server must make a GET request to

GET https://app.plasmapay.com/business/api/v1/public/ping

with the apiKey as query parameter or Bearer <API_KEY> as authorization header.

Parameter Meaning
apiKey={API_KEY} The application's api key provided when registering your application

After receive the success message you can use all public API's.

POST /invoices

Create invoice.

curl 
  -X POST 
  -H "Content-type: application/json" 
  -H "authorization: Bearer <API_KEY>"
  https://app.plasmapay.com/business/api/v1/public/invoices
  -d '{"currencyCode": "{INVOICE_CURRENCY}", "amount": "{INVOICE_AMOUNT}","currencyCode": "EURP", "metadata": {"{KEY}": "{VALUE}"},"merchantId": "{MERCHANT_ID}","description": "{DESCRIPTION_TEXT}","accountId": "{USER_ID}"}'
var request = require('request');

const options = { uri: 'https://app.plasmapay.com/business/api/v1/public/invoices', method: 'POST', headers: { 'Content-Type': 'application/json' 'authorization': 'Bearer API_KEY' }, json: { "currencyCode": "{INVOICE_CURRENCY}", "amount": "{INVOICE_AMOUNT}", "currencyCode": "EURP", "metadata": { "{KEY}": "{VALUE}" }, "merchantId": "{MERCHANT_ID}", "description": "{DESCRIPTION_TEXT}", "accountId": "{USER_ID}" } }

request(options, function (error, response, body) { if (!error && response.statusCode === 200) { // Handle body } });

RESPONSE

200 Ok
Content-Type: application/json

BODY

{
    "id": "{INTERNAL_ID}",
    "amount": "{INVOICE_AMOUNT}",
    "currencyCode": "{INVOICE_CURRENCY}",
    "status": "new",
    "extId": "{INVOICE_ID}",
    "createdAt": "{DATE}",
    "link": "https://app.plasmapay.com/business/api/v1/public/pay-invoice/{INVOICE_ID}",
    "metadata": {
        "{KEY}": "{VALUE}"
    },
    "merchantId": "{MERCHANT_ID}",
    "description": "{DESCRIPTION_TEXT}",
    "accountId": "{USER_ID}"
}

In order to create invoice on the server you must make a POST request to

POST https://app.plasmapay.com/business/api/v1/public/invoices

with the apiKey as query parameter or Bearer <API_KEY> as authorization header.

Parameter Meaning
currencyCode={INVOICE_CURRENCY} Invoice stable coin currency code (required)
amount={INVOICE_AMOUNT} Invoice amount (required)
merchantId={INVOICE_MERCHANTID} EExternal ID / ID of your order (required)
description={INVOICE_DESCRIPTION} Invoice description (required)
accountId={INVOICE_ACCOUNTID} External user ID / ID of your user (required)
metadata={INVOICE_METADATA} Key value storage (optional)

After receive the success response you can redirect user on https://app.plasmapay.com/business/api/v1/public/pay-invoice/{INVOICE_ID} page to pay the invoice.

GET /invoices

Fetch list invoices.

curl 
  -X GET 
  -H "Content-type: application/json" 
  -H "authorization: Bearer <API_KEY>"
  https://app.plasmapay.com/business/api/v1/public/invoices?
  limit={INVOICES_LIMIT}&
  offset={INVOICES_OFFSET}&
  status={INVOICES_STATUS}&
  dateFrom={INVOICES_FROM}&
  dateTo={INVOICES_TO}
var request = require('request');

const options = { uri: 'https://app.plasmapay.com/business/api/v1/public/invoices', method: 'GET', headers: { 'Content-Type': 'application/json' 'authorization': 'Bearer API_KEY' }, qs: { limit:{INVOICES_LIMIT}, offset:{INVOICES_OFFSET}, status:{INVOICES_STATUS}, dateFrom:{INVOICES_FROM}, dateTo:{INVOICES_TO} } }

request(options, function (error, response, body) { if (!error && response.statusCode === 200) { // Handle body } });

RESPONSE

200 Ok
Content-Type: application/json

BODY

"result": [
  {
    "id": "{INTERNAL_ID}",
    "amount": "{INVOICE_AMOUNT}",
    "currencyCode": "{INVOICE_CURRENCY}",
    "status": "new",
    "extId": "{INVOICE_ID}",
    "createdAt": "{DATE}",
    "link": "https://app.plasmapay.com/business/api/v1/public/pay-invoice/{INVOICE_ID}"
    "metadata": {
      "{KEY}": "{VALUE}"
    },
    "merchantId": "{MERCHANT_ID}",
    "description": "{DESCRIPTION_TEXT}",
    "accountId": "{USER_ID}"
  }
],
"meta": {
  "total": 1,
},

In order to fetch list of invoice you must make a GET request to

GET https://app.plasmapay.com/business/api/v1/public/invoices

with the apiKey as query parameter or Bearer <API_KEY> as authorization header.

Parameter Meaning
limit={INVOICES_LIMIT} Limit (optional)
offset={INVOICES_OFFSET} Offset (optional)
status={INVOICES_STATUS} Invoice status (optional)
dateFrom={INVOICES_FROM} Invoice date from (optional)
dateTo={INVOICES_TO} Invoice date to (optional)

INVOICES_STATUS available values: pending success failed canceled deleted

GET /invoices/:extId

Fetch invoice by id.

curl 
  -X GET 
  -H "Content-type: application/json" 
  -H "authorization: Bearer <API_KEY>"
  https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}
var request = require('request');

const options = { uri: 'https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}', method: 'GET', headers: { 'Content-Type': 'application/json' 'authorization': 'Bearer API_KEY' } }

request(options, function (error, response, body) { if (!error && response.statusCode === 200) { // Handle body } });

RESPONSE

200 Ok
Content-Type: application/json

BODY

{
  "id": "{INTERNAL_ID}",
  "amount": "{INVOICE_AMOUNT}",
  "currencyCode": "{INVOICE_CURRENCY}",
  "status": "new",
  "extId": "{INVOICE_ID}",
  "createdAt": "{DATE}",
  "link": "https://app.plasmapay.com/business/api/v1/public/pay-invoice/{INVOICE_ID}"
  "metadata": {
    "{KEY}": "{VALUE}"
  },
  "merchantId": "{MERCHANT_ID}",
  "description": "{DESCRIPTION_TEXT}",
  "accountId": "{USER_ID}"
}

In order to fetch invoice by id you must make a GET request to

GET https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}

with the apiKey as query parameter or Bearer <API_KEY> as authorization header.

Parameter Meaning
extId={INVOICE_ID} Invoice ext Id

DELETE /invoices/:extId

Remove invoice.

curl 
  -X DELETE 
  -H "Content-type: application/json" 
  -H "authorization: Bearer <API_KEY>"
  https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}
var request = require('request');

const options = { uri: 'https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}', method: 'DELETE', headers: { 'Content-Type': 'application/json' 'authorization': 'Bearer API_KEY' } }

request(options, function (error, response, body) { if (!error && response.statusCode === 200) { // Handle body } });

RESPONSE

200 Ok
Content-Type: application/json

BODY

{
  "message": "Invoice successfully removed",
  "status": 200,
};

In order to remove invoice by id you must make a GET request to

DELETE https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}

with the apiKey as query parameter or Bearer <API_KEY> as authorization header.

Parameter Meaning
extId={INVOICE_ID} Invoice ext Id

Webhook

You can configure webhook endpoint via the app in merchant account to be notified about events that happen in your invoices. Retrieves the details of an invoice.

Supported events:

pending success failed status of the invoice would send to your webhook endpoint.

{
    invoice: {
        "id": "{INTERNAL_ID}",
        "amount": "{INVOICE_AMOUNT}",
        "currencyCode": "{INVOICE_CURRENCY}",
        "status": "new",
        "extId": "{INVOICE_ID}",
        "createdAt": "{DATE}",
        "link": "https://app.plasmapay.com/business/api/v1/public/pay-invoice/{INVOICE_ID}"
        "metadata": {
            "{KEY}": "{VALUE}"
        },
        "merchantId": "{MERCHANT_ID}",
        "description": "{DESCRIPTION_TEXT}",
        "accountId": "{USER_ID}"
    }
}

Status codes

The PlasmaPay API uses the following error codes:

Code Meaning
200 OK Successful request
201 Created New object saved
204 No content Object deleted
Code Meaning
400 Bad Request -- You have passed a malformed request
401 Unauthorized -- Your API key is incorrect
403 Forbidden -- The resource requested is not available with your permissions
404 Not Found -- The specified resource could not be found
422 Unprocessable Entity -- Your request is invalid
500 Internal Server Error -- We had a problem with our server. Try again later
503 Service Unavailable (Time out) -- The server is overloaded or down for maintenance