AtomicPay API

Programmatically Secure RESTful Interface

Overview

AtomicPay provides a standard HTTP RESTful interface which enables application developers to programmatically interact with their account in a powerful, yet secure environment. Using the AtomicPay API, clients can create and manage invoices, retrieve transaction information, access features, retrieve real-time currency rates, manage bills, and much more.

Developers do not need to install additional libraries or softwares. Developers may call the API directly over HTTPS via protocol methods GET, PUT, POST and DELETE to perform operations, using the language of their choice.

Concept

API Contract

AtomicPay considers the following types of API changes to be non-breaking and backwards-compatible:

  • exposing a new resource type
  • adding a new method to an existing resource type
  • adding an optional property to an existing resource type
  • adding an optional query parameter to an existing resource method
  • deprecating an existing resource method and providing an alternative

API Keys

Authorization in AtomicPay's API utilizes a set of revocable API Keys. Each API call must be accompanied by an Authorization header that include either a public or private API Key which grants access to perform specific operations.

Key Access

There are two types of Key Access, namely Public Key and Private Key. These keys provide specific access that grant clients the ability to create invoices or manage sensitive account and transaction features.

Types Access Description
public Provides limited access to public methods for generating invoices via client-side integrations.
private Provides full access to manage merchant account which include create, read, update, delete and search actions.

Getting Access

To access any resource URI, an API Key will need to be sent within the HTTP headers Authorization: BASIC {AccountID}:{APIKey} encoded in base64 over SSL along with the API body request. API access require key authentication and you can retrieve the API keys by login to merchant control panel -> API Integration page. If your key becomes compromised, you may revoke the keys by regenerating new set of keys.

HTTP Basic authentication (BA) implementation enforces access controls to AtomicPay resources without requiring cookies, session identifiers, or login pages; rather, HTTP Basic authentication uses Authorization in the HTTP header, removing the need for handshakes.

Making Requests

Requests to the AtomicPay REST API follow the RESTful convention using standard HTTP protocols against AtomicPay resources URI to return JSON formatted responses. IMPORTANT: (AccountID:APIKey) must be encoded in base64

Except for Authorization endpoint, each request MUST include in the HTTP headers:

  • Authorization: BASIC {AccountID}:{APIKey}
  • Content-Type: application/json

To make an API request, simply send an HTTP request with a HTTP method to a resource URI and include in the body JSON parameters of any additional parameters required.

For more information about specific resource URIs, please visit the resource documentation.

Cross-Origin Resource Sharing

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served.

The AtomicPay REST API supports CORS, so that you may send requests directly from the client, however remember to never expose your private key. If your key becomes compromised, you will need to revoke existing keys and generate a new set of API keys.

Code Libraries / Examples

We've released our GitHub open source repository which contains code examples on how to make requests to AtomicPay RESTful API for various programming languages, including C#, Go, Java, JavaScript, NodeJS, PHP, Python, Ruby and Shell scripting. Future updates include easy-to-use code library for each programming languages. View the code libraries and examples at https://github.com/atomicpay/RESTful-API-client

IPN / Webhooks

Instant Payment Notification (IPN) or webhook is a message service that automatically notifies merchants of events related to AtomicPay transactions. Merchants can use it to automate back-end and administrative functions, including automatically fulfilling orders and providing customers with order status.

Why use IPN / Webhooks?

IPN or webhook notifies merchants almost instantly about transaction events, such as:

  • Payments received
  • Changes in invoice status

Merchants can use their backend processes to act based on the information they receive. For example, they can:

  • Update their inventory
  • Email a purchase confirmation
  • Trigger order fulfillment
  • Enable download of digital media
  • Update their customer list
  • Email a shipping notification
  • Update accounting-related information
  • Activate services for customer

IPN / Webhooks Format

Here is an example of the JSON data in the IPN message:

