Create a hosted-checkout payment

POST/payments

Creates a payment and returns the hosted checkout URL the customer must be redirected to. Synchronous 200: the resource and its checkout link are produced from our own data. The customer's payment itself is asynchronous — the resource starts in status: pending and the terminal outcome arrives through the payment.completed or payment.expired webhook (or GET /payments/{paymentId}). Never read the outcome from the returnUrl redirect.

A failed attempt does not end the payment: the customer can retry until checkout.expiresAt, and the payment stays pending meanwhile. A customer who committed just before the deadline can still complete it after payment.expired — the money has then moved, so handle payment.completed even for an order you closed.

Retrying. After a timeout or a 5xx, retry with the same Idempotency-Key: you get the payment the first attempt made, never a second one and never duplicate_merchant_reference. Within 24 hours the original response is replayed. Past that, or when the first attempt ended in a 5xx, the payment is answered as it stands: while nobody has started paying it, with a new checkout.url — the token behind the earlier link is replaced, so that link stops working — and its checkout.expiresAt unchanged; once a customer has started paying it, or it has ended, without a url.

Authentication: ApiKeyAuth
Execution: synchronous

Parameters

Idempotency-Keystringheaderrequired
Client-generated unique key for this logical request (UUID recommended). See Idempotency.
min length 1 · max length 255

Request body application/jsonrequired

description, metadata and a per-payment expiresIn are not accepted yet; the checkout TTL is the platform default (15 minutes) and is reported back in checkout.expiresAt.

merchantReferencestringrequired
Your own unique reference for this payment — typically your order number. Unique per merchant for good; a repeat under a different Idempotency-Key is 400 duplicate_merchant_reference.
min length 1 · max length 100
amountMoneyrequired
Decimal amount as a string — never a float, never minor units. An amount you send may carry no more decimal places than its currency has (and never more than 8); trailing zeros do not count, so 10.100 EUR is fine and 10.123 EUR is 400 validation_failed on amount.value. An amount the API returns is written with exactly as many decimal places as its currency has (at most 8): 10.10 EUR, never 10.1.
- valuestringrequired
  Example: 149.90
  pattern ^-?\d{1,18}(\.\d{1,18})?$
- currencystringrequired
  ISO 4217 code for fiat (EUR), asset ticker for crypto (USDT).
  Example: EUR
  pattern ^[A-Z0-9]{3,10}$
methodstringrequired
One of the methods GET /payment-methods lists as enabled for you. Unlike other enums you send, a method the API does not know is not validation_failed: it is 400 payment_method_not_enabled, as a disabled one is.
Allowed values: jeton_wallet
returnUrlstring (uri)required
HTTPS URL the customer is sent back to after checkout (success or failure — read the outcome from the API or webhooks, never from the redirect).
languagestring
The checkout page's language, ISO 639-1 — the one language field a payment has. Left out, the checkout picks its own.
Example: en
pattern ^[a-z]{2}$
customerCustomer
The payer. Only the e-mail is reported for now; name, phone and country are not provided yet. The checkout page's language is the payment's own language, not a customer field.
- emailstring (email)
  max length 100

Responses

The payment.

Headers

X-Request-Idstring
The request's trace id: the same value a problem body carries as traceId. Quote it when you contact support. A replayed response (Idempotent-Replayed: true) carries the replay's own; its body keeps the original request's traceId.
RateLimit-Limitinteger
RateLimit-Remaininginteger
RateLimit-Resetinteger
Seconds until the window resets.
Idempotent-Replayedboolean
true when this response was replayed from an earlier request with the same Idempotency-Key.

Schema application/json

