# Payment details

**GET** `/payment/{payment_reference}`

Base URL: `https://api.triple-a.io/api/v2`

Get the payment details. This is an alternative way to get the current 
status of the payment, aside from the webhook.

## Authorization

- bearer_auth (http, bearer)

## Path parameters

- `payment_reference` (string, required)
  Unique payment reference number given by the Payment Request

## Query parameters

- `verbose` (integer)
  Flag to display the associated transaction information

  `0` - txs property will not be included.

  `1` - txs property will be included.

## Responses

### 200

Success

- `type` (string)
  The type of payment request.

  Use:
  * `triplea` - when integrating with external URL Payment Form.
  * `widget` - when integrating with Widget Payment Form.
- `payment_reference` (string)
  Unique Payment Reference Number that identifies this payment
- `crypto_currency` (string)
  Cryptocurrency that the payer will pay
- `crypto_address` (string)
  Address that the customer must send the cryptocurrency funds to.
  Each address will only be used to receive a single payment
- `crypto_amount` (number<float>)
  Amount of cryptocurrency to be sent to the address
- `order_currency` (string)
  Currency that the merchant will receive. This should be a
  [3-character ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
  currency code
- `order_amount` (number<float>)
  The amount of currency that the merchant wants to receive
- `exchange_rate` (number<float>)
  Exchange rate that is used to calculate the required `crypto_amount`
- `status` ("none" | "short" | "hold" | "good" | "invalid")
  The status describe the overall state of the payment and
  are related to **Instant Confirmation**. These are the status codes:

  1. `none` - no payment has been detected (yet). The merchant **should not**
  deliver the goods and services.

  2. `short` - the payment is short of the requested amount. The merchant **should not**
  deliver the goods and services.

  3. `hold` - the payment is equal to or greater then the requested amount,
  but the payment cannot be instantly confirmed. The merchant **should not**
  deliver the goods and services.

  4. `good` - the payment is equal to or greater then the requested amount and
  Triple-A has determined that you can now deliver the goods and services to
  the buyer. Your funds are now guaranteed.

  5. `invalid` - the payment was unable to be processed. This is a
  very rare occurence.
- `status_date` (string<date-time>)
  Date and time the `status` was updated
- `receive_amount` (number<float>)
  Amount received in the `order_currency`
- `payment_tier` ("none" | "short" | "hold" | "good" | "invalid")
  Alias for `status`
- `payment_tier_date` (string<date-time>)
  Date of the Payment Tier
- `payment_currency` (string)
  The 3-character currency code of the guaranteed amount. This is
  also the merchant's preferred currency.
- `payment_amount` (number<float>)
  **Guaranteed amount of local currency** that the merchant will
  receive. Even if the `status` remains as `short` or `hold`
  or later becomes `invalid`.
- `payment_crypto_amount` (number<float>)
  Amount of cryptocurrency that the merchant has received.
- `refundable` (boolean)
  Indicates if an invalid payment is refundable or non-refundable.
- `cart` (object)
  Shopping Cart
  - `items` (object[])
    List of items in the shopping cart
    - `sku` (string)
      Stock Keeping Unit of the item
    - `label` (string)
      Name and/or description of the item
    - `quantity` (number<float>)
      Number of units of the item
    - `amount` (number<float>)
      Total price of all the units of the item
  - `shipping_cost` (number<float>)
    Shipping cost
  - `shipping_discount` (number<float>)
    Any discounts to shipping
  - `tax_cost` (number<float>)
    All applicable taxes
- `crypto_uri` (string)
  a unique sequence of characters that identify the details or payment destination of the payment request
- `expires_in` (number)
  How long, in seconds, until the `access_token` expires
  and the hosted payment page becomes inaccessible
- `site_name` (string)
  Name of the merchant
- `success_url` (string)
  Webpage to redirect the customer to on successful payment.
  The `payment_reference` will be provided as part of the
  query string
- `cancel_url` (string)
  Webpage to redirect the customer to on cancelled payment.
  The `payment_reference` will be provided as part of the
  query string
- `hosted_page` (object)
  Data that is used to customize the hosted payment page.
  **Can be ignored**
- `remain_crypto_amount` (number<float>)
  The remaining crypto amount that has not been paid
- `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.

  We need a unique payer ID to track total spends for KYC purposes
- `payer_name` (string)
  Payer's name.

  For a `triplea` or `widget` integration, the payer's name is not
  required. However, if provided, it can make the checkout
  experience better as the payer will not have to enter their name
  if we need to collect it.

  If you do not have the payer's name, then leave this
  key out of the JSON object. Do not submit an empty string `""`.
- `payer_email` (string<email>)
  Payer's email address.

  For a `triplea` or `widget` integration, the payer's email is not
  required. However, if provided, it can make the checkout
  experience better as the payer will not have to enter their email.

  If you do not have the payer's email,
  then leave this key out of the JSON object. Do not submit an empty
  string `""`
- `payer_phone` (string)
  Payer's phone number in
  [E.164 format](https://en.wikipedia.org/wiki/E.164).

  For a `triplea` or `widget` integration, the payer's phone number is not
  required. However, if provided, it can make the checkout
  experience better as the payer will not have to enter their email.

  If you do not
  have the payer's phone number, then leave this key out of the JSON
  object. Do not submit an empty string `""`
- `payer_address` (string)
  Payer's address. If you do not
  have the payer's address, then leave this key out of the JSON
  object. Do not submit an empty string `""`
- `payer_poi` (string<uri>)
  URL to the payer's Proof-Of-Identity (POI). Our system will download
  the payer's POI from this link.

  For a `triplea` or `widget` integration, the payer's POI is not
  required. However, if provided, it can make the checkout
  experience better as the payer will not have to upload their POI. If it is not provided here and the payment or order amount is above SGD 1500 or equivalent, the POI will be asked in the payment form.

  If you do not
  have the payer's POI, then leave this key out of the JSON
  object. Do not submit an empty string `""`

  Note : Please do not use the URL example provided below as the `payer_poi` value in production. It is only for testing purpose.
- `payer_ip` (string)
  IP address of the payer

  If you do not have the payer's ip location,
  then leave this key out of the JSON object. Do not submit an empty
  string `""`
- `required_payer_data` (object)
  Data that is used by the hosted payment page to know if it
  needs to collect data. **Can be ignored**
- `txs` (object[])
  Array of transactions received by the payment request.
  - `t3a_id` (string)
    Triple-A transaction ID
  - `txid` (string)
    Transaction ID
  - `vout_n` (integer)
    Vout index
  - `order_currency` (string)
    Local currency that the merchant has received. This should be a
    [3-character ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
    currency code.
  - `receive_amount` (number<float>)
    Amount received in the `order_currency`
  - `status` ("hold" | "good" | "invalid")
    Payment tiers describe the overall state of the payment and
    are related to **Instant Confirmation**. These are the tiers:

    1. `hold` - the payment is equal to or greater then the requested amount,
    but the payment cannot be instantly confirmed. The merchant **should not**
    deliver the goods and services.

    2. `good` - the payment is equal to or greater then the requested amount and
    Triple-A has determined that you can now deliver the goods and services to
    the buyer. 97% of transactions that we process have instant confirmation
    and are determined good within a few seconds of being broadcast to the
    cryptocurrency network. Your funds are now guaranteed.

    3. `invalid` - the payment cannot be processed. This is a
    very rare occurence.
  - `status_date` (string<date-time>)
    Date and time the `payment_tier` was updated
  - `payment_tier` ("hold" | "good" | "invalid")
    Alias of `status`
  - `payment_tier_date` (string<date-time>)
    Alias of `status_date`
  - `payment_currency` (string)
    The 3-character currency code of the guaranteed amount. This is
    also the merchant's account currency.
  - `payment_amount` (number<float>)
    **Guaranteed amount of local currency** that the merchant will
    receive.
  - `payment_crypto_amount` (number<float>)
    Amount of cryptocurrency that the merchant will receive. Ignore
    if using a local currency account.

Example:

```json
{
  "type": "triplea",
  "payment_reference": "SDF-453672-PMT",
  "crypto_currency": "testBTC",
  "crypto_address": "1NcAyv8YVCnQGCrDb4kiUm1jj6GLyowxER",
  "crypto_amount": 0.001067203,
  "order_currency": "USD",
  "order_amount": 10,
  "exchange_rate": 9370.28,
  "status": "good",
  "status_date": "2020-01-26T03:57:22Z",
  "receive_amount": 10,
  "payment_tier": "good",
  "payment_tier_date": "2021-11-14T02:36:01.557Z",
  "payment_currency": "USD",
  "payment_amount": 10,
  "payment_crypto_amount": 0.00001234,
  "refundable": true,
  "cart": {
    "items": [
      {
        "sku": "ABC8279289",
        "label": "A tale of 2 cities",
        "quantity": 10,
        "amount": 7
      }
    ],
    "shipping_cost": 2,
    "shipping_discount": 1,
    "tax_cost": 2
  },
  "crypto_uri": "testbitcoin:1NcAyv8YVCnQGCrDb4kiUm1jj6GLyowxER?amount=0.001067203",
  "expires_in": 1499,
  "site_name": "Triple-A Gift Cards Pte Ltd",
  "success_url": "https://www.success.io/success.html",
  "cancel_url": "https://www.failure.io/cancel.html",
  "hosted_page": {
    "version": 1,
    "name": "Gift Cards Galore",
    "logo_url": "`https://triple-a.io/logo.png`",
    "tagline": "Tons of gift cards as long as they are Amazon",
    "btn_primary_background_color": "#46d5ba",
    "btn_primary_color": "#ffffff",
    "page_background_color": "#2da2fb"
  },
  "remain_crypto_amount": 0.001067203,
  "payer_id": "TRE1787238200",
  "payer_name": "Alice Tan",
  "payer_email": "alice.tan@triple-a.io",
  "payer_phone": "+6591234567",
  "payer_address": "1 Parliament Place, Singapore 178880",
  "payer_poi": "https://icatcare.org/app/uploads/2018/07/Thinking-of-getting-a-cat.png",
  "payer_ip": "203.116.172.50",
  "required_payer_data": {
    "email_or_phone": true,
    "name": false,
    "poi": false,
    "block": false
  },
  "txs": [
    {
      "t3a_id": "16ff14ea264ee91c5728a36b5b89b07122e58269ca682abcd3571dc634591d4e",
      "txid": "cba3bcf8e4d0d77e2b6af9f16dcc68ac3f5fa7432020d2368541b14bf547b09b",
      "vout_n": 0,
      "order_currency": "USD",
      "receive_amount": 10,
      "status": "good",
      "status_date": "2020-01-26T03:57:22Z",
      "payment_tier": "good",
      "payment_tier_date": "2020-01-26T03:57:22Z",
      "payment_currency": "USD",
      "payment_amount": 10,
      "payment_crypto_amount": 0.00001234
    }
  ]
}
```

### 401

Not authorized

- `message` (string)

Example:

```json
{
  "message": "some_error_message"
}
```

### 403

No permission to access this payment

- `message` (string)

Example:

```json
{
  "message": "some_error_message"
}
```

### 404

Payment not found

- `message` (string)

Example:

```json
{
  "message": "some_error_message"
}
```