Vanilla Integration
Use these integration instructions to add ATLOS to a custom-built website or a website built on top of a CMS that does not have an ATLOS plugin. The integration is very simple. ATLOS can be added to your website with as few as only two lines of JavaScript!
First, if you haven't done so already, sign up to get your merchant ID and the API secret. You only need a web3 compatible wallet, such as Metamask, to sign up. Once you log in, find the merchant ID and the API secret under Settings.
After you get your merchant ID, follow the instructions below:
Step 1: import ATLOS script file
On your checkout page, add the line of code below before the </body> tag:
Step 2: add a payment button
Add a link or a button with the onclick attribute that opens the payment widget:
Substitute the placeholder text with:
merchantId | your merchant ID |
orderId | (optional) any string generated by you used to track the order in your system |
orderAmount | (optional) the order amount, e.g. 1234.56; it must be specified, unless you are using advanced subscriptions |
orderCurrency | (optional) the order currency, e.g. 'USD' |
userName | (optional) the user name to incude in the subscription payment reminders |
userEmail | (optional) if you pass user email, and the user makes a payment with a non-EVM compatible or a native coin, we will send automatic subscription payment reminders to that user |
recurrence | (optional) use this field for basic subscriptions (see below) |
subscription | (optional) use this field for advanced subscriptions (see below) |
resetSubscription | (optional) whether or not to cancel all prior substitutions of this user, defaults to true |
subscriptionId | (optional) if you pass this field, the payment will be credited to that subscription; this ID is generated by ATLOS and it must exist |
postbackUrl | (optional) overrides the postback URL specified in settings in Merchant Panel (useful for custom plugins) |
noBuyCrypto | (optional) causes the widget not to display the "Buy crypto" link |
onSuccess | (optional) a callback function to call when the payment is completed successfully |
onCanceled | (optional) a callback function to call when the payment widget is closed and the payment was not completed |
onCompleted | (optional) a callback function to call when the payment widget is closed and the payment was completed successfully |
language | (optional) language, defaults to browser language |
theme | (optional) light or dark theme, defaults to 'light' |
Live example:
Try it:
Optional: postback
You may set an optional postback (a.k.a. webhook) URL in Settings. Each time a payment transaction has at least one confirmation on blockchain, our system will send a POST request to that URL to notify your backend system of the successful payment.
The POST request will contain the following data in JSON format:
We also recommend that you check the authenticity of the postback message by verifying its HMAC-SHA256 signature. We sign each message using your API secret. You can view your API secret in Settings. We pass the HMAC signature in the Signature header of the POST request.
HMAC signature verification example in NodeJS:
Optional: get transactions API
Sometimes, your system my need to fetch all transactions or specific transactions in a given time range. This may be useful if your system was down for maintenance and needs to catch up with payments that were made while it was down. To get transactions, you may call the following endpoint:
https://atlos.io/api/Transaction/List
Example input:
All fields are optional except for MerchantId. Make sure to pass your API secret in the ApiSecret header.
Example output:
Optional: cancel subscription API
Allows canceling recurring payments by the merchant.
https://atlos.io/api/Subscription/Cancel
Example input:
or:
Basic Subscriptions
You can make any payment a recurring payment by passing the recurrence field to the widget. A basic subscription is a subscription that begins immediately, has a fixed payment amount, and recurs once a day, a week, a month, or a year.
Recurrence time unit values:
atlos.RECURRENCE_NONE | one-time payment, no recurrence |
atlos.RECURRENCE_DAY | daily |
atlos.RECURRENCE_WEEK | weekly |
atlos.RECURRENCE_MONTH | monthly |
atlos.RECURRENCE_YEAR | annually |
Advanced Subscriptions
Advanced subscriptions are recurrent payments that can change over time. You can set the subscription rules with the subscription field:
amount | amount to bill in orderCurrency |
unit | the time unit for the recurrence interval, e.g. month |
interval | (optional) recurrence interval, e.g. 3 months, defaults to 1 |
startInterval | (optional) start date measured in intervals from now, e.g. start in 2 months |
startDate | (optional) start date; the date format must be "YYYY-MM-DD", defaults to now |
paymentCount | (optional) total number of payments for this entry; if omitted, then bills until canceled |
If both, the recurrence and the subscription are specified, the subscription will be used.
If both, the startInterval and the startDate are specified, the startDate will be used.
When using the subscription field, you do not need to specify the orderAmount, as it will be computed automatically. However, if you do specify the orderAmount, it will override the computed subscription amount and your payment will be for the orderAmount.
Example:
Let's create a subscription that has an "introductory rate" of $10.00 for the first 3 months, then changes to $50.00 per month in perpetuity. In addition, starting after 6 months, the user should be billed $100.00 every 6 months in perpetuity.
Invoices, Payment Links, Hosted Checkout
Invoices, also known as a "payment link," or a "hosted checkout," is an alternative way to accept payments from users without integrating the payment widget into your website or app. This can be useful if your application does not have a website, e.g. a chat bot, or if you accept orders over email, by phone, etc.
When you generate an invoice, you receive a payment URL (a payment link). You can either send that payment URL to the user or redirect the user to that URL from your application. Then, the user can complete the payment on that page, which is hosted at atlos.io.
https://atlos.io/api/Invoice/Create
Example input:
Example output:
How to view transactions
View the payments in the Payments section of the Merchant Panel.
How to get help
Need integration support? Contact us at .