idstringrequired
A payment's id. Opaque — use it as you received it.
Example: pay_019985c24a6e7c3b9f102d5e8a1b3c4d
pattern ^pay_[0-9a-f]{32}$
merchantReferencestringrequired
Your own reference for this payment, as you sent it.
statusstringrequired
pending awaiting the customer — also after a failed attempt, while the customer may retry · processing customer acted, settlement in flight · completed funds credited · failed not used for payments: one never paid ends expired · cancelled · expired checkout TTL elapsed unpaid (a customer who committed just before the deadline can still turn it completed) · refunded. (partially_refunded is not reported yet.)
Allowed values: pendingprocessingcompletedfailedcancelledexpiredrefunded
amountMoneyrequired
Decimal amount as a string — never a float, never minor units. An amount you send may carry no more decimal places than its currency has (and never more than 8); trailing zeros do not count, so 10.100 EUR is fine and 10.123 EUR is 400 validation_failed on amount.value. An amount the API returns is written with exactly as many decimal places as its currency has (at most 8): 10.10 EUR, never 10.1.
- valuestringrequired
  Example: 149.90
  pattern ^-?\d{1,18}(\.\d{1,18})?$
- currencystringrequired
  ISO 4217 code for fiat (EUR), asset ticker for crypto (USDT).
  Example: EUR
  pattern ^[A-Z0-9]{3,10}$
feeobject
Present once the payment is completed: the fee charged to you on it, in the payment's currency. You were credited amount less this.
- valuestringrequired
  Example: 149.90
  pattern ^-?\d{1,18}(\.\d{1,18})?$
- currencystringrequired
  ISO 4217 code for fiat (EUR), asset ticker for crypto (USDT).
  Example: EUR
  pattern ^[A-Z0-9]{3,10}$
methodstringrequired
How the customer pays — the same vocabulary as PayoutMethod. jeton_wallet: the customer pays from their Jeton account on the checkout page. More methods will come; GET /payment-methods lists those enabled for you.
Allowed values: jeton_wallet
checkoutobject
Present while the payment is pending or processing.
- urlstring (uri)
  Redirect the customer here. Returned in the create response only — the checkout token is stored hashed, so GET cannot reproduce it. Persist it with your order. A retry of the create under its Idempotency-Key issues a new one while nobody has started paying (see Retrying on POST /payments).
- expiresAtstring (date-time)required
  RFC 3339, UTC, with millisecond precision.
  Example: 2026-09-18T10:15:30.123Z
customerCustomer
The payer. Only the e-mail is reported for now; name, phone and country are not provided yet. The checkout page's language is the payment's own language, not a customer field.
- emailstring (email)
  max length 100
payerobject
Present once the payment is completed: the Jeton user who actually paid. Distinct from customer, which is what you sent. Pass payer.customerNumber as destination.customerNumber on POST /payouts to pay the same customer back.
- customerNumberstringrequired
languagestring
The checkout page's language as you sent it. Absent when you sent none.
pattern ^[a-z]{2}$
createdAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
updatedAtstring (date-time)required
Last change. It never moves backwards, so use it to discard stale webhook snapshots.
Example: 2026-09-18T10:15:30.123Z
completedAtstring (date-time)
Present once the payment is completed — when the funds were credited.
Example: 2026-09-18T10:15:30.123Z

Request

POST https://merchant-api.jeton.com/v2/payments

Request body · application/json

{
  "merchantReference": "string",
  "amount": {
    "value": "149.90",
    "currency": "EUR"
  },
  "method": "jeton_wallet",
  "returnUrl": "https://example.com",
  "language": "en",
  "customer": {
    "email": "[email protected]"
  }
}

Example · 200

{
  "id": "pay_019985c24a6e7c3b9f102d5e8a1b3c4d",
  "merchantReference": "string",
  "status": "pending",
  "amount": {
    "value": "149.90",
    "currency": "EUR"
  },
  "fee": {
    "value": "149.90",
    "currency": "EUR"
  },
  "method": "jeton_wallet",
  "checkout": {
    "url": "https://example.com",
    "expiresAt": "2026-09-18T10:15:30.123Z"
  },
  "customer": {
    "email": "[email protected]"
  },
  "payer": {
    "customerNumber": "string"
  },
  "language": "string",
  "createdAt": "2026-09-18T10:15:30.123Z",
  "updatedAt": "2026-09-18T10:15:30.123Z",
  "completedAt": "2026-09-18T10:15:30.123Z"
}