Cards
Host-to-Host card payment integration
H2H (Host-to-Host) integration allows you to accept payments directly through the API, bypassing the payment form. This gives you full control over the payment process.
Before you start
How to authorize your requests
This integration is not available for all merchants. Check availability with your manager.
Creating an Order
Before sending card data, you need to create an order and get its UUID from the id field.
How to create orders
Sending Card Data
Send card data to the following endpoint:
POST /v1/orders/{orderId}/h2h/cardRequest Example
curl -X POST "https://api.riopay.online/v1/orders/{orderId}/h2h/card" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"cardNumber": "4111111111111111",
"expiryDate": "12/25",
"cardholderName": "John Doe",
"cvv": "123"
}'Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| cardNumber | string | ✅ Yes | Card number |
| expiryDate | string | ✅ Yes | Expiry date (MM/YY) |
| cardholderName | string | ✅ Yes | Cardholder name |
| cvv | string | ✅ Yes | CVV/CVC code |
If the response returns order information — the card data is valid and accepted. Now you need to check if SMS code verification is required.
Checking SMS Code Requirement
Check the H2H transaction status:
GET /v1/orders/{orderId}/h2h/statusRequest Example
curl -X GET "https://api.riopay.online/v1/orders/{orderId}/h2h/status" \
-H "X-Api-Token: YOUR_API_TOKEN"Response Example
{
"isSmsRequired": true,
"status": "PROCESSING"
}Response Fields
| Field | Description |
|---|---|
| isSmsRequired | true — SMS code verification is required |
| status | Current H2H transaction status |
Sending SMS Code
Sending the code means you are passing the code from the payer's bank SMS to the API. This is NOT sending an SMS to the user!
Send the SMS code to the endpoint:
POST /v1/orders/{orderId}/h2h/codeRequest Example
curl -X POST "https://api.riopay.online/v1/orders/{orderId}/h2h/code" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"code": "123456"
}'Verification Algorithm
- Successful response — code accepted, continue checking status
- Keep checking H2H transaction status while
status = "PROCESSING" - If
isSmsRequiredbecomestrueagain — code was invalid, request it again
H2H Statuses
H2H transaction statuses are NOT the same as main order statuses. They describe the internal Host-to-Host payment process. Always confirm the final result with the order status and webhook messages.
Monitor both status streams:
- Poll H2H status (
/orders/{orderId}/h2h/status) until terminal state - Webhook order events (final payment confirmation)
H2H Status List
| Status | Description |
|---|---|
| INITIALIZING | H2H is initializing |
| PROCESSING | H2H is processing (validation, 3-D Secure, anti-fraud, etc.) |
| SUCCESS | H2H stage completed successfully (wait for final order status via webhook) |
| CANCELLED | H2H payment cancelled |
| FAILED | H2H failed with error |
| EXPIRED | H2H session expired |
Processing Recommendations
- Poll status while it's
INITIALIZINGorPROCESSING - On
SUCCESS— proceed to check final order status and wait for webhook event - On terminal
CANCELLED,FAILED,EXPIRED— stop polling and record unsuccessful result - If status is
PROCESSINGafter sending SMS code, continue waiting; if code is required again (isSmsRequired = true), request it again
Only the order status (via webhook / direct request) finally confirms the funds deduction. SUCCESS status at H2H level is an intermediate success.
Overall H2H Integration Process
Checking Order Status
After the H2H process is complete, check the final order status: