Custom Integration

Introduction

If a merchants or payment service provider requires more control over the user experience than what TripleA has provided in the hosted payment page, then they can do a custom integration. A mobile app would also require a custom integration. For a custom integration:

  1. The customer will initiate the payment
  2. The merchant will make a payment request to the TripleA API and receive the payment details and Payment Reference
  3. The merchant will send these payment details to the customer
  4. Using these details the customer’s device gets a QRCode from TripleA. The QRCode makes it easy to pay with various cryptocurrency wallets
  5. The customer’s device then polls the status of the payment until a payment is detected. The customer’s device can then end the payment flow and display a success message. If the expiry_date for the payment is reached, it is recommended that the customer’s device ends the payment flow
  6. The merchant will receive all payment notifications through the Payment Notification Webhook

Please contact TripleA for your Merchant Credentials or your Payment Service Provider Credentials (OAuth 2.0) that will authenticate your calls to our API.

Make a Payment Request

The payment process is kickstarted by making a call to this endpoint. A successful response will contain the URL that the customer will need to be redirected to. This endpoint requires authentication.

Request Parameters

type
string
The type of payment request. For custom integration use “custom
api_id
string
The API ID of the cryptocurrency wallet the funds will be received in. You can either use a “live” API ID or a sandbox API ID
crypto_currency
string
The cryptocurrency that the payer will pay. It must match the cryptocurrency of the API ID. testBTC for sandbox API ID
order_currency
string
The currency that the merchant will receive. This should be a 3-character ISO 4217 currency code
order_amount
number
The amount of currency that the merchant will receive
notify_email
string
[optional]
Where to send the email notification for this payment request. The email used in your account setup will be used if this is not provided
notify_url
string
[optional]
The URL to send the webhook notification. The webhook URL given in your account setup will be used if this is not provided
webhook_data
object
[optional]
This data will be passed through to the webhook during payment notification. It is a JSON object that can contain any information that the merchant want’s to pass through to the webhook
payer_id
string
The merchant needs to provide a unique ID for each payer. If the merchant does not have a unique ID then use the payer’s email address
payer_ip
string
The payer’s IP address. It can be IPv4 or IPv6
payer_name
string
[optional]
The customer’s name
payer_email
string
[optional]
The customer’s email
payer_phone
string
[optional]
The customer’s mobile phone number in E.164 format
cart
object
[optional]
This is an object that represents a “shopping cart”. Provide this data so that the payment page can display all the items in the payer’s shopping cart. Make sure that the total in the cart (including shipping and any applicable taxes) is equal to the payment amount.

Cart Parameters

All cart parameters are required.

items
array
An array of item
items[].amount
number
The total cost of the item. Should be price * quantity
items[].quantity
number
The count of that particular item
items[].label
string
A short description or label of the item
items[].sku
string
Stock Keeping Unit of the item
shipping_cost
number
The cost of shipping
shipping_discount
number
Any discount that is applied to shipping. Must be a positive number
tax_cost
number
Any applicable taxes

Endpoint:

POST https://api.triple-a.io/api/v1/payment/request

Sample cURL request:

curl --location \
--request POST 'https://api.triple-a.io/api/v1/payment/request' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
  "type": "custom", 
  "api_id": "HA************_t",
  "crypto_currency": "testBTC",
  "order_currency": "USD",
  "order_amount": 14.29,
  "notify_email": "admin@your-organization.com",
  "notify_url": "https://webhook/url",
  "webhook_data": {"order_id": "ABC12345-2"}, 
  "payer_id": "ABC-4728738428",
  "payer_email": "payer01@gmail.com",
  "payer_ip": "192.168.1.1",
  "cart": {
    "items": [
      {
        "amount": 10.99, 
        "quantity": 1, 
        "label": "A tale of 2 cities", 
        "sku": "2736829"
      }
    ],
    "shipping_cost": 2.57,
    "shipping_discount": 0,
    "tax_cost": 0.73
  }
}'

Selected Response Parameters

This is not the full list of parameters as some are duplicated from the request parameters.

payment_reference
string
Unique Payment Reference Number that identifies this payment
crypto_address
string
The address that the customer must send the cryptocurrency funds to. Each address will only be used to receive 1 payment
crypto_amount
number
The amount of cryptocurrency funds that need to be sent to the crypto_address
exchange_rate
number
The exchange rate that is used to calculate the required crypto_amount
expiry_date
date
The exchange rate is guaranteed until the expiry date which is 900 seconds from the time the the JSON response is received.

After expiry, any cryptocurrency funds received by the address will be converted at the spot exchange rate

Sample JSON response:

{
  "payment_reference": "SDF-453672-PMT",
  "crypto_currency": "BTC",
  "crypto_address": "1NcAyv8YVCnQGCrDb4kiUm1jj6GLyowxER", 
  "crypto_amount": 0.0011,
  "order_currency": "USD",
  "order_amount": 10.37,
  "exchange_rate": 9370.28,
  "expiry_date": "2020-01-26T03:57:22Z"
}

Get Payment Status

Get the status of the payment. This endpoint does not require authentication.

Selected Response Parameters

This is not the full list of Webhook parameters as some are duplicated from the Make a Payment request response parameters.