{
"invoice_id":"DBVZzHMxjjfdRZYeignEZC",
"order_id":"1235425",
"fiat_price":"1.00",
"fiat_currency":"USD",
"payment_currency":"BTC",
"payment_rate":"4,192.00",
"payment_address":"bc1qmtyax97phenvvs3sdg5r45kdcphd",
"payment_total":"0.00023855",
"payment_paid":"0.00023855",
"payment_due":"0.00000000",
"payment_txid":"14edecbf114f2b2e73cf7470916122286506de5",
"payment_confirmation":"3",
"status":"confirmed"
"statusException":"null"
}

Best practices for handling IPN / Webhooks

  • IPNs or webhooks are HTTP POST messages sent to the URL provided in the notification_url field when creating the invoice. Please DO NOT rely on whitelisting AtomicPay’s sending IP addresses, as these IP addresses are subject to change without notice.
  • Make sure to use HTTPS for your notification_url
  • AtomicPay does not sign IPNs, so the information in the payload should not be trusted outright
  • The IPN SHOULD ONLY be used as a trigger to verify the status of a specific invoice by using the invoice_id provided in the body of the IPN and sending a GET request to /invoices/:invoice_id. The invoice status "paid" does not represent a payment guarantee, so merchants should only process an order after the corresponding AtomicPay invoice has reached the status "confirmed" or "complete".
  • The AtomicPay server expects a HTTP 200 as a response by your server. Any other HTTP response is considered by AtomicPay as a failed delivery. AtomicPay server will attempt to resend IPNs every 10 minutes until the IPN delivery is either successful or the AtomicPay server stops after 12 hours of retries.

IPN / Webhooks Troubleshooting

In the event that IPNs are not being received or processed as expected, please check the following:

  • Verify that your IPN callback handler at the notification_url is properly receiving POSTs
  • Verify that the POST json data received is properly parsed
  • Verify that your firewall is not blocking POSTs from servers it may not recognize

Resources

Authorization

Resource

Authorization endpoint URI allows client to validate the authentication of API Keys.

Schema
Name Type
code
Internal response code determines Success (200) or Failure (401)
string
message
Response message on success or failure
string

POST /authorization

Validates the authentication of private and public API Keys against the account ID. The required parameters can be obtained by login to merchant control panel -> API Integration page

Endpoint URI https://merchant.atomicpay.io/api/v1/authorization
Required Parameters account_id account_publicKey account_privateKey
cURL Snippet
View Codes @ GitHub
curl -X POST https://merchant.atomicpay.io/api/v1/authorization
-H 'Content-Type: application/json'
-d "{
"account_id": "GJnUGzreherheherYFSweJ",
"account_publicKey": "3453ye4rhgh3ey45y534f",
"account_privateKey": "oifwnijfweg8wg8gikegwe"
}"
On Success
{
"code":"200",
"message":"Authorization Succesful",
}
On Failure
{
"code":"401",
"message":"Authorization failed. Access denied"
}

Account

Resource

Account endpoint URI allows client to retrieve or update account details of merchant's AtomicPay account.

Authorization
Key Access PRIVATE KEY
HTTP Headers Authorization: BASIC base64_encode(AccountID:APIKey)
Content-Type: application/json
cURL Snippet
curl -X METHOD https://merchant.atomicpay.io/api/v1/account
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
Schema
Name Type
account_id
Unique account ID that identifies a merchant
string
account_name
Account name that will display on payment invoices
string
account_username
Username that can be used with PayURL - https://atomicpay.me/{account_username}
string
account_website
Merchant website URL
string
account_email
Merchant email address that will be used for payment and account notifications
string
account_status
Account status. Can be `pending`,`active`,`locked`,`suspended`,`banned`
string
account_fee
Percentage fee payable to AtomicPay for each payment transaction
number
account_credits
Prepaid credits that can be used to offset your usage of AtomicPay
number
account_rateLimit
Account API rate limit per second
number
account_currency
The default FIAT currency for account. ISO 4217 3-character currency code
string
account_cryptocurrency
The default cryptocurrency for payment invoices. The values allowed are based on the account's activated cryptocurrency wallets. Possible values are `BTC`,`BCH`,`BTG`,`LTC`,`DASH`,`GRS`
string
account_expirationTime
The default expiration time period for your payment invoices (in minutes format e.g. 25)
string
account_transactionSpeed
The transaction speed for payment invoice. Can be `high`, `medium`, or `low`. HIGH speed require 1 confirmation, and can be used for digital goods or low-risk items. MEDIUM speed require at least 2 confirmations, and should be used for mid-value items. LOW speed require at least 6 confirmations (averaging 30 mins, depending on selected cryptocurrency), and should be used for high-value items. If missing, then default account transaction speed will apply
string
account_notificationURL
The default notification URL to which AtomicPay sends webhook notifications
string
code
Internal response code determines Success (200) or Failure (4xx). Can be `200`,`400`,`401`,`404`
string
message
Only available for failure response. Determine reasons for failure
string

