Create payment
Create an order and redirect the payer to the hosted payment page
A payment starts with an order. You create it with one request, receive a paymentLink, and redirect the payer to it. The payment page handles the rest.
Requests are signed with the X-Api-Token header, see Authorization.
Endpoint
POST /v1/ordersRequest parameters
| Field | Type | Required | Description |
|---|---|---|---|
amount | string (decimal) | ✅ Yes | Order amount |
currency | string | Depends on the terminal | Order currency (ISO 4217). Required for multi-currency terminals |
serviceId | integer | ✅ Yes, for new accounts | Service to process the payment through |
externalId | string / null | ❌ No | Order ID in your system. Returned in webhooks; use it to match records |
externalUserId | string / null | ❌ No (required by some methods) | User ID in your system |
isFeeOnUser | boolean | ❌ No | Pass the fee on to the payer |
purpose | string / null | ❌ No | Payment purpose shown to the payer |
successUrl | string / null | ❌ No (if set in settings) | Redirect URL after a successful payment |
failUrl | string / null | ❌ No | Redirect URL after a failed payment |
callbackUrl | string / null | ❌ No | Webhook URL for this order. When omitted, the address from merchant settings is used |
Method-specific objects
Some countries and payment methods require additional data about the payer or the payment method. These are passed in the same request as extra fields:
| Field | Type | Used for |
|---|---|---|
customer | object | Payer details: name, email, phone, country, document. Required by most local methods |
extraParams | string | Selects a specific payment method on the terminal, for example Apple Pay or Trustly |
card | object | Card details for direct card payments |
The exact set of required fields depends on the country and the method. Find your case in Payments by country or Payment methods.
Request example
curl -X POST "https://api.riopay.online/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": "1000.50",
"serviceId": 3,
"externalId": "order_1234",
"externalUserId": "user_987",
"isFeeOnUser": true,
"purpose": "Payment for order #1234",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments"
}'Response
A successful request returns the order object. The same object is returned by the status endpoint and sent in webhooks.
{
"id": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"status": "CREATED",
"statusMessage": "Ok",
"purpose": "Payment for order #1234",
"amount": "1000.5",
"commission": "1.5",
"received": "999.0",
"currency": "EUR",
"paymentType": null,
"shopId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"terminalId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"merchantId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"externalId": "order_1234",
"externalUserId": "user_987",
"paymentLink": "https://example.com/payment?id=a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhook",
"metadata": null,
"fingerprint": null,
"ipAddress": null,
"gatewayTransactionId": null,
"payedAt": null,
"updatedAt": "2023-03-21T12:34:56Z",
"createdAt": "2023-03-21T12:34:56Z"
}Order object fields
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Order ID in our system. Use it to check the status |
status | string | Current order status, see Order statuses |
statusMessage | string / null | Human-readable status details |
purpose | string / null | Payment purpose |
amount | string | Order amount |
commission | string / null | Fee charged for the order |
received | string / null | Amount credited to your balance |
currency | string | Order currency (ISO 4217) |
paymentType | string / null | Payment method used by the payer |
shopId | string (UUID) | Shop ID |
terminalId | string (UUID) | Terminal the order is processed through |
merchantId | string (UUID) | Your merchant ID |
externalId | string / null | Order ID in your system (the value you passed) |
externalUserId | string / null | User ID in your system (the value you passed) |
paymentLink | string | Link to the payment page. Redirect the payer to it |
successUrl | string / null | Redirect URL after a successful payment |
failUrl | string / null | Redirect URL after a failed payment |
callbackUrl | string / null | Webhook URL for this order (null — merchant settings are used) |
metadata | object / null | Additional data |
fingerprint | string / null | Payer device fingerprint |
ipAddress | string / null | Payer IP address |
gatewayTransactionId | string / null | Transaction ID on the provider side |
payedAt | string / null | Payment time (ISO 8601) |
createdAt | string | Creation time (ISO 8601) |
updatedAt | string | Last update time (ISO 8601) |
Order statuses
| Status | Final | Description |
|---|---|---|
CREATED | No | Order created, payment link not yet opened |
PENDING | No | Awaiting payment |
COMPLETED | Yes | Payment successful, funds received |
FAILED | Conditionally | Payment error |
CANCELED | Conditionally | Order canceled by the system |
EXPIRED | Conditionally | Order expired before it was paid |
BLOCKED | Conditionally | Transaction blocked by the bank |
REFUND | Yes | Payment refunded to the payer. Set after COMPLETED |
CHARGEBACK | Yes | Payment disputed by the payer and reversed by the bank. Set after COMPLETED |
FAILED, CANCELED, EXPIRED and BLOCKED are not strictly final. If the bank confirms the payment later because of an error on its side, the order moves to COMPLETED and the webhook for this change is sent automatically. Be ready to receive COMPLETED for an order you have already marked as unsuccessful.
Some fields may be null depending on the processing stage. Up-to-date request and response schemas are always available in the Swagger documentation (link in the top navigation).
Redirect the payer
Redirect the payer to the paymentLink from the response. After the payment, the payer is sent to successUrl or failUrl.
Do not treat the redirect to successUrl as a payment confirmation. Only the COMPLETED status, received via webhook or the status endpoint, confirms that the funds arrived.