Pay with Terra API
Auth
For interacting with API you need to use your personal API key (token). You can get it from your account dashboard.
There are 3 ways how you can pass API token while making requests (choose one):
-
Request header:
Authorization: Bearer YOUR_API_TOKEN
- POST field:
api_token
- GET parameter:
api_token
Create order
https://paywithterra.com/api/order/create
Create an order to look for transaction on the blockchain. Typically this called after a user has created an order, and youβre awaiting payment.
Parameters
{
"address": "terra14wvwnyjgsljdps5g3uy9jp2veysd4psu8aytk7",
"memo": "#order-1234",
"webhook": "http://your-website.com/webhook-pay-complete",
"webhook_json": false,
"amount": 9990000,
"denom": "uusd",
"return_url": null
}
Description
Response example
{
// Store uuid value for later using in "Second check"
"uuid": "345a126b-f22c-42ff-935b-da7074fdacd7",
"address": "terra14wvwnyjgsljdps5g3uy9jp2veysd4psu8aytk7",
"memo": "#order-1234",
"amount": 9990000,
"denom": "uusd",
// ISO-8601 compatible date including timezone information and fractional seconds
"created_at": "2021-03-10T13:35:36.000000Z"
}
After the order was created you need to show the payment instructions to customer and wait for webhook signal (see below).
Or you can direct him to our special "Payment instructions page".
Get this page link by replacing {uuid}
with newly created order uuid in this template: https://paywithterra.com/pay/{uuid}
Second check
https://paywithterra.com/api/order/{uuid}/status
It is very important, because the first webhook signal to your site can send anybody (fake success)!
Returns proven information about order with specified uuid
(json).
{
"is_payed": true,
"txhash": "04C8BF34BE457D3523BC3C317592...",
"tx_link": "https:\/\/finder.terra.money\/columbus-4\/tx\/04C8BF34BE457D352...",
"amount": "9990000",
"denom": "uusd"
}
Response always contain is_payed
field even if order not paid or not found (in last case also error
field included).
{
"is_payed": false,
"error": "Order not found"
}
You should know that completed orders are removed from our servers after 14 days and unpaid orders after 24 hours.
Post Back (webhook signal)
If the transaction detected on the blockchain, and we can let you know that youβve received the funds.
This POST request goes to the URL specified in create
method
{
"address": "terra14wvwnyjgsljdps5g3uy9jp2veysd4psu8aytk7",
"memo": "#order-1234",
"webhook": "http://your-website.com/webhook-pay-complete",
"webhook_json": 0,
"amount": 99000,
"denom": "uusd",
"is_payed": 1,
"uuid": "1ad6b9bc-e474-4677-8d69-0bf04b96ca28",
"txhash": "04C8BF34BE457D3523BC3C317592...",
"return_url": "http://your-website.com/order_complete",
"created_at": "2021-03-10T13:35:36.000000Z",
"updated_at": "2021-03-10T13:35:36.000000Z",
"hash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b1..."
}
This data sends as simple form data (application/x-www-form-urlencoded
).
If you want receive this request as JSON, pass the webhook_json
param when you create an order.
Checking data integrity
If you are no able to store uuid after order creation and no able use the Second check
you can check if incoming data is really sent from our server by checking incoming data hash:
data_check_string = ...
secret_key = SHA256(<API_TOKEN>)
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
// data is from PaywithTerra
}
You can find sample PHP code for checking received data on this page.
Pay with Terra Stream API
Please, first read about the Pay with Terra Stream.
Managing Streams
You can manage streams programmatically via API.
Add
https://paywithterra.com/stream/add [POST]
Parameters
{
"address": "terra14wvwnyjgsljdps5g3uy9jp2veysd4psu8aytk7",
"email": "myemail@domain.tld",
"webhook": "https:\\/\\/test.requestcatcher.com\\/test",
"telegram": "111111"
}
Description
Response example
{
"status": "OK"
}
List my streams
https://paywithterra.com/stream/list [GET]
Response example
{
"status": "OK",
"list": [
{
"id": 1,
"address": "terra14wvwnyjgsljdps5g3uy9jp2veysd4psu8aytk7",
"email": "myemail@domain.tld",
"webhook": "https:\/\/test.requestcatcher.com\/test",
"telegram": "111111",
"created_at": "2021-05-15T14:02:29.000000Z",
"updated_at": "2021-05-15T14:02:29.000000Z"
}
]
}
Delete stream
https://paywithterra.com/stream/delete [POST]
Parameters
{
"id": 123
}
Response example
{
"status": "OK"
}
The Stream webhook
If your stream was created with the "webhook" option, we send you signal when each new income payment will be detected on specified address.
{
"memo": "Hello, world!",
"txhash": "04C8BF34BE457D3523BC3C317592...",
"timestamp": "2021-05-15T14:51:17Z",
"from_address": "terra106h043ewfd0xrnwuazkf05q72cfm7kwj784la2",
"to_address": "terra14wvwnyjgsljdps5g3uy9jp2veysd4psu8aytk7",
"amount": "100000",
"denom": "uusd",
"tx_link": "https://finder.terra.money...",
"amount_human": "0.10 USD",
"hash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b1..."
}
This data sends as simple form data (application/x-www-form-urlencoded
).
Error codes
While creation orders API may return a HTTP error code. In some plugins it visible publicly. Using this code you can determine the real error reason.
Here is a list of typical error codes with descriptions
401
Wrong API key. Please check that your code accurately copy&pasted from profile.
403
Inactive API key. Pro period or inner balance is expired. Please, login to your profile and top up your balance or buy the extended Pro period.
Other errors
If your own website is crashed with error 500 when trying to create order through plugin or PHP library - please check if you have all required PHP extensions.