API reference

API URLs

API Base URLs for the available environments are as follows:

• Production: https://stargate.montonio.com/api
• Sandbox: https://sandbox-stargate.montonio.com/api

Authentication

The Stargate API uses JWT (JSON Web Tokens) for authentication. GET endpoints require a JWT in the Authorization header. POST endpoints require that the request payload is the JWT and the token itself contains the original request data.

Both GET and POST JWTs must contain your Access Key and be signed with your Secret Key using HMAC SHA256 (HS256). Read more about API keys here.

The exact implementation of how to generate the JWT varies by programming language and you can see some examples on the code panel of some of the guides. We recommend using popular community maintained libraries for generating and verifying JWTs.

To learn more about JWTs, find libraries for your programming language, or to debug and verify your JWTs, visit jwt.io.

JWT headers

Key	Required	Type	Description
alg	yes	string	Must be set to HS256
typ	yes	string	Must be set to JWT

JWT payload

Here is the minimum required payload for all requests:

Key	Required	Type	Description
accessKey	yes	string	Your Access Key obtained from the Partner System.
exp	yes	number	Expiration time of the token in Unix time. We recommend setting this to 1 hour from the time of issuing the token.

JavaScript

/**
 * We recommend using the jsonwebtoken package to generate
 * Json Web Tokens. You can install it with npm:
 * > npm install jsonwebtoken
 * More information can be found at
 * https://www.npmjs.com/package/jsonwebtoken
 */

import jwt from 'jsonwebtoken';

const payload = {
    accessKey: 'MY_ACCESS_KEY'
};

const authHeader = jwt.sign(
    payload,
    'MY_SECRET_KEY',
    { algorithm: 'HS256', expiresIn: '1h' }
);

console.log(authHeader);
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJNWV9BQ0NFU1NfS0VZIiwiaWF0IjoxNjc1OTM4NjM3LCJleHAiOjE2NzU5NDIyMzd9.f-wXP8t5HGhr5XKAl3eCeWbHnY3SO9DcY5WiWo06-uQ

PHP

<?php
/**
 * We recommend using Firebase's php-jwt package to verify
 * Json Web Tokens. You can install it with composer:
 * > composer require firebase/php-jwt
 * More information can be found at
 * https://github.com/firebase/php-jwt
 */

// Should be loaded only once in the app, check composer docs for the specific framework you are using
require __DIR__ . '/vendor/autoload.php';

use \Firebase\JWT\JWT;

$payload = [
    'accessKey' => 'MY_ACCESS_KEY',
    'iat'        => time(),
    'exp'        => time() + (60 * 60)
];

$token = JWT::encode($payload, 'MY_SECRET_KEY', 'HS256');
// var_dump($token);
// eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NLZXkiOiJNWV9BQ0NFU1NfS0VZIiwiaWF0IjoxNjc2MDQ1NTg5LCJleHAiOjE2NzYwNDkxODl9.9kz7LBZZVJrJbSO_42NTTg1Wg4HEP01cqOw0IzQ0nXU

Python

'''
We recommend using the PyJWT package to generate
Json Web Tokens. You can install it with pip:
> pip3 install PyJWT datetime
More information can be found at
https://pyjwt.readthedocs.io/en/latest/
'''
import jwt
from datetime import datetime, timedelta, timezone

payload = {
    'accessKey': 'MY_ACCESS_KEY',
    'iat': datetime.now(timezone.utc),
    'exp': datetime.now(timezone.utc) + timedelta(hours=1)
}

auth_header = jwt.encode(
    payload,
    'MY_SECRET_KEY',
    algorithm='HS256'
)

print(auth_header)
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3Nfa2V5IjoibWVyY2hhbnRfYWNjZXNzX2tleSIsImlhdCI6MTYwMzcxMTQ3NSwiZXhwIjoxNjAzNzE1MDc1fQ.UYwRQXykcIVNzIjni3icf_FBbxSXZ_m-2SsFfz3zjBs

API endpoints

Get available payment methods

The endpoint allows you to fetch all enabled payment methods for your store. This allows you to display the methods in your checkout and to let the customer choose their preferred payment method.

In addition to the overall payment methods, the endpoint also returns a list of additional options for that method. For example, paymentInitiation will have a list of available banks, so that you can let the customer make their bank selection already in your checkout.

Endpoint path

GET /stores/payment-methods

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Example request

curl -X GET \
  'https://stargate.montonio.com/api/stores/payment-methods' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJNWV9BQ0NFU1NfS0VZIiwiaWF0IjoxNjc1OTM4NjM3LCJleHAiOjE2NzU5NDIyMzd9.f-wXP8t5HGhr5XKAl3eCeWbHnY3SO9DcY5WiWo06-uQ'

Example response

Show / Hide Response Data

{
    "id": "0bafe86b-c5cf-4c88-ba28-484a8585f0f4",
    "name": "Montonio Store",
    "paymentMethods": {
        "blik": {
            "processor": "blik",
            "logoUrl": "https://public.montonio.com/images/logos/blik.png"
        },
        "cardPayments": {
            "processor": "adyen",
            "logoUrl": "https://public.montonio.com/images/logos/visa-mc-ap-gp.png",
            "requiredToBeEnabled": true
        },
        "mobilePay": {
            "processor": "adyen",
            "logoUrl": "https://public.montonio.com/images/logos/mobilepay.png",
            "requiredToBeEnabled": true
        },
        "bnpl": {
            "processor": "inbank",
            "logoUrl": "https://public.montonio.com/images/logos/inbank_bnpl.png"
        },
        "hirePurchase": {
            "processor": "inbank",
            "logoUrl": "https://public.montonio.com/images/logos/inbank_hire_purchase.png"
        },
        "paymentInitiation": {
            "processor": "montonio",
            "setup": {
                "EE": {
                    "supportedCurrencies": [
                        "EUR"
                    ],
                    "paymentMethods": [
                        {
                            "code": "HABAEE2X",
                            "name": "Swedbank Eesti",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/swedbank.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "EEUHEE2X",
                            "name": "SEB Eesti",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/seb.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "LHVBEE22",
                            "name": "LHV",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/lhv.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "RIKOEE22",
                            "name": "Luminor Eesti",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/luminor.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "EKRDEE22",
                            "name": "Coop Pank",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/coop.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "PARXEE22",
                            "name": "Citadele Eesti",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/citadele.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "RVUALT2V",
                            "name": "Revolut",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/revolut.png",
                            "supportedCurrencies": [
                                "EUR",
                                "PLN"
                            ]
                        }
                    ]
                },
                "FI": {
                    "supportedCurrencies": [
                        "EUR"
                    ],
                    "paymentMethods": [
                        {
                            "code": "OKOYFIHH",
                            "name": "OP",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/op.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "NDEAFIHH",
                            "name": "Nordea",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/nordea.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "DABAFIHH",
                            "name": "Danske Bank",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/danske.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "ITELFIHH",
                            "name": "Säästöpankki",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/saastopankki.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "POPFFI22",
                            "name": "POP Pankki",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/pop.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "ITELFIHH",
                            "name": "Oma Säästöpankki",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/omasp.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "SBANFIHH",
                            "name": "S-Pankki",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/s-pankki.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "AABAFI22",
                            "name": "Alandsbanken",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/alandsbanken-fi.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "RVUALT2V",
                            "name": "Revolut",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/revolut.png",
                            "supportedCurrencies": [
                                "EUR",
                                "PLN"
                            ]
                        }
                    ]
                },
                "LV": {
                    "supportedCurrencies": [
                        "EUR"
                    ],
                    "paymentMethods": [
                        {
                            "code": "HABALV22",
                            "name": "Swedbank Latvija",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/swedbank.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "UNLALV2X",
                            "name": "SEB Latvija",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/seb.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "PARXLV22",
                            "name": "Citadele Latvija",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/citadele.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "RIKOLV2X",
                            "name": "Luminor Latvija",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/luminor.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "RVUALT2V",
                            "name": "Revolut",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/revolut.png",
                            "supportedCurrencies": [
                                "EUR",
                                "PLN"
                            ]
                        }
                    ]
                },
                "LT": {
                    "supportedCurrencies": [
                        "EUR"
                    ],
                    "paymentMethods": [
                        {
                            "code": "HABALT22",
                            "name": "Swedbank Lietuva",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/swedbank.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "CBVILT2X",
                            "name": "SEB Lietuva",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/seb.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "AGBLLT2X",
                            "name": "Luminor Lietuva",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/luminor.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "CBSBLT26",
                            "name": "Šiaulių bankas",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/siauliu.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "MDBALT22",
                            "name": "Medicinos bankas",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/medicinos.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "INDULT2X",
                            "name": "Citadele Lietuva",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/citadele.png",
                            "supportedCurrencies": [
                                "EUR"
                            ]
                        },
                        {
                            "code": "RVUALT2V",
                            "name": "Revolut",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/revolut.png",
                            "supportedCurrencies": [
                                "EUR",
                                "PLN"
                            ]
                        }
                    ]
                },
                "PL": {
                    "supportedCurrencies": [
                        "PLN"
                    ],
                    "paymentMethods": [
                        {
                            "code": "BPKOPLPW",
                            "name": "PKO Bank Polski",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/pko-polski.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "PKOPPLPW",
                            "name": "Bank Pekao",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/pekao.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "BREXPLPW",
                            "name": "mBank",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/mbank.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "WBKPPLPP",
                            "name": "Santander",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/santander.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "INGBPLPW",
                            "name": "Ing",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/ing.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "ALBPPLPW",
                            "name": "Alior",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/alior.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "PPABPLPK",
                            "name": "BNP Paribas",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/bnp-paribas.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "BIGBPLPW",
                            "name": "Millennium Bank",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/millennium.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "IBNKPAPA",
                            "name": "Inteligo",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/inteligo.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "AGRIPLPR",
                            "name": "Crédit Agricole",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/credit-agricole.png",
                            "supportedCurrencies": [
                                "PLN"
                            ]
                        },
                        {
                            "code": "RVUALT2V",
                            "name": "Revolut",
                            "logoUrl": "https://public.montonio.com/images/aspsps_logos/revolut.png",
                            "supportedCurrencies": [
                                "EUR",
                                "PLN"
                            ]
                        }
                    ]
                }
            }
        }
    }
}