GET /account

Retrieves account details of merchant's AtomicPay account.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/account
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/account
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"account_id":"GJnUGzreherheherYFSweJ",
"account_name":"AtomicPay Ltd",
"account_username":"atomicswap",
"account_website":"https:\/\/atomicpay.io",
"account_email":"support@atomicpay.io",
"account_status":"active",
"account_fee":"0.9",
"account_credits":"1.17255109",
"account_rateLimit":"30",
"account_currency":"USD",
"account_cryptocurrency":"DASH",
"account_expirationTime":"25",
"account_transactionSpeed":"medium",
"account_notificationURL":"https:\/\/merchant.atomicpay.io"
}
On Failure
{
"code":"401",
"message":"Authorization failed. Access denied"
}

PUT /account

Updates account details of merchant's AtomicPay account.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/account
Optional Parameters account_name account_website account_email account_currency account_cryptocurrency account_expirationTime account_transactionSpeed account_notificationURL
cURL Snippet
View Codes @ GitHub
curl -X PUT https://merchant.atomicpay.io/api/v1/account
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json' -d "{
"account_name": "AtomicPay Ltd",
"account_website": "https://atomicpay.io",
"account_email": "support@atomicpay.io",
"account_currency": "USD"
}"
On Success
{
"code":"200",
"account_id":"GJnUGzreherheherYFSweJ",
"account_name":"AtomicPay Ltd",
"account_username":"atomicswap",
"account_website":"https:\/\/atomicpay.io",
"account_email":"support@atomicpay.io",
"account_status":"active",
"account_fee":"0.9",
"account_credits":"1.17255109",
"account_rateLimit":"30",
"account_currency":"USD",
"account_cryptocurrency":"DASH",
"account_expirationTime":"25",
"account_transactionSpeed":"medium",
"account_notificationURL":"https:\/\/merchant.atomicpay.io"
}
On Failure
{
"code":"400",
"message":"Cryptocurrency type is invalid."
}

Billing

Resource

Billing endpoint URI allows client to retrieve details of a specific bill or a list of bills for the merchant account filtered by query.

Authorization
Key Access PRIVATE KEY
HTTP Headers Authorization: BASIC base64_encode(AccountID:APIKey)
Content-Type: application/json
cURL Snippet
curl -X METHOD https://merchant.atomicpay.io/api/v1/account
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
Schema
Name Type
bill_id
Unique billing ID that identifies a specific bill
string
bill_timestamp
Date and time of bill in Unix timestamp
string
bill_days
Number of days for the billing period
string
bill_month
Month of the billing period
string
bill_year
Year of the billing period
string
bill_credits
Amount of credits used to offset the bill, in USD ($)
number
tx_total
Total number of processed transactions for the bill
number
tx_volume
Total volume of processed transactions for the bill, in USD ($)
number
tx_fee
Total amount of processing fees payable for the bill
number
amount_due
Total amount due for the bill, in USD ($)
number
payment_timestamp
Date and time of payment in Unix timestamp
string
payment_type
The channel used for payment. Default, AtomicPay
string
payment_price
Total amount of payment price
string
payment_currency
Type of currency used for payment
string
payment_rate
The payment rate of currency type against USD ($)
string
payment_address
The wallet address of which the payment is sent to
string
status
The current status of the bill. Can be `pending`,`paid`,`overdue`
string
code
Internal response code determines Success (200) or Failure (4xx). Can be `200`,`401`,`404`
string
message
Only available for failure response. Determine reasons for failure
string
Filter Parameters
Name Type
status
Filter by billing status. Can be `all`,`pending`,`paid`,`overdue`
string
dateStart
Specify a starting date for filtering based on period, in Unix timestamp format
string
dateEnd
Specify an ending date for filtering based on period, in Unix timestamp format
string

