Business checkout integration API

Business Integration Required

For your work you will need

  • Create account or login on https://app.plasmapay.com

  • Pass KYC verification on https://app.plasmapay.com/id/profile/identification

  • Create Plasma wallet and activate needed stable currencies on https://app.plasmapay.com/plasma-wallet

  • Go to business dashboard on https://app.plasmapay.com/business

  • Create your first business app

  • Then you can use server-to-server integration using provided API KEY. Go to API Reference Docs.

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

Shell
JS
Shell
curl -X GET -H "content-type: application/json" -H "authorization: Bearer <API_KEY>"
https://app.plasmapay.com/business/api/v1/public/ping
JS
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'

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). If the success message was received you should send this `API_KEY` for all your request to the server. Using an request without `API_KEY` will return an error.

GET /ping

Test your connection using API KEY.

Shell
JS
Shell
curl
-X GET
-H "content-type: application/json"
-H "authorization: Bearer <API_KEY>"
https://app.plasmapay.com/business/api/v1/public/ping
JS
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.

Shell
JS
Shell
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}"}'
JS
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.

Shell
JS
Shell
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}
JS
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.

Shell
JS
Shell
curl
-X GET
-H "Content-type: application/json"
-H "authorization: Bearer <API_KEY>"
https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}
JS
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.

Shell
JS
Shell
curl
-X DELETE
-H "Content-type: application/json"
-H "authorization: Bearer <API_KEY>"
https://app.plasmapay.com/business/api/v1/public/invoices/{INVOICE_ID}
JS
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

Four-letter Plasma currency code, in uppercase. Must be a supported currency.

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