Get Order by UUID

The endpoint returns details about the order and its paymentStatus. You can use it to double-check the status of the order and its payment. In order to use this endpoint, you need to save the Order UUID returned by the POST /orders endpoint in your database.

Endpoint path

GET /orders/:orderUuid

Authentication

Refer to the Authentication section. Follow instructions for GET endpoints.

Headers

Key	Required	Value
Authorization	yes	Bearer [your_token]

Example Request

curl -X GET \
  'https://stargate.montonio.com/api/orders/0ac2124d-9f8e-4a29-816d-7eef5b9bb0fd' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJNWV9BQ0NFU1NfS0VZIiwiaWF0IjoxNjc1OTM4NjM3LCJleHAiOjE2NzU5NDIyMzd9.f-wXP8t5HGhr5XKAl3eCeWbHnY3SO9DcY5WiWo06-uQ'

Example Response

Show / Hide Response Data

{
    "uuid": "0ac2124d-9f8e-4a29-816d-7eef5b9bb0fd",
    "paymentStatus": "PARTIALLY_REFUNDED",
    "locale": "et",
    "merchantReference": "MY-ORDER-ID-123",
    "merchantReferenceDisplay": "MY-ORDER-ID-123",
    "merchantReturnUrl": "https://mystore.com/payment/return",
    "merchantNotificationUrl": "https://mystore.com/payment/notify",
    "grandTotal": "100.00",
    "currency": "EUR",
    "paymentMethodType": "cardPayments",
    "paymentIntents": [
        {
            "uuid": "293513c0-66b1-401a-8afa-75e1f5714516",
            "paymentMethodType": "cardPayments",
            "paymentMethodMetadata": {},
            "amount": "100.00",
            "currency": "EUR",
            "status": "PAID",
            "serviceFee": "3.15", // Montonio's transaction processing fee. Initially null during order creation, populated after payment processing completes
            "serviceFeeCurrency": "EUR",
            "createdAt": "2023-05-23T08:22:53.899Z"
        }
    ],
    "refunds": [
        {
            "uuid": "92b11684-319a-4cce-92f5-56d348aa986a",
            "amount": "25",
            "status": "SUCCESSFUL",
            "currency": "EUR",
            "createdAt": "2023-05-23T08:37:55.534Z",
            "type": "PARTIAL_REFUND"
        },
        {
            "uuid": "8453465a-a9d8-469e-a838-5b2b5b20f429",
            "amount": "25",
            "status": "SUCCESSFUL",
            "currency": "EUR",
            "createdAt": "2023-05-23T11:03:04.954Z",
            "type": "PARTIAL_REFUND"
        }
    ],
    "availableForRefund": 50,
    "isRefundableType": false, // will be true if you enabled refunds in montonio (and the user paid with a refundable method)
    "lineItems": [
        {
            "name": "Hoverboard",
            "quantity": 1,
            "finalPrice": 100
        }
    ],
    "billingAddress": {
        "firstName": "CustomerFirst",
        "lastName": "CustomerLast",
        "email": "test@montonio.com",
        "phoneNumber": null,
        "phoneCountry": null,
        "addressLine1": "Kai 1",
        "addressLine2": null,
        "locality": "Tallinn",
        "region": null,
        "country": "EE",
        "postalCode": "10111",
        "companyName": null,
        "companyLegalName": null,
        "companyRegCode": null,
        "companyVatNumber": null
    },
    "shippingAddress": {
        "firstName": "CustomerFirstShipping",
        "lastName": "CustomerLastShipping",
        "email": "test@montonio.com",
        "phoneNumber": null,
        "phoneCountry": null,
        "addressLine1": "Kai 1",
        "addressLine2": null,
        "locality": "Tallinn",
        "region": null,
        "country": "EE",
        "postalCode": "10111",
        "companyName": null,
        "companyLegalName": null,
        "companyRegCode": null,
        "companyVatNumber": null
    },
    "expiresAt": null,
    "createdAt": "2023-05-23T08:22:53.879Z",
    "storeName": "My Store Name",
    "businessName": "My Business Name",
    "paymentUrl": null // will be URL when order is PENDING
}

The values for paymentStatus are described here - Lifecycle of an Order, and the values for refunds’ status are described here - Lifecycle of a Refund.

Create Order

Endpoint path

POST /orders

Request, response and authentication

See Create and validate an order -> Creating an order for details.

Create Refund

Endpoint path

POST /refunds

Request, response and authentication

See Refund an Order for details.

Create Payment Link

Endpoint path

POST /payment-links

Request, response and authentication

See Payment links for details.

Create Session

Endpoint path

POST /sessions

Authentication

Refer to the code example in the Embedded Cards in checkout guide or to the Authentication section above (follow instructions for POST endpoints). The generated token must be included in the data field of the request body.

Request body

The request body is a JSON object with a single field data, which contains the generated authentication token.

Example request

curl -X POST \
  'https://stargate.montonio.com/api/sessions' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NLZXkiOiIwMzA2M2I4Yi0wMjliLTQ5NTMtYTA0ZC02ZDNkNjRhZDdkNmUiLCJleHAiOjE3NTczNDM2NDl9.4mEIutn-C2kU4rEGS5zs1jlxjebvb0WzmsIFWAdbUIw"
  }'

Example response

{
    "uuid": "087a9fb5-7a85-4e1e-b3f7-2546faab9a97"
}