Overview
Create a payment gateway for cryptocurrencies. To bridge the gap between cryptocurrency owners, who are looking for ways to use their coins for purchasing goods and services, and merchants, that can easily utilize the benefits of blockchain to grow their businesses.
Goals
- BTC, ETH, ADA, and XRP: The system must support these common cryptocurrencies.
- The system has higher security and reliability requirements: Because every transaction has financial impacts on the users and the business. Security should be of a high stake because it is very hard to gain trust and super easy to get it lost.
- Traffic and Scalability:< Speed up the payment process.
- Backup payment processors:< Handle retries and backup Payment, the System and the log files.
- Operations and customer support: Easy to operate and support when the customers need.
- Analytics:< To support improve system architecture and answer any question of the marketing team or the manager.
REST API
You must send an authorization header with every request (Except for Public APIs). App token will be shown after you create an app.
Using the HTTP Authorization header like this:
Authorization: Token <app_token>
The tokens can be generated on the payment system's console. The merchant will need to define the application name when generating a new token. It will help the merchant can filter reports better.
Response format
- Format: JSON standard
- Timezone: Coordinated Universal Time (UTC), UTC +0 with ISO 8601 format.
- Support UTF-8 encoding: YES
- Number format in JSON: Double value will be return 1.1 or "1.1"
Environments
| Name | Link (Notify if they are updated) |
|---|---|
| Live (Mainnet) | https://payment.act-tech.io/ |
| Live (Mainnet) | https://payment-sandbox.act-tech.io/ |
Error code
| Error Code | HTTP Status | Message | Note |
|---|---|---|---|
| 1000 | 401 | Missing Authorization Header | |
| 1001 | 401 | Invalid Authorization Header | |
| 4000 | 400 | Please check the parameters again | Default |
| 4001 | 400 | Price amount is required | |
| 4002 | 400 | Price currency is required | |
| 4220 | 422 | The data is invalid | Default |
Status code
| HTTP Status | Description |
|---|---|
| 200 (OK) | API response success |
| 201 (Created) | Record is created |
| 401 (Unauthorized) | API credentials are not valid |
| 404 (Not Found) | Page, action not found |
| 404 (Not Found) | Record not found |
| 400 (Bad Request) | Missing params |
| 422 (Unprocessable Entity) | The value of params is invalid |
| 500 (Internal Server Error) | Something wrong in servers |
| 429 (Too Many Requests) | API request limit is exceeded |
Response example:
JSON
{
"message": "The order is not found",
"error_code": 404
}
Merchant API
Create Order
| Method | HTTP request | Description |
|---|---|---|
URLs relative to https://<Server URL>/api/v1/, unless otherwise noted |
||
| post | POST /orders | Create Order |
Parameters:
| Parameter name | Value | Description |
|---|---|---|
| price_amount Or invoice_price_amount | double | The price set by the merchant. Example: 1050.99 |
| price_currency Or invoice_price_currency | string | Currency code which defines the currency in which you wish to price your merchandise. Eg, USD, JPY (It also can be BTC, ADA) |
| Optional query parameters | ||
| order_id | string | Merchant's custom order ID |
| title | string | Max 150 characters. Order title |
| description | string | More details about this order. Max 500 characters |
| callback_url | string | Send an automated message to Merchant URL when order status is changed or the number of confirmation is enough. The data is the same order/invoice response. |
| success_url | string | Redirect to Merchant URL after successful payment |
| cancel_url | string | Redirect to Merchant URL when buyer cancels the order |
| pay_currency | string | Cryptocurrency code which will be paid. Eg, BTC, ADA. If you want the user to process payment on your system, please send this param |
Response
If successful, this method returns a response body with the following structure
{
"id": 53,
"status": "unconfirmed",
"invoice_price_currency": "USD",
"invoice_price_amount": 0.5,
"wallet_address": "367f4YWz1VCFaqBqwbTrzwi2b1h2U3w1AF",
"invoice_created_at": "2018-11-15T05:49:36.553+07:00",
"order_id": "ORDER-1539318129916178-4",
"token": "DkNB5m5a7VZySCWr2jZfEw",
"payment_url": "https://.../invoices/f7eb404c-...-be1fd9bbc464",
"title": "Order 4",
"description": "1 × Espresso Con Panna",
"pay_amount": 16.26,
"pay_currency": "ADA",
"wallet_address": "Ae2tdPwUPEZ9Z3...UHZdqHMXUvHMp5i5SE5D2YxkB",
"qr_code_url": "https://paym...ices/qr_code/Ae5D2xkB",
"invoice_confirmed_at": null,
"invoice_received_amount": 0,
}
| Response data | Value | Description |
|---|---|---|
| payment_url | String URL | The URL to payment when using ACT-Payment screen UI |
| wallet_address | String URL | The wallet address which will be received payment amount. |
| qr_code_url | String URL | The QR code URL of wallet address |
| status | string | Status of order (invoice) |
| pay_amount | double | The cryptocurrency amount which the buyer needs to pay |
| invoice_created_at | DateTime | The time when the order (invoice) was created |
| token | string | The token is used when need to verify the payment again. Maybe the merchants’ systems don’t need to store it. |
Create Order Status
{
"id":53,
"status":"paid",
"invoice_price_currency":"USD",
"invoice_price_amount":0.5,
"created_at":"2018-11-15T05:49:36.553+07:00",
"order_id":"ORDER-1539318129916178-4",
"token":"DkNB5m5a7VZySCWr2jZfEw",
"payment_url":"https://.../invoices/f7eb404c-...-be1fd9bbc464",
"title":"Order 4",
"description":"1 × Espresso Con Panna",
"pay_amount":16.26,
"pay_currency":"ADA",
"wallet_address":"Ae2tdPwUPEZ9Z3...UHZdqHMXUvHMp5i5SE5D2YxkB",
"qr_code_url":"https://paym...ices/qr_code/Ae5D2xkB",
"invoice_confirmed_at": "2018-11-15T05:55:36.553+07:00",
"invoice_received_amount":16.3
}
| Method | HTTP Request | Description |
|---|---|---|
URIs relative to https://<Server URL>/api/v1/, unless otherwise noted |
||
| get | GET /orders/:id |
Get Order detail |
Parameter
| Parameter name | Value | Description |
|---|---|---|
| Required parameters | ||
| id | integer | Order ID |
Reponsise
If successful, this method returns a response body with the following structure
| Response data | Value | Description |
|---|---|---|
| nvoice_confirmed_at | DateTime | The time when the blockchain network confirmed the transaction (Normally 6 blocks for a Bitcoin transaction) |
| invoice_received_amount | Double | The real amount which the system |
| was received for this order (invoice). |
Reporting API
List the orders
{
"message":"Success",
"data": [,
{
"id":6,
"status":"paid",
"invoice_price_currency":"USD",
"invoice_price_amount":1.0,
"created_at":"2018-10-23T16:33:24.485+09:00",
"order_id":"ORDER-1540280002934932-6",
"token":"uwxHYa4Q4Kg-UR-0UCHZ3w",
"payment_url":"https://payment.act-te...8b3-8655-69ee5542fc1a",
"title":"Order #6",
"description":"1 × 1 × Brewed Coffee",
"pay_amount":0.0001544,
"pay_currency":"BTC",
"wallet_address":"2MvvXu8JdcZdo9pAkw2fMvAZxrmTbhrviap",
"wallet_url":"https://payment.act-t...cZdo9pAkw2fMvAZxrmTbhrviap",
},
{ "id":5,
"status":"expired",
"invoice_price_currency":"USD",
"invoice_price_amount":3.0,
"created_at":"2018-10-23T16:17:59.203+09:00",
"order_id":"ORDER-1540279075370022-5",
"token":"B5CO-64aXVk_vb-Op3QK5w",
"payment_url":"https://payment.act-tech...0b-45d1-b919-3f9110032efd",
"title":"Order #5",
"description":"1 × Caramel Macchiato",
"pay_amount":0.0004635,
"pay_currency":"BTC",
"wallet_address":"2N47sHtU9wewejLGh3Hv8H89gNX53xNa4PH",
"wallet_url":"https://payment.act-tech...9wewejLGh3Hv8H89gNX53xNa4PH",
}
]
}
| Method | HTTP request | Description |
|---|---|---|
URIs relative to https://<Server URL>/api/v1/, unless otherwise noted |
||
| get | GET /report/orders | Report for orders |
Parameter
| Parameter name | Value | Description |
|---|---|---|
| Optional query parameters | ||
| date_range | string | See Date range value |
| from | date | Start date range with format YYYY-MM-DD. It can’t be greater today. |
| to | date | End date range with format YYYY-MM-DD. It must be greater from value and can’t be greater today. |
| price_currency | string | Filter orders which use price_currency |
| pay_currency | string | Cryptocurrency code: BTC or ADA. Filter orders which were paid with pay_currency |
| status | string | Filter orders with status. |
| amount | double | Filter orders which amount |
| keyword | string | Search title and description or wallet address |
| Operations | ||
| = | The content of a string or boolean is equal to the other or a value is equal to another. | |
| < | A value is less than another | |
| <= | A value is less than or equal to another. | |
| > | A value is later than another. | |
| >= | A value is later than or equal to another. | |
| and | Return items that match both clauses. | |
| or | Return items that match either clause. |
Date range value
| Value | Description |
|---|---|
| TODAY | Today only |
| YESTERDAY | Yesterday only. |
| LAST_7_DAYS | The last 7 days not including today. |
| THIS_MONTH | All days in the current month. |
| LAST_MONTH | All days in the previous month. |
| ALL_TIME | The entire available time range. |
| CUSTOM_DATE | A custom date range. Use with parameters from and to |
| LAST_14_DAYS | The last 14 days not including today. |
| LAST_30_DAYS | The last 30 days not including today. |
Response
If successful, this method returns a response body with the result
Public API
Current exchange rates for Merchants. This endpoint is public, authentication is not required
List the supported coins
| Method | HTTP request | Description |
|---|---|---|
| URIs relative to https:// |
||
| get | GET /listings | Displays all supported coins |
Response
If successful, this method returns a response body with the result
Example
Get Exchange Rate
| Method | HTTP request | Description |
|---|---|---|
| URIs relative to https:// |
||
| get | GET /rates/:from/:to |
Get an exchange rate |
{
"from":String,
"to":String,
"rate":double,
"time":DateTime,
}
Prameters
| Parameter name | Value | Description |
|---|---|---|
| Required parameters | ||
| from | string | ISO Symbol. Example: JPY, USD |
| to | string | ISO Symbol. Example: BTC, ADA |
| Option parameters | ||
| source | string | The source to get the exchange rate data. Default: Cryptocompare |
Response
If successful, this method returns a response body with the result
Example
Real-Time Notifications
{
"id":12,
"order_id":"ORDER-1545492017181432-35",
"token":"kmeJKu7LHOkH82XDEFW89Q",
"status":"paid",
"invoice_received_amount":"0.0007723",
}
Data post callback
If successful, the system will post to callback URL with data
| Name | Description |
|---|---|
| id | The invoice ID on the payment system |
| order_id | The invoice ID on the merchant system |
| token | The invoice token. It helps to avoid invalid data |
| status | The new status of the invoice |
| invoice_received_amount | The received amount |