GET /billing

Retrieves bills for merchant account filtered by query.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/billing
Filter Parameters status dateStart dateEnd
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/billing?status=all&dateStart=1544796077&dateEnd=1544968877
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":1,
"result":[{
"bill_timestamp":"1544816428",
"bill_id":"1065207821570",
"bill_month":"Nov",
"bill_year":"2018",
"status":"complete"
}]
}
On Failure
{
"code":"404",
"message":"No records found"
}

GET /billing/:bill_id

Retrieves bills for merchant account filtered by query.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/billing/:bill_id
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/billing/1065207821570
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":1,
"result":[{
"bill_timestamp":"1544816428",
"bill_id":"1065207821570",
"bill_days":"30",
"bill_month":"Nov",
"bill_year":"2018",
"bill_credits":"0.00000000",
"tx_total":"3",
"tx_volume":"0.39468914",
"tx_fee":"0.00394689",
"amount_due":"0.00000000",
"payment_timestamp":"1544817311",
"payment_type":"AtomicPay",
"payment_price":"0.01902767",
"payment_currency":"GRS",
"payment_rate":"0.2074",
"payment_address":"grs1qkdut9wzpv7f5und6472x6ftld53jp5ywmrsher",
"status":"complete"
}]
}
On Failure
{
"code":"404",
"message":"Invalid Bill ID"
}

Currencies

Resource

Currencies are fiat currencies supported by AtomicPay

Authorization
Key Access PRIVATE KEY
HTTP Headers Authorization: BASIC base64_encode(AccountID:APIKey)
Content-Type: application/json
cURL Example
curl -X METHOD https://merchant.atomicpay.io/api/v1/currencies
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
Schema
Name Type
currency
ISO 4217 3-character currency code
string
name
English currency name
string
symbol
Display symbol of currency
string
precision
Number of decimal places
number
minimum
Minimum supported value
string
count
Total number of currencies returned in json response
number
code
Internal response code determines Success (200) or Failure (4xx). Can be `200`,`401`,`404`
string
message
Only available for failure response. Determine reasons for failure
string

GET /currencies

Retrieves the list of supported currencies.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/currencies
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/currencies
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":156,
"result":[ {
"currency":"USD",
"name":"US Dollar",
"symbol":"$",
"precision":"2",
"minimum":"0.01"
}... and more
]}
On Failure
{
"code":"401",
"message":"Authorization failed. Access denied"
}

GET /currencies/:currency

Retrieves the specified currency.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/currencies/:currency
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/currencies/USD
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":1,
"result":[ {
"currency":"USD",
"name":"US Dollar",
"symbol":"$",
"precision":"2",
"minimum":"0.01"
}
]}
On Failure
{
"code":"404",
"message":"Currency code is invalid"
}

Invoices

Resource

Invoices are time-sensitive payment requests. An invoice has a fixed price, typically denominated in fiat currency. AtomicPay will automatically convert this fiat amount into cryptocurrency of equivalent value, based on real-time average cryptocurrency market rate, along with an expiration time of 15 minutes.

Authorization
Key Access PRIVATE KEY
HTTP Headers Authorization: BASIC base64_encode(AccountID:APIKey)
Content-Type: application/json
cURL Snippet
curl -X METHOD https://merchant.atomicpay.io/api/v1/currencies
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
Schema
Name Type
invoice_id
Unique invoice ID that identifies a specific invoice
string
invoice_timestamp
Date and time of invoice in Unix timestamp
string
order_id
Merchant can assign internal order ID to an invoice. If used, there should be a direct correlation between an order ID and an invoice ID.
string
order_description
A short order description of the invoice. Not more than 100 characters. Eg. Iced Caffe Latte
string
order_price
Fixed price amount, denominated in `order_currency`
number
order_currency
ISO 4217 3-character currency code. This is the currency associated with `order_price`
string
transaction_speed
The transaction speed for payment invoice. Can be `high`, `medium`, or `low`. HIGH speed require 1 confirmation, and can be used for digital goods or low-risk items. MEDIUM speed require at least 2 confirmations, and should be used for mid-value items. LOW speed require at least 6 confirmations (averaging 30 mins, depending on selected cryptocurrency), and should be used for high-value items. If missing, then default account transaction speed will apply
string
notification_email
Customer email address for payment notifications. This is used for notifying your customer after successful payment
string
notification_url
The notification URL to which AtomicPay sends webhook notifications
string
redirect_url
URL to redirect customer back to merchant website after successful payment. Must include "http://" or "https://" in the url
string
payment_currency
The cryptocurrency which is used to pay for the invoice
string
payment_rate
The cryptocurrency exchange rate used for the invoice, denominated in `order_currency`
string
payment_total
The total amount payable indicated in the smallest possible unit for supported cryptocurrency, denominated in `payment_currency`
string
payment_paid
The amount paid indicated in the smallest possible unit for supported cryptocurrency, denominated in `payment_currency`
string
payment_due
The amount due indicated in the smallest possible unit for supported cryptocurrency, denominated in `payment_currency`
string
payment_address
The cryptocurrency wallet address of which the payment is sent to
string
payment_txid
Transaction ID to identify the transaction in blockchain
string
payment_confirmation
Number of confirmations in blockchain
string
status
The current status of the bill. Can be `new`,`paid`,`confirmed`,`complete`,`expired`,`invalid`
string
statusException
Can be `Underpaid`, `Overpaid`, or `Paid After Expiry`
string
count
Total number of invoices returned in json response
number
code
Internal response code determines Success (200) or Failure (4xx - 500). Can be `200`,`401`,`404`,`500`
string
message
Only available for failure response. Determine reasons for failure
string
Optional Parameters
Name Type
redirect
Specify whether AtomicPay automatically redirect to payment checkout page after successful invoice generation. Default: false. Can be `true` or `false`
boolean
Filter Parameters
Name Type
status
Filter by invoice status. Can be `all`,`new`,`paid`,`confirmed`,`complete`,`expired`,`invalid`,`underpaid`,`overpaid`,`paidafterexpiry`
string
dateStart
Specify a starting date for filtering based on period, in Unix timestamp format
string
dateEnd
Specify an ending date for filtering based on period, in Unix timestamp format
string

GET /invoices

Retrieves invoices for merchant account filtered by query.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/invoices
Filter Parameters status dateStart dateEnd
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/invoices?status=complete&dateStart=1544796077&dateEnd=1544968877
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":2,
"result":[{
"invoice_timestamp":"1544664995",
"invoice_id":"PBbkEsV87eHCwv1mRGyz1",
"status":"complete"
},{
"invoice_timestamp":"1544656118",
"invoice_id":"7sL3EKJ6C7SDfZEQY8CAT",
"status":"complete"
}
]}
On Failure
{
"code":"404",
"message":"No records found"
}

GET /invoices/:invoice_id

