# Get list of payments **GET** `/payments` Base URL: `https://api.triple-a.io/api/v2` Returns a list of payments that are associated with your merchant account. The payments are listed in descending order and for a size of 10 by default. ## Authorization - bearer_auth (http, bearer) ## Query parameters - `start_date` (string) Define the start date of list of payments required. Format: `YYYY-MM-DD`. - `end_date` (string) Define the end date of list of payments required. Format: `YYYY-MM-DD`. - `sort` (string) Order the list of payments based on value given. Values: `asc` or `desc`. - `page_size` (integer) Number of payment records retrieved. Maximum value is `100`. - `offset` (integer) Starting point of retrieving the payment records. Example:`offset=0&page_size=10` will retrieve records 1-10, `offset=1&page_size=10` will retrieve records 11-20, and so on. - `status` (string) The current status of the payment. Please refer to the statuses page [here](https://developers.triple-a.io/docs/triplea-api-doc/0c40f1b88af6a-payment-statuses) for the full list. ## 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) 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) The amount of currency that the merchant wants to receive - `exchange_rate` (number) 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 and time the `status` was updated - `receive_amount` (number) Amount received in the `order_currency` - `payment_tier` ("none" | "short" | "hold" | "good" | "invalid") Alias for `status` - `payment_tier_date` (string) 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) **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) 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) Number of units of the item - `amount` (number) Total price of all the units of the item - `shipping_cost` (number) Shipping cost - `shipping_discount` (number) Any discounts to shipping - `tax_cost` (number) 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) 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) 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) 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** 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 } } ] ``` ### 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" } ```