E-commerce:
External payment page

The TripleA API is organised around HTTP calls. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. It is fully SSL-secured.

You can use the TripleA API with the Bitcoin Testnet network. The API ID you use with requests determines whether the request is live mode or test mode.

Payment flow

Integration steps

  1. Your server requests a payment form URL for a given order.
    API doc: POST payment_form
     
  2. Our API responds with a Payment Page URL and a response authentication token. Save this token (associate it with the current order).
     
  3. When a user selects Bitcoin payment for an order, user is redirected to the Payment Page URL to make his payment.
     
  4. After a payment has been made, the user is redirected to the Payment Completed Page (as specified in step 1).
     
  5. Our API detects the transaction and sends a payment notification to your backend.
     
  6. After a while (~10 minutes on average), the transaction will be validated on the blockchain. Our API detects this and sends a payment update notification.


Handling payment updates

When are payment update notifications sent?

Whenever a Bitcoin payment is made, a transaction is added to the blockchain which will trigger a payment update notification to be sent to your server (to the payment_update_url you specified in step 1 when requesting the payment page URL).

Each time a Bitcoin transaction gets validated on the blockchain (on average ~10 minutes after a transaction was created), another payment update notification will be sent.

Verifying authenticity of incoming notifications

When receiving a payment update notification, verify that the response_auth_token for this order matches with the value you received together with the Payment Page URL. (See integration step 2.)

Note that the response_auth_token is unique and different each time, for each order.

Rare edge cases

Should a user by mistake have paid too little, they have the possibility to make another payment to match the total amount owed and paid. In such a case, more than one transaction is made, each triggering a payment update notification when created and again when validated.

Should a user by mistake have paid too much, they’ll have the possibility reaching out and asking for a refund.

Edge cases do not make things more difficult for integration. To see how we keep things clear and accurate you can refer to the section below, Updating order payment statuses.

POST https://<YOUR_DOMAIN>/<PATH_TO_WEBHOOK>
{
  "return": "0",
  "status": "OK",

  /* Order payment details. */

  /*** TODO ***/

  /* Collected user data. */
  "auth_response_token":"###",
  "user_fields":[
    {
      "name":"Your name",
      "required":1,
      "type":"text",
      "value":""
    },
    {
      "name":"Address",
      "required":0,
      "type":"textarea",
      "value":"User street<br>Building address"
    }
  ],

  /* Server already has this. */
  /* Adding to ease debugging. */
  "api_id":"HA11111112222222",
  "order_id":"###",
  "order_amount":"1234.98",
  "order_currency":"SGD",
  "user_id":"",
  "user_email":"user@domain.org"
}

Updating order payment statuses

You update an order’s payment status based on the payment_status and order_status value in a payment update notification.

The payment_status property

Possible values:

  • “unconfirmed”
  • “confirmed”

An order may have been paid in a single Bitcoin transaction or with several transactions (if user paid too little at first).
As long as at least one transaction is still awaiting blockchain validation, the value will remain “unconfirmed”.

The order_status property

Possible values:

  • “paid”
  • “paid_too_much”
  • “failed_paid_too_little”
  • “failed”
// PHP example

$payment_status = $payment_update->payment_status;
$order_status = $payment_update->order_status;

/* One or more transactions are still unconfirmed. */
if ($payment_status === 'unconfirmed') {
  // Payment has been made, not yet fully validated.
  // Set order payment status to "processing" 
  // (unless it was already marked as such).
}
elseif ($payment_status === 'confirmed') {
  // Payment has been fully validated.
  // Now it depends on how much has been paid.

  if ($order_status === 'paid') {
    // Mark order payment as "completed".
  }

  elseif ($order_status === 'paid_too_much') {
    // Mark order payment as "completed".
    // Note that user might contact you asking for a refund.
  }

  else {
    // Mark order payment as "failed" and save the order.

    // If the user did pay, but paid too little,
    //  the user may request a refund.
  }
}


Payment form user experience

Once the Bitcoin payment form is displayed, a Bitcoin payment address is provided together with the amount to be paid and the current exchange rate.

If no payment is made within 15 minutes, the form expires.

If a sufficient payment is made, a confirmation message is shown. The user is then redirected back to the merchant’s site.

If an insufficient payment is made, the form remains available so that the user can make another payment to the same Bitcoin address. If the 15 minutes of guaranteed exchange rate expire, the user can click the form to refresh the exchange rate and get another 15 minute time frame to make the additional payment. (This continues until the user closes the window or a sufficient amount has been paid.)

 

Sample code

Code for additional programming languages will be added upon request.

We welcome feedback! Please reach out at support@triple-a.io with your questions or comments.

Please rename file extensions before testing.