# Make a payment request (specific account)

**POST** `/payment/account/{account_api_id}`

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

Making a payment request for a specific account.

Note :
1. If you are integrating with the [External URL Payment Form](https://developers.triple-a.io/docs/triplea-api-doc/8575c3952a289-payment-solutions), refer to the `TripleAType-SpecificAccount`.
2. If you are integrating with [Embedded Payment Form](https://developers.triple-a.io/docs/triplea-api-doc/8575c3952a289-payment-solutions), refer to the `WidgetType-SpecificAccount`.

## Authorization

- bearer_auth (http, bearer)

## Body

Content type: `application/json`

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

  Use:
  * `triplea` - when you want to redirect to the external URL Payment Form. The response will contain `hosted_url` which you will redirect the payer to.
  * `widget` - when you want to display the payment form embedded in your app or site. The response will contain `hosted_url` which you can then display in an iframe or Webview.
- `order_currency` (string, required)
  The 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>, required)
  Total amount of the order.
- `order_id` (string)
  Idempotency key. Merchant's unique ID for the payout
- `notify_email` (string<email>)
  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. For testing you can use
  [webhook.site](https://webhook.site), the site can also receive
  notification emails
- `notify_url` (string<uri>)
  The URL to send the webhook notification. The webhook URL given
  in your account setup will be used if this is not provided.
  For testing you can use [webhook.site](https://webhook.site)
- `notify_secret` (string)
  The shared secret that will be used to sign the notification.
  This secret can be at most 64 characters long.
  If this is not provided in the payment request, the system will
  create a random secret just for that payment.
- `notify_txs` (boolean)
  Flag to include the individual txs in the webhook notification
- `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 `""`
- `success_url` (string)
  Webpage to redirect the customer to on successful payment.
  We inject some information into the URL as URL parameters.

  Parameters :
  * `status`
  * `payment_reference`
  * `order_currency`
  * `order_amount`

  Example : if url provided is https://www.myshop.com/payment-success and payment is successful, the redirect URL is : https://www.myshop.com/payment-success?status=paid&payment_reference=ASDDF...&order_currency=USD&order_amount=10

  Note:
  This field is required if integrating using **External URL Payment Form**. For other integrations,
  either insert the field with a url, or remove the field completely.
- `cancel_url` (string)
  Webpage to redirect the customer to on cancelled payment.
  We inject some information into the URL as URL parameters.

  Parameters :
  * `status`
  * `payment_reference`

  Example: if url provided is https://www.myshop.com/payment-failure
  and payment is canceled or form expired, the redirect URL is
  https://www.myshop.com/payment-failure?status=paid_too_little&payment_reference=ASDFDF....

  Note:
  This field is required if integrating using **External URL Payment Form**. For other integrations,
  either insert the field with a url, or remove the field completely.
- `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
- `webhook_data` (object)
  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.

  We recommend that you at least include the `order_id` which ties
  this payment request to the order in your system. You can also
  include any other data you need to be passed through to your
  payment notification webhook
  - `order_id` (string)
    Order ID that is associated with this payment
- `sub_merchant` (object)
  Submerchant Details
  - `id` (string)
    ID of the Submerchant
  - `name` (string)
    Name of the Submerchant
  - `phone_number` (string)
    Phone Number of Submerchant
  - `email` (string)
    Email of Submerchant

Example:

```json
{
  "type": "triplea",
  "order_currency": "USD",
  "order_amount": 10,
  "order_id": "TSGA267KL",
  "notify_email": "1a2d24e8-1594-4569-bc35-079049e4d805@email.webhook.site",
  "notify_url": "https://webhook.site/1a2d24e8-1594-4569-bc35-079049e4d805",
  "notify_secret": "Cf9mx4nAvRuy5vwBY2FCtaKr",
  "notify_txs": true,
  "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",
  "success_url": "https://www.success.io/success.html",
  "cancel_url": "https://www.failure.io/cancel.html",
  "cart": {
    "items": [
      {
        "sku": "ABC8279289",
        "label": "A tale of 2 cities",
        "quantity": 10,
        "amount": 7
      }
    ],
    "shipping_cost": 2,
    "shipping_discount": 1,
    "tax_cost": 2
  },
  "webhook_data": {
    "order_id": "ABC12345-12"
  },
  "sub_merchant": {
    "id": "25",
    "name": "Test Payer",
    "phone_number": "+6591234467",
    "email": "testpayer@gmail.com"
  }
}
```

## Responses

### 200

Success

- `payment_reference` (string)
  Unique Payment Reference Number that identifies this payment
- `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
- `expiry_date` (string<date-time>)
  Exchange rate is guaranteed until the expiry date. After expiry,
  any cryptocurrency funds received by the address will be converted
  at the spot exchange rate
- `hosted_url` (string)
  Redirect the payer's browser to this URL for them to make payment
- `access_token` (string)
  Oauth2 access token used specifically for this payment request
- `token_type` (string)
  Type of Oauth2 authentication token
- `expires_in` (number)
  How long, in seconds, until the `access_token` expires
  and the hosted payment page becomes inaccessible
- `notify_secret` (string)
  The shared secret that will be used to sign the notification.
  If the secret was provided in the payment request, it will be
  mirrored here. If not a random secret will be generated
- `crypto_currency` (string)
  The cryptocurrency of the account API ID selected.
- `crypto_amount` (number<float>)
  The amount in cryptocurrency

Example:

```json
{
  "payment_reference": "SDF-453672-PMT",
  "order_currency": "USD",
  "order_amount": 10,
  "expiry_date": "2020-01-26T03:57:22Z",
  "hosted_url": "`https://triple-a.io/app/v1/payment_form?payment_reference=SDF-453672-PMT&access_token=1aa03d46aee08c6539db7b8afccaaa49f9d0f968`",
  "access_token": "cb17fe4910504350d2bc258fd7917f7d32ac83bf",
  "token_type": "Bearer",
  "expires_in": 1499,
  "notify_secret": "Cf9mx4nAvRuy5vwBY2FCtaKr",
  "crypto_currency": "BTC",
  "crypto_amount": 0.00031873
}
```

### 401

Not authorized

- `message` (string)

Example:

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

### 403

No permission to use this API ID

- `message` (string)

Example:

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

### 404

API ID not found

- `message` (string)

Example:

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

### 409

Payment Processing Error - The payment cannot be processed

- `message` (string)

Example:

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

### 422

Validation Error - There are 1 or more errors in the request body

- `message` (string)
  Main error message
- `errors` (any[])
  - `message` (string)
    Additional error messages
  - `path` (string)
    JSON object key that has the error

Example:

```json
{
  "message": "validation_error",
  "errors": [
    {
      "message": "invalid",
      "path": "api_id"
    }
  ]
}
```