Retrieves specified invoice for merchant account

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/invoices/:invoice_id
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/invoices/PBbkEsV87eHCwv1mRGyz1
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":1,
"result":[{
"invoice_timestamp":"1544664995",
"invoice_id":"PBbkEsV87eHCwv1mRGyz1",
"order_id":"12234544",
"order_description":"QuickPay",
"order_price":"5",
"order_currency":"USD",
"transaction_speed":"medium",
"payment_currency":"BTC",
"payment_rate":"3427.74",
"payment_address":"bc1qce6ez07ve67gtwmgfe7aszar2sdv4cg",
"payment_total":"0.04393",
"payment_paid":"0.04393",
"payment_due":"0.00000000",
"payment_txid":"e3304d661af7a0abf5b5e200f667dc98e719e848c5e502e73",
"payment_confirmation":"At least 6",
"notification_email":"customer@atomicpay.io",
"notification_url":"https://merchant.atomicpay.io/test-ipn",
"redirect_url":"https://merchant.atomicpay.io/payInvoices/all/1",
"status":"complete",
"statusException":""
}]
}
On Failure
{
"code":"404",
"message":"No records found"
}

POST /invoices

Creates an invoice for merchant account.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/invoices
Required Parameters order_price order_currency
Optional Parameters redirect order_id order_description notification_email notification_url redirect_url transaction_speed
cURL Snippet
View Codes @ GitHub
curl -X POST https://merchant.atomicpay.io/api/v1/invoices?status=complete&dateStart=1544796077&dateEnd=1544968877
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
-d "{
"order_price": "100.00",
"order_currency": "USD",
"transaction_speed": "medium"
}"
On Success
{
"code":"200",
"invoice_id":"Hsks869sks0Ujsk"
"invoice_url":"https://merchant.atomicpay.io/invoice/GSjsdsjsay4saf/Hsks869sks0Ujsk"
}
On Failure
{
"code":"500",
"message":"Unable to generate invoice"
}

PayURL

Resource

PayURL endpoint URI allows client to retrieve, create, update and delete PayURLs of merchant account.

Authorization
Key Access PRIVATE KEY
HTTP Headers Authorization: BASIC base64_encode(AccountID:APIKey)
Content-Type: application/json
cURL Snippet
curl -X METHOD https://merchant.atomicpay.io/api/v1/payurl
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
Schema
Name Type
url_id
Unique PayURL ID that identifies a specific PayURL
string
url_timestamp
Date and time of PayURL in Unix timestamp
string
url_name
Assign a label name for the PayURL
string
url_expiry
The URL will expire after the preset number of days. Value must be either 0, 1, 7, 15 or 30. Set to 0 to disable expiry.
string
url_status
The current status of the PayURL. Can be `active`,`expired`,`deleted`
string
order_id
Merchant can assign internal order ID to an invoice. If used, there should be a direct correlation between an order ID and an invoice ID.
string
order_description
A short order description of the PayURL. Not more than 100 characters. Eg. Iced Caffe Latte
string
order_price
Fixed price amount, denominated in `order_currency`
string
order_currency
ISO 4217 3-character currency code. This is the currency associated with `order_price`
string
transaction_speed
The transaction speed for payment invoice. Can be `high`, `medium`, or `low`. HIGH speed require 1 confirmation, and can be used for digital goods or low-risk items. MEDIUM speed require at least 2 confirmations, and should be used for mid-value items. LOW speed require at least 6 confirmations (averaging 30 mins, depending on selected cryptocurrency), and should be used for high-value items. If missing, then default account transaction speed will apply
string
notification_email
Customer email address for payment notifications. This is used for notifying your customer after successful payment
string
notification_url
The notification URL to which AtomicPay sends webhook notifications
string
redirect_url
URL to redirect customer back to merchant website after successful payment. Must include "http://" or "https://" in the url
string
count
Total number of PayURLs returned in json response
number
code
Internal response code determines Success (200) or Failure (4xx). Can be `200`,`400`,`401`,`404`
string
message
Only available for failure response. Determine reasons for failure
string
Optional Parameters
Name Type
order_price
New Feature: When creating a PayURL, you may choose not to specify order_price. Doing so, will allow your customer to specify a custom amount to pay when they access the PayURL address.
string
Filter Parameters
Name Type
status
Filter by status. Can be `active`,`deleted`,`expired`. Leave blank to retrieve all PayURLs
string

GET /payurl

Retrieves PayURLs for merchant account filtered by query.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/payurl
Filter Parameters status
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/payurl?status=active
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":5,
"result":[{
"url_timestamp":"1544124542",
"url_name":"Test URL",
"url_id":"621tIISO55ZL",
"url_status":"active"
}...and more
]}
On Failure
{
"code":"404",
"message":"No records found"
}

GET /payurl/:url_id

Retrieves specified PayURL for merchant account.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/payurl/:url_id
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/payurl/621tIISO55ZL
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":1,
"result":[{
"url_timestamp":"1544124542",
"url_name":"Test URL",
"url_id":"621tIISO55ZL",
"url_expiry":"0",
"url_status":"active",
"order_id":"8888",
"order_description":"API",
"order_price":"10",
"order_currency":"USD",
"transaction_speed":"medium",
"notification_email":"customer@atomicpay.io",
"notification_url":"https://merchant.atomicpay.io/test-ipn",
"redirect_url":"https://merchant.atomicpay.io/payInvoices/all/1" }]
}
On Failure
{
"code":"404",
"message":"Invalid URL ID"
}

POST /payurl

Creates a PayURL for merchant account.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/payurl
Required Parameters url_name order_currency transaction_speed url_expiry
Optional Parameters order_id order_price order_description notification_email notification_url redirect_url
cURL Snippet
View Codes @ GitHub
curl -X POST https://merchant.atomicpay.io/api/v1/payurl
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
-d "{
"url_name": "Test PayURL",
"url_expiry": "0"
"order_id": "12345"
"order_description": "API"
"order_price": "10.00",
"order_currency": "USD",
"transaction_speed": "high"
"notification_email": "customer@atomicpay.io"
"notification_url": "https://merchant.atomicpay.io/test-ipn"
"redirect_url": "https://merchant.atomicpay.io"
}"
On Success
{
"code":"200",
"url_timestamp":1545003122,
"url_name":"Test PayURL",
"url_id":"tFta4yeC65yo",
"url_expiry":"0",
"url_status":"active",
"order_id":"12345",
"order_description":"Testing the API",
"order_price":"10",
"order_currency":"USD",
"transaction_speed":"high",
"notification_email":"customer@atomicpay.io",
"notification_url":"https://merchant.atomicpay.io/test-ipn",
"redirect_url":"https://merchant.atomicpay.io"
}
On Failure
{
"code":"400",
"message":"Invalid parameters"
}

PUT /payurl/:url_id

Updates a PayURL for merchant account.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/payurl/:url_id
Optional Parameters url_name order_id order_price order_currency order_description transaction_speed url_expiry notification_email notification_url redirect_url
cURL Snippet
View Codes @ GitHub
curl -X PUT https://merchant.atomicpay.io/api/v1/payurl/tFta4yeC65yo
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
-d "{
"url_name": "Test URL",
"url_expiry": "7"
"order_id": "8888"
"order_description": "API"
"order_price": "5.00",
"order_currency": "USD",
"transaction_speed": "medium"
"notification_email": "support@atomicpay.io"
"notification_url": "https://merchant.atomicpay.io/test-ipn2"
"redirect_url": "https://atomicpay.io/global/en"
}"
On Success
{
"code":"200",
"url_timestamp":1545004719,
"url_name":"Test URL",
"url_id":"tFta4yeC65yo",
"url_expiry":"7",
"url_status":"active",
"order_id":"8888",
"order_description":"API",
"order_price":"5",
"order_currency":"USD",
"transaction_speed":"medium",
"notification_email":"support@atomicpay.io",
"notification_url":"https://merchant.atomicpay.io/test-ipn2",
"redirect_url":"https://atomicpay.io/global/en"
}
On Failure
{
"code":"404",
"message":"Invalid URL ID"
}

DELETE /payurl/:url_id

Deletes a PayURL for merchant account.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/payurl/:url_id
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X DELETE https://merchant.atomicpay.io/api/v1/payurl/tFta4yeC65yo
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"url_id":tFta4yeC65yo,
"url_status":"deleted"
}
On Failure
{
"code":"404",
"message":"Invalid URL ID"
}

Rates

Resource

Rates endpoint URI allows client to retrieve real-time exchange rates between a base fiat currency and merchant's supported cryptocurrencies.

Authorization
Key Access PRIVATE KEY
HTTP Headers Authorization: BASIC base64_encode(AccountID:APIKey)
Content-Type: application/json
cURL Snippet
curl -X METHOD https://merchant.atomicpay.io/api/v1/rates
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
Schema
Name Type
base_currency
ISO 4217 3-character fiat currency code
string
pair
Base fiat currency against cryptocurrency. Eg. BTC_USD
string
rate
Base fiat currency units per cryptocurrency
string
count
Total number of rate pairs returned in json response
number
code
Internal response code determines Success (200) or Failure (4xx). Can be `200`,`400`,`401`
string
message
Only available for failure response. Determine reasons for failure
string

GET /rates/:base_currency

Retrieves the real-time exchange rate of merchant's supported cryptocurrencies, denominated in the specified base fiat currency. Merchant account must have at least one activated cryptocurrency wallet.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/rates/:base_currency
Parameters none
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/rates/usd
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":2,
"result":[{
"pair":"BTC_USD",
"rate":3259.33357039262
},{
"pair":"LTC_USD",
"rate":25.9611459748841850454
}
]}
On Failure
{
"code":"400",
"message":"No active cryptocurrency wallets"
}

Transactions

Resource

Transactions endpoint URI allows client to retrieve a list of transactions for the merchant account filtered by query.

Authorization
Key Access PRIVATE KEY
HTTP Headers Authorization: BASIC base64_encode(AccountID:APIKey)
Content-Type: application/json
cURL Example
curl -X METHOD https://merchant.atomicpay.io/api/v1/transactions
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
Schema
Name Type Read-Only
invoice_id
Unique invoice ID that identifies a specific invoice
string
invoice_timestamp
Date and time of invoice in Unix timestamp
string
payment_currency
Type of currency used for payment
string
payment_txid
Transaction ID to identify transaction in blockchain
string
status
The current status of the bill. Can be `new`,`paid`,`confirmed`,`complete`
string
count
Total number of transactions returned in json response
number
code
Internal response code determines Success (200) or Failure (4xx). Can be `200`,`401`,`404`
string
message
Only available for failure response. Determine reasons for failure
string
Filter Parameters
Name Type
crypto_code
Filter by cryptocurrency. Can be `BTC`,`BCH`,`BTG`,`LTC`,`DASH`,`GRS`. Leave blank to retrieve all cryptcurrencies
string
dateStart
Specify a starting date for filtering based on period, in Unix timestamp format
string
dateEnd
Specify an ending date for filtering based on period, in Unix timestamp format
string

GET /transactions

Retrieves transactions for merchant account filtered by query.

Key Access PRIVATE KEY
Endpoint URI https://merchant.atomicpay.io/api/v1/transactions
Filter Parameters crypto_code dateStart dateEnd
cURL Snippet
View Codes @ GitHub
curl -X GET https://merchant.atomicpay.io/api/v1/transactions?crypto_code=BTC&dateStart=1544796077&dateEnd=1544968877
-H 'Authorization: Basic RlhONXpqVHdmRFlHQ1haYmxRVkGeTU='
-H 'Content-Type: application/json'
On Success
{
"code":"200",
"count":2,
"result":[{
"invoice_timestamp":"1544664995",
"invoice_id":"PBef547ererCwv1mRGy1",
"payment_currency":"BTC",
"payment_txid":"e3304d6herherhherherherc40d8629db125227",
"status":"complete"
}...and more
]}
On Failure
{
"code":"404",
"message":"No records found"
}