curl --request POST \
--url https://api.example.com/v1/payment/sale \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": "12.30",
"buyerId": "buyer_example",
"callbackUrl": "https://shop.example.com/webhooks/orsunpay",
"currency": "EUR",
"customer": {
"country": "US",
"email": "[email protected]",
"firstName": "Jane",
"lastName": "Doe"
},
"description": "Coffee beans",
"failureUrl": "https://shop.example.com/failure",
"locale": "en-US",
"merchantId": "mr_example",
"metadata": {
"cartId": "cart_example"
},
"orderId": "order_example_001",
"paymentMethod": "cr_example",
"paymentMethodInput": {},
"returnUrl": "https://shop.example.com/return",
"successUrl": "https://shop.example.com/success"
}
'{
"error": "INVALID_AMOUNT: amount 12.345 has more than 2 decimal places allowed for EUR",
"status": false
}Create deposit transaction (Sale)
Creates a new deposit transaction for customer account funding. Supports various payment methods including cryptocurrencies, e-wallets, and BNPL services. Money is a decimal string in major units ("amount": "10.00"), in the request and in the response. Without paymentMethod, or with incomplete paymentMethodInput, the response carries paymentPageUrl: the hosted payment page where the buyer picks a method and types the missing details.
curl --request POST \
--url https://api.example.com/v1/payment/sale \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": "12.30",
"buyerId": "buyer_example",
"callbackUrl": "https://shop.example.com/webhooks/orsunpay",
"currency": "EUR",
"customer": {
"country": "US",
"email": "[email protected]",
"firstName": "Jane",
"lastName": "Doe"
},
"description": "Coffee beans",
"failureUrl": "https://shop.example.com/failure",
"locale": "en-US",
"merchantId": "mr_example",
"metadata": {
"cartId": "cart_example"
},
"orderId": "order_example_001",
"paymentMethod": "cr_example",
"paymentMethodInput": {},
"returnUrl": "https://shop.example.com/return",
"successUrl": "https://shop.example.com/success"
}
'{
"error": "INVALID_AMOUNT: amount 12.345 has more than 2 decimal places allowed for EUR",
"status": false
}Authorizations
Headers
Optional, recommended. 1-255 printable ASCII characters without spaces (e.g. a UUID v4) generated once per payment attempt and reused for every retry of it. Scoped to the merchant, kept 24 h. A retry of a finished request returns the stored status and body with Idempotency-Replayed: true; a retry while the first request is still running gets 409 IDEMPOTENCY_IN_PROGRESS with Retry-After; the same key with a different body or endpoint gets 422 IDEMPOTENCY_KEY_REUSED.
"0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10"
Body
Amount as a decimal string in major units of currency: "12.30" EUR, "5000" JPY, "0.00000001" BTC. Must be greater than zero. JSON numbers (12.3, 1230) are rejected with 400. At most 18 decimals here; the payment core also rejects more decimals than the currency allows ("12.345" EUR, "1.5" JPY).
^(0|[1-9]\d{0,19})(\.\d{1,18})?$"10.00"
Buyer ID in merchant system
"customer_123"
Callback URL
"https://example.com/callback"
Currency
"USD"
Failure URL
"https://example.com/failure"
Merchant ID
"mr_clyv2goxb0000z8b8j5y6fl1j"
Transaction ID in merchant system. The pl_ prefix is reserved for payment links (422 ORDER_ID_RESERVED).
"transaction_123"
Return URL
"https://example.com/return"
Success URL
"https://example.com/success"
Customer
Show child attributes
Show child attributes
{
"address": "123 Main St",
"address2": "Apt 1",
"city": "Anytown",
"country": "US",
"dob": "1990-01-01",
"email": "[email protected]",
"firstName": "John",
"ip": "123.45.67.89",
"lastName": "Doe",
"phone": "+1234567890",
"state": "CA",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
"zip": "12345"
}
Order description shown to the buyer on the hosted payment page
255"2 x Coffee beans, 1 kg"
Locale in BCP 47 format
en-US, ru-RU, uk-UA, en-GB, pl-PL, cs-CZ, de-DE, de-AT, de-CH "en-US"
Metadata: at most 16 KiB encoded JSON, 50 entries per container, nesting depth 5.
{}
Payment method (credential config id). Omit it to let the buyer pick one of your methods on the hosted payment page: the response then carries paymentPageUrl.
"cr_clyv2goxb0000z8b8j5y6fl1j"
Payment method input
{}
Response
Transaction created, or status: false with a business error (e.g. INVALID_AMOUNT: ... when the amount has more decimals than the currency allows). Money fields are decimal strings in major units. LIVEMODE_MISMATCH is a declined transaction returned with status: true, not an HTTP error; no PSP operation is sent.
Operation status
true
Error message (if operation failed)
"Payment method not available"
Validated app confirmation or voucher instructions for the payer
Sales only: the hosted payment page, when the buyer still has to pick a method or type payment details (no paymentMethod, or incomplete paymentMethodInput). Redirect the buyer there; url carries the same value. Valid until the sale expires (48 h by default); the token in it is the only key to the page, so treat the URL like a secret link.
"https://pay.example.com/pay/hpp1.dHJfeHYwcDJxNXNjb2NuZHBlamswbnVkNzVxOjE3NjAxMDAwMDA.X8f…"
Accepted payment awaiting confirmation. On PSP_OUTCOME_UNKNOWN poll the transaction; do not resubmit or create a new order.
true
Transaction details
Show child attributes
Show child attributes
Redirect URL for payment completion (if required)
"https://payment-provider.com/pay/abc123"