TripleA hosted Payment Page

Introduction

One of the simplest ways to integrate with TripleA is using the TripleA hosted Payment Page. All that needs to be done is:

  1. Make a payment request. This will return a unique Payment Reference Number
  2. Redirect the payer to the TripleA hosted Payment Page using the Payment Reference Number
  3. The Triple A hosted Payment Page will handle the User Experience for the customer
  4. Finally, the merchant can receive notifications of the payment via email and/or webhook integration

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 TripleA hosted Payment Page use “triplea
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_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
success_url
string
Webpage to redirect the customer to on successful payment
cancel_url
string
Webpage to redirect the customer to on cancelled payment
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": "triplea", 
  "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",
  "success_url": "https://success/url",
  "cancel_url": "https://cancel/url",
  "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
  }
}'

Redirect the user

The payment request returns data containing a hosted_url.

Simply redirect the user to this URL (or link a pay button to this URL).

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
hosted_url
string
The URL that hosts the payment page and that the customer should be redirected to

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",
  "hosted_url": "https://triple-a.io/payment_page=?payment_reference=SDF-453672-PMT"
}

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 some are duplicated from the Make a Payment request response parameters.

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
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
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

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

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
  }
}