unconfirmed_crypto_amount
number
The amount of cryptocurrency received by the crypto_address that has been detected but not confirmed
unconfirmed_order_amount
number
The amount of currency that the merchant receives that has been detected but not confirmed
confirmed_crypto_amount
number
The amount of cryptocurrency received by the crypto_address that has been confirmed
confirmed_order_amount
number
The amount of currency that the merchant receives that has been confirmed
crypto_address
string
The cryptocurrency address the funds are to be sent to. If the status of the payment request is invalid, this value will be an empty-string.
status
string
The status of the payment request. Please see below for an explanation of the status codes
status_date
date
Datetime (UTC) of the status
webhook_data
object
Data provided by the merchant in the Make a Payment Request endpoint and passed through to the webhook

Status Codes

These status codes give you all the information you need to know about the payment. To make more fine-grained decisions about the payment, you can take into account the unconfirmed / confirmed cryptocurrency and order amounts.

  1. unpaid — the payment has just been created and no funds have been detected or confirmed
  2. unconfirmed-less — funds have been detected but it is less than the order amount
  3. unconfirmed — funds have been detected and it is equal to the requested order amount
  4. unconfirmed-more — funds have been detected and it is more than the requested order amount
  5. confirmed-less — funds have been confirmed but the confirmed funds are less than the requested order amount
  6. confirmed — funds have been confirmed and are equal to the requested order amount
  7. confirmed-more — funds have been confirmed and are more than the requested order amount
  8. invalid — the payment request is no longer valid and can no longer receive funds

Note: If the address contains a mixture of confirmed and unconfirmed funds, it will be in one of the confirmed statuses.

Endpoint:

GET https://api.triple-a.io/api/v1/payment/:payment_reference

Sample JSON Response:

{
  "payment_reference": "DQJ-176495-PMT",
  "crypto_currency": "testBTC",
  "crypto_address": "moD6GbfewBuWXyNaV2Y7imEoyyU5YNPGEV",
  "crypto_amount": 0.00152227,
  "order_amount": "USD",
  "order_currency": 14.29,
  "unconfirmed_crypto_amt": 0,
  "confirmed_crypto_amt": 0.00152227,
  "unconfirmed_order_amt": 0,
  "confirmed_order_amt": 14.29,
  "exchange_rate": 9370.28,
  "expiry_date": "2020-02-06T08:18:53.088Z",
  "status": "confirmed",
  "status_date": "2020-02-06T09:34:12.000Z",
  "site_name": "Test Merchant",
  "cart": {
    "items": [
      {
        "amount": 10.99,
        "quantity": 1,
        "label": "A tale of 2 cities",
        "sku": "2736829"
      }
    ],
    "shipping_cost": 2.57,
    "shipping_discount": 0,
    "tax_cost": 0.73
  }
}

Get QRCode

This is a QRCode generated from the payment request. It is of the format bitcoin:<address>?amount=<crypto_amount> and is a standard that all cryptocurrency wallets recognize.

Parameters

width
number
[optional]
This is the width of the QRCode. If the width is not given, the QRCode will be a standard size

The response will be a .png file.

We have provided this endpoint for convenience. It’s possible to use the above format to generate the QRCode on the customer’s device. This endpoint does not require authentication.

Endpoint:

GET https://api.triple-a.io/api/v1/payment/:payment_reference/qrcode?width=200

Webhook Payment Notification

This Payment Notification will be POSTed back to the notify_url that you have specified in the payment request. If there was no URL was specified, it will default to the notification URL provided when the merchant was setup.

Selected Webhook Parameters

This is not the full list of Webhook parameters as most are duplicated from get payment status.

event
string
The type of webhook notification. This is a payment event
api_id
string
The API ID of the merchant’s wallet that received the funds

Sample POST webhook JSON:

{
  "event": "payment",
  "api_id": "HA1151890420kHnW",
  "payment_reference": "SDF-453672-PMT",
  "crypto_currency": "BTC",
  "crypto_address": "1NcAyv8YVCnQGCrDb4kiUm1jj6GLyowxER", 
  "crypto_amount": 0.0011,
  "order_currency": "USD",
  "order_amount": 10.37,
  "exchange_rate": 9370.28,
  "expiry_date": "2020-01-26T03:57:22Z",
  "unconfirmed_crypto_amount": 0,
  "unconfirmed_order_amount": 0,
  "confirmed_crypto_amount": 0.0011,
  "confirmed_order_amount": 10.37,
  "status": "confirmed",
  "status_date": "2020-01-26T03:57:22Z",
  "webhook_data": {"order_id": "ABC12345-2"},
  "cart": {
    "items": [
      {
        "amount": 10.99, 
        "quantity": 1, 
        "label": "A tale of 2 cities", 
        "sku": "2736829"
      }
    ],
    "shipping_cost": 2.57,
    "shipping_discount": 0,
    "tax_cost": 0.73
  }
}

Advanced

Payment Exchange Rate

When the expiry date has elapsed, the cryptocurrency address can still receive funds. However, any cryptocurrency received after the expiry date will be converted at our-spot rate.

By using this API endpoint, you can update the user on the new exchange rate and amount of cryptocurrency that needs to be paid and not end the payment flow when the expiry_date has been reached.

Warning: this new exchange rate is indicative and not guaranteed. So in practice, the conversion will vary once the funds are detected in the cryptocurrency address.

Endpoint:

GET https://api.triple-a.io/api/v1/payment/:payment_reference/exchange_rate

Sample JSON response:

{
  "from_currency": "BTC",
  "to_currency": "USD",
  "exchange_rate": 9462.640776699029
}