> For the complete documentation index, see [llms.txt](https://docs.paymento.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paymento.io/api-documentation/payment-request.md).

# Payment Request

How to create a payment request and get a token for redirecting customer to paymento gateway.

## Request a new payment

<mark style="color:green;">`POST`</mark> <https://api.paymento.io/v1/payment/request>

**Headers**

| Name         | Value                 |
| ------------ | --------------------- |
| Api-Key      | Your Merchant API Key |
| Content-Type | `application/json`    |
| Accept       | `application/json`    |

**Body**

Provide either `fiatAmount` (with `fiatCurrency`) or `cryptoAmounts`.

<table><thead><tr><th width="185">Name</th><th width="132">Type</th><th>Nullable</th><th>Description</th></tr></thead><tbody><tr><td><code>fiatAmount</code></td><td>string</td><td>true</td><td>Digits with an optional <code>.</code> decimal point, e.g. <code>"1000.50"</code>. Thousands separators and decimal commas (<code>"1,000.50"</code>, <code>"0,09"</code>) are refused.</td></tr><tr><td><code>fiatCurrency</code></td><td>string</td><td>true</td><td>(e.g.) USD or EUR</td></tr><tr><td><code>returnUrl</code></td><td>string</td><td>true</td><td>Where the customer's browser is sent after the gateway. See <a href="https://docs.paymento.io/api-documentation/payment-callback.md#return-url-redirect">Return URL redirect</a>.</td></tr><tr><td><code>orderId</code></td><td>string</td><td>true</td><td>Your online store order ID</td></tr><tr><td><code>riskSpeed</code></td><td>int</td><td>true</td><td><p>Optional, default <code>0</code>.</p><p><code>0</code> = High: the checkout tells the customer the payment was received as soon as it is seen on-chain (mempool or block).</p><p><code>1</code> = Low: the checkout waits for the required confirmations.</p><p>Either way the order becomes <code>Paid</code> only after the asset's required confirmations. <code>riskSpeed</code> changes what the customer sees, not when you may fulfil.</p></td></tr><tr><td><code>cryptoAmounts</code></td><td>Json Object</td><td>true</td><td><p><code>[ { "coinName": "Bitcoin", "amount": "0.01854793" }, { "coinName": "Ethereum", "amount":</code></p><p><code>"1.54848465" } ]</code></p></td></tr><tr><td><code>additionalData</code></td><td>Json Object</td><td>true</td><td><code>[ { "key": "invoice-number", "value": "A-578" }, { "key": "param2", "value": "value2" } ]</code></td></tr><tr><td><code>emailAddress</code></td><td>string</td><td>true</td><td>Email address of the user</td></tr><tr><td><code>language</code></td><td>string</td><td>true</td><td>Gateway language, as a <code>culture</code> from <code>GET /v1/languages</code>. An unknown culture is refused.</td></tr><tr><td><code>tokenExpiryDate</code></td><td>date-time</td><td>true</td><td>When the payment token expires (UTC, ISO 8601). Must be in the future. Defaults to the store's token lifetime (24 hours unless changed).</td></tr></tbody></table>

**Response**

Every response has the shape `{ success, message, body }`. **Always check `success`**: a request that breaks a business rule returns HTTP `200` with `success: false` and a readable `message`.

{% tabs %}
{% tab title="200 — Created" %}

```json
{
  "success": true,
  "message": "",
  "body": "3256e147c6fe4d36a9341a5112ed2214"
}
```

{% endtab %}

{% tab title="200 — Refused" %}

```json
{
  "success": false,
  "message": "Please set amount",
  "body": ""
}
```

{% endtab %}

{% tab title="400 / 401 — API key" %}

```json
{
  "success": false,
  "message": "The 'Api-Key' value is invalid or does not match a merchant store.",
  "code": "API_KEY_INVALID"
}
```

`400` with `API_KEY_MISSING` when the header is absent; `401` with `API_KEY_EMPTY` or `API_KEY_INVALID`.
{% endtab %}
{% endtabs %}

Sending the same request body again shortly after, while that order is still `Initialize`, returns the same token instead of creating a second order.

Now you can use the received token in body section and redirect your customer to

* **Payment URL:** `https://app.paymento.io/gateway?token=TOKEN_HERE`

Replace `TOKEN_HERE` with the token you received.
