# TrueMoney for Payment Setup API

To accept TrueMoney payments, you must:

1. Create a payment setup.
2. Confirm the payment.
3. Redirect the customer to TrueMoney.

---

## Create a payment setup

Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) endpoint.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/setups`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups`

### Request example

```json
{
  "amount": 1100,
  "currency": "THB",
  "reference": "ORD-5023-4E89",
  "customer": {
    "name": "Hannah Bret"
  },
  "order": {
    "items": [
      {
        "name": "Wireless headphones",
        "quantity": 1,
        "unit_price": 1100
      }
    ]
  },
  "payment_methods": {
    "truemoney": {
      "terminal_type": "app",
      "os_type": "ios"
    }
  },
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

In the request body, provide the following:

| Field | Description |
| --- | --- |
| `amount`<br>`number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). <br><br>Minimum: 1 <br><br>**Required** |
| `currency`<br>`string` | Three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). <br><br>Supported value: `THB` <br><br>**Required** |
| `customer.name`<br>`string` | The customer's full name. <br><br>**Required** |
| `order.items`<br>`array` | The list of items in the order. <br><br>Minimum items: 1 <br><br>**Required** |
| `order.items[].name`<br>`string` | The name of the item. <br><br>**Required** |
| `order.items[].quantity`<br>`number` | The quantity of the item. <br><br>Minimum: 1 <br><br>**Required** |
| `order.items[].unit_price`<br>`number` | The unit price of the item. <br><br>Minimum: 0 <br><br>**Required** |
| `payment_methods.truemoney.os_type`<br>`string` | The operating system of the customer's device. <br><br>Required if `terminal_type` is `wap` or `app`. <br><br>Supported values:<br><br>- `android`<br><br>- `ios` |
| `payment_methods.truemoney.terminal_type`<br>`string` | Supported values:<br><br>- `web`<br><br>- `wap`<br><br>- `app` <br><br>**Required** |
| `settings.failure_url`<br>`string` | The URL to redirect the customer to if the payment fails. <br><br>Format: URI <br><br>Max length: 1024 <br><br>**Required** |
| `settings.success_url`<br>`string` | The URL to redirect the customer to if the payment is successful. <br><br>Format: URI <br><br>Max length: 1024 <br><br>**Required** |
| `billing`<br>`object` | The customer's billing details. |
| `billing.address`<br>`object` | The customer's billing address. <br><br>Required if `billing` is provided. |
| `billing.address.address_line1`<br>`string` | The first line of the billing address. <br><br>Required if `billing` is provided. |
| `billing.address.city`<br>`string` | The city of the billing address. <br><br>Required if `billing` is provided. |
| `billing.address.country`<br>`string` | The country of the billing address. <br><br>Required if `billing` is provided. |
| `description`<br>`string` | A description of the payment. <br><br>Max length: 100 |
| `order.items[].reference`<br>`string` | A reference for the item. |
| `reference`<br>`string` | A reference you can use to identify the payment. <br><br>Max length: 80 |

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1100,
  "currency": "THB",
  "payment_type": "Regular",
  "reference": "ORD-5023-4E89",
  "description": "TrueMoney payment",
  "payment_methods": {
    "truemoney": {
      "status": "ready",
      "flags": []
    }
  },
  "available_payment_methods": [
    "truemoney"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `payment_methods` object, which contains the payment methods enabled on your account.

When all required fields are present, the `payment_methods.truemoney` object shows a `ready` [status](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api.md#Payment_method_status).

---

## Confirm the payment

Checkout.com processes the payment when you confirm the payment setup. Confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:

- The payment setup `id` as the `{id}` path parameter.
- `truemoney` as the `{payment_method_name}` path parameter.

### Request example

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/truemoney`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/truemoney`

### Response example

If you receive a `202 Success` response with a payment `id` and a `status` field set to `Pending`, your request was successful.

```json
{
  "id": "pay_sxzrgliy2w3e5gpnby3chlswwq",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_2g4ehcpm6phexgkzahlwxvbgne",
    "email": "hannah.bret@example.com",
    "name": "Hannah Bret"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_sxzrgliy2w3e5gpnby3chlswwq"
    },
    "redirect": {
      "href": "https://psp.ac.alipay.com/page/simulation-wallet/acwallet/alipayconnectcode.html?code=281666040095AHvh5AIKT0a3kv8X6Zzv3kiv&pspName=TRUEMONEY&loadMode=2"
    }
  }
}
```

---

## Redirect the customer

Redirect the customer to the `redirect.href` URL from the response. The customer completes the payment on the TrueMoney page and is then redirected back to your `settings.success_url` or `settings.failure_url`.

When accepting TrueMoney payments, you must display the Alipay+ and TrueMoney logos on your payment interface. To ensure that the logos meet Alipay brand guidelines, refer to their [Brand display guidelines for online payments](https://docs.alipayplus.com/alipayplus/alipayplus/ux_cashier_acq_older_edition/brand_online_acq#quwEA) and [Brand display guidelines for cashier payments](https://docs.alipayplus.com/alipayplus/alipayplus/brand_guidelines/brand_cashier_acq).