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

• address Terra wallet address that you are going to ask the customer to send funds to
• memo String that you ask user to define with transaction. Usually it's an unique order number in your system.
• webhook A URL to POST back info when transaction comes. Details of the webhook are below
• amount Transaction amount that "PaywithTerra" should watch for. Pay attention that in Terra blockchain transaction values are presented in u_amount. For example if you want to ask for 9.99 USD you need set awaiting transaction amount 9990000 (9.99 * 1 000 000).
• denom Stablecoin denom for needed fiat currency.
  Currently supported: uaud, ucad, uchf, ucny, udkk, ueur, ugbp, uhkd, uidr, uinr, ujpy, ukrw, umnt, umyr, unok, uphp, usdr, usek, usgd, uthb, utwd, uusd, uluna
• return_url When field is set the "Payment instructions page" will contain the "Return" link with given value.

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

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

• address Terra wallet address for transactions watching
• email, telegram, webhook - destination for sending notification signal.

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.