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

Do not mark your order as complete until you check transaction status with this method.
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).