Your first payment

Creating a payment takes one authenticated request, and you read its status with another. This page runs both against the sandbox.

Before you start, you need an access token and your Sandbox API ID. See Sandbox and test mode.

Create the payment

Call Make a payment request with your token in the Authorization header. The following request creates a test payment of 10 USD. The highlighted lines set the price in order_currency and order_amount, and mark the payment as a test with sandbox.

Request

curl --request POST \
  --url https://api.triple-a.io/api/v2/payment \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "triplea",
    "merchant_key": "YOUR_MERCHANT_KEY",
    "order_currency": "USD",
    "order_amount": 10,
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "sandbox": true
  }'

The table below describes the request fields.

Field	Required	Notes
`type`	Yes	`triplea` redirects to a Triple-A hosted page. `widget` is for an embedded form.
`merchant_key`	Yes	Identifies your merchant account. You receive it when you sign up.
`order_currency`	Yes	A 3-character ISO 4217 code. See Which currency is which.
`order_amount`	Yes	The total amount of the order.
`success_url`, `cancel_url`	For `triplea`	Where to send the customer after payment. `success_url` is required for the External URL form.
`sandbox`	For testing	`true` marks a test payment.
`notify_url`, `notify_secret`	Optional	The webhook destination and signing secret. See Webhooks.
`order_id`	Optional	Your own ID, up to 255 characters. The API reference describes it inconsistently across payment types, so check it before you rely on it as an idempotency key.

Read the response

A successful request returns the payment and the hosted page address. The following response is adapted from the Payment Integration Guide, and its values are illustrative. The real response also includes an exchange_rate. The highlighted lines are the payment_reference to store and the hosted_url to send your customer to.

Response

{
  "payment_reference": "AQH-100306-PMT",
  "order_currency": "USD",
  "order_amount": 10,
  "expiry_date": "2020-04-22T08:52:11.842Z",
  "access_token": "736511b8...",
  "token_type": "Bearer",
  "expires_in": 1499,
  "hosted_url": "https://triple-a.io/app/v1/payment_form?payment_reference=AQH-100306-PMT&access_token=..."
}

These are the fields to use.

payment_reference identifies the payment. Keep it.
hosted_url is where you send the customer.
expiry_date is when the guaranteed rate ends. After it, funds received are converted at the spot rate.
access_token and expires_in belong to this payment form only, not to your API token. In the example, expires_in is 1499 seconds (about 25 minutes). This appears to be how long the payment form stays usable, and the embedded form fires a triplea.formExpired event when its timer expires or the token is invalid.

Check the payment status

Call Payment details to get the payment’s current state, including status. Deliver only when the status is good. For every status and the action to take, see Payment statuses.

Which currency is which

Three currencies can differ within one payment, and the table below shows what each one is and where it appears.

Currency	What it is	Where you see it
Order currency	The currency you price the order in, which is the presentment currency. You set it in `order_currency`.	Request, response, and webhook `order_currency`
Digital currency	What the customer pays in, for example `USDT_TRC20`. The customer picks it.	`crypto_currency`
Settlement currency	The local currency your account is credited in.	Webhook `payment_currency`

A customer can pay in USDT on Tron, you can display prices in EUR, and you can settle in SGD. For the digital currency codes, see Coins and networks.

The API reference describes order_currency as “the currency that the merchant will receive”, which reads as if it were the settlement currency. It is the currency you set per request.

Reconcile on payment_currency#

Reconcile on payment_currency and payment_amount, not order_currency. payment_currency is the currency of the guaranteed amount and also your preferred currency, and payment_amount is the guaranteed local-currency amount.

Next steps

These pages are the best places to go next.

Stablecoin checkout to receive webhooks and fulfil orders