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

var request = require('request');

const options = {
  uri: 'https://app.plasmapay.com/business/api/v1/public/ping',
  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

{ 
  "message": "pong ;)"
}

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

var request = require('request');
const options = {
uri: 'https://app.plasmapay.com/business/api/v1/public/ping',
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

{ 
  "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}","email": "{EMAIL}", "phone": "{PHONE}"}'

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}"
"email": "{EMAIL}",
"phone": "{PHONE}"
}
}
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}",
    "email": "{EMAIL}",
    "phone": "{PHONE}"
}

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}	string (required) Four-letter Plasma currency code
amount={INVOICE_AMOUNT}	number (required) Invoice amount
successUri={SUCCESS_URI}	string (optional) Success URI for return user to your success page
failureUri={FAILURE_URI}	string (optional) Failure URI for return user to your failure page
merchantId={INVOICE_MERCHANTID}	string (required) External ID / ID of your order in your DataBase
description={INVOICE_DESCRIPTION}	string (required) Invoice description
accountId={INVOICE_ACCOUNTID}	string (required) External user ID / ID of your user in your DataBase
metadata={INVOICE_METADATA}	string (optional) Key value storage
email={EMAIL}	string (optional) Email of a user
phone={PHONE}	string (optional) The phone number to lookup in E.164 format, which consists of a + followed by the country code and subscriber number - 12 to 24 characters

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}"
      "email": "{EMAIL}",
      "phone": "{PHONE}"
    }
  ],
  "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}"
  "email": "{EMAIL}",
  "phone": "{PHONE}"
}

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

Currency code

Plasma currency code standart.

Each currency supports a resolution of 18 + 18 characters, which allows you to work with complex micro / macro calculations and formulas. Example of supported numbers 11.1111.2222.3333.4444,555566667777888899

Currency	Code
US Dollar	USDP
Euro	EURP
Pound Sterling	GPBP
Chinese Yuan	CYNP
Russian Ruble	RUBP
Czech Republic Koruna	CZKP
Singapore Dollar	SGDP
Hong Kong Dollar	HKDP
South Korean Won	KRW
Hungarian Forint	HUFP
Israeli New Sheqel	ILSP
Norwegian Krone	NOKP
Kenyan Shilling	KESP
Philippine Peso	PHPP
Indian Rupee	INRP
Pakistani Rupee	PKRP
Argentine Peso	ARSP
Australian dollar	AUDP
Belarusian Ruble	BYNP
Indonesian Rupiah	IDRP
Danish Krone	DKKP
Thai Baht	THBP
Mexican Peso	MXNP
Swedish Krona	SEKP
Japanese Yen	JPYP
Chilean Peso	CLPP
Azerbaijani Manat	AZNP
Armenian Dram	AMDP
Brazilian Real	BRLP
Swiss Franc	CHFP
New Taiwan Dollar	TWDP
Nigerian Naira	NGNP
Canadian Dollar	CADP
Turkish Lira	TRYP
Kazakhstani Tenge	KZTP
New Zealand Dollar	NZDP
Malaysian Ringgit	MYRP
Omani Rial	OMRP
Vietnamese Dong	VNDP
South African Rand	ZARP
Polish Zloty	PLNP
Ukraine Hryvnia	UAHP

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}",
    "email": "{EMAIL}",
    "phone": "{PHONE}"
  }
}

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

Business API Reference

Authentication

Invoice

GET /ping

Test your connection using API KEY.

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

POST /invoices

Create invoice.

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

GET /invoices

Fetch list invoices.

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

GET /invoices/:extId

Fetch invoice by id.

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

DELETE /invoices/:extId

Remove invoice.

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

Currency code

Plasma currency code standart.

Webhook

Supported events:

Status codes

Test your connection using `API KEY`.

`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/{INVOICE_ID}`

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

`Supported events:`