Customized Checkout (API-only)
Build your own checkout UI on top of the direct API — start and close Apple Pay, Google Pay, Klarna, and PayPal flows without any hosted page.
With a customized checkout you render the payment UI yourself — your own buttons, your own brand, your own page — and drive the payment over the direct API v4/v5. There is no RoxPay-hosted checkout page and no Checkout SDK iframe: every call is server-to-server, authenticated with your bearer token (see Authentication).
Each method follows the same start → close shape:
| Method | Start | Close |
|---|---|---|
| Apple Pay | GET /payments/apple-pay + POST /payments/apple-pay/session | POST /payments/charge with the wallet token |
| Google Pay | GET /payments/google-pay | POST /payments/charge with the wallet token |
| Klarna | GET /payments/klarna + POST /payments/charge | POST /payments/complete → POST /payments/capture |
| PayPal | GET /payments/paypal + POST /payments/charge | POST /payments/complete |
All examples use v4; the same body is accepted on the v5 endpoints (/api/v5/...).
Prerequisites
- Authentication — a valid bearer token
- The method enabled for your company (Klarna
KLN, PayPalPAP, Apple PayAPL, Google PayGPA): checkGET /api/v4/payments/payment-methodsor contact Rox - Wallet flows (Apple Pay / Google Pay) need no PCI activation — the charge carries no PAN
- Klarna / PayPal redirect charges need no PCI activation either: no PAN is sent or handled
The charge endpoint
Every flow ends on the same endpoint, POST /api/v4/payments/charge. The instrument travels in the PaymentMethodDetails object and its Type decides which fields are valid:
{
"Amount": 2500,
"Currency": "EUR",
"PaymentMethodDetails": {
"Type": "applepay",
"ApplePayToken": "eyJ2ZXJzaW9uIjoiRUNfdjEi..."
},
"ReturnUrl": "https://shop.example.com/return",
"StatementDescription": "Order #1001",
"Metadata": { "store_reference": "STORE-1" }
}
Rules the object enforces (422 otherwise):
- Card fields (
CardNumber,ExpirationMonth,ExpirationYear,Cvv) are only valid withType: "scheme"(PCI-scoped plain-card charging) - Wallet types (
applepay,googlepay) require exactly that wallet's token and reject everything else - Redirect types (
klarna,paypal) carry no instrument fields at all — the shopper authorizes on the provider page
ReturnUrl (https, max 2048 chars) is required: it is where the provider sends the shopper back with a redirectResult when the flow redirects (3DS challenge for cards, Klarna / PayPal confirmation pages). It is not validated against your authorized domains, but it must be an endpoint you own.
Metadata.store_reference targets a specific Adyen store — send the same StoreReference you used on the config endpoints so the session and the payment resolve to the same store.
TransactionId is your idempotency key: reusing an existing identifier returns the previously persisted transaction without a second charge.
Handling a redirect
When the response Status is REDIRECT, submit the provider page in the shopper's browser. RedirectUrl, RedirectMethod (GET or POST) and RedirectData (hidden form fields) are already in the response:
<form action="{RedirectUrl}" method="{RedirectMethod}">
<!-- one hidden input per RedirectData entry -->
<input type="hidden" name="key" value="value">
</form>
<script>document.forms[0].submit();</script>
Do not navigate to RedirectUrl with a plain GET when RedirectMethod is POST: the endpoint answers with a 405 error page.
After the shopper authorizes, the provider redirects them to your ReturnUrl with a redirectResult (query or POST body). Finalize with POST /api/v4/payments/complete:
curl -X POST https://app.roxpay.eu/api/v4/payments/complete \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"TransactionId": "TRX-0E8908817D1E",
"RedirectResult": "eyJ0eXBlIjoicmVzdWx0Ii...",
"RedirectPaymentData": "..."
}'
RedirectPaymentData is optional when the charge already stashed it. The response carries the final Status plus the same echo fields as the charge (WalletToken, CardBrand, …). For redirect methods the payment is not done until you see the final status or the webhook.
Apple Pay
Platform-managed certificate: RoxPay generates and owns the Apple Pay identifier, so no Apple Developer account is needed on your side.
1. Register the domain. Apple Pay requires the page showing the button to be a registered domain. Download the association file and publish it:
curl -o apple-domain.zip https://app.roxpay.eu/api/v4/payments/apple-pay/domain-association \
-H "Authorization: Bearer YOUR_TOKEN"
# unzip and publish the file at
# https://<domain>/.well-known/apple-developer-merchantid-domain-association
Then register the domain (hosted checkout domains are already registered):
curl -X POST https://app.roxpay.eu/api/v4/payments/payment-methods \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "PaymentMethod": "apple_pay", "ApplePay": { "Domains": ["shop.example.com"] } }'
2. Fetch the configuration.
curl "https://app.roxpay.eu/api/v4/payments/apple-pay?StoreReference=STORE-1" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"Result": true,
"Enabled": true,
"MerchantIdentifier": "000000000626598",
"DisplayName": "Rox Pay",
"StoreReference": "STORE-1",
"Brands": ["visa", "mc"]
}
Do not hardcode MerchantIdentifier: it is store- and environment-specific.
3. Run the browser flow. Apple Pay only runs on Safari (Mac / iOS) with a card in Wallet:
const request = {
countryCode: "IT",
currencyCode: "EUR",
total: { label: "Order #1001", amount: "25.00" },
supportedNetworks: config.Brands.map(b => brandToNetwork(b)), // visa, mc, maestro…
merchantCapabilities: ["supports3DS"],
};
const session = new ApplePaySession(3, request);
session.onvalidatemerchant = async (event) => {
// POST /api/v4/payments/apple-pay/session { DomainName, StoreReference }
const merchantSession = await fetchSession(event.validationURL);
session.completeMerchantValidation(merchantSession);
};
session.onpaymentauthorized = async (event) => {
const applePayToken = btoa(JSON.stringify(event.payment.token.paymentData));
// POST /api/v4/payments/charge with Type: "applepay"
chargeApplePayToken(applePayToken);
// Answer Apple immediately — do not wait for the charge result:
session.completePayment(ApplePaySession.STATUS_SUCCESS);
};
session.begin();
4. Close the flow with the charge (see The charge endpoint). The response is final — SETTLED (or AUTHORIZED with PreAuthorization: true) — and echoes the token (WalletToken, WalletType) plus the masked card data.
Google Pay
1. Fetch the configuration. The values come from your store's Adyen setup; you need them to build the button's PaymentDataRequest:
curl "https://app.roxpay.eu/api/v4/payments/google-pay?StoreReference=STORE-1" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"Result": true,
"Enabled": true,
"GatewayMerchantId": "RoxPayECOM",
"GoogleMerchantId": "000000000626598",
"StoreReference": "STORE-1",
"Brands": ["visa", "mc"]
}
GoogleMerchantId is present when Adyen returned the Google Pay MID; when absent, use your own Google Pay Business Console ID (or none on test).
2. Build the button. With the Google Pay JavaScript SDK:
const paymentDataRequest = {
apiVersion: 2,
apiVersionMinor: 0,
allowedPaymentMethods: [{
type: "CARD",
parameters: {
allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
allowedCardNetworks: config.Brands.map(b => brandToNetwork(b)), // VISA, MASTERCARD…
},
tokenizationSpecification: {
type: "PAYMENT_GATEWAY",
parameters: {
gateway: "adyen",
gatewayMerchantId: config.GatewayMerchantId,
},
},
}],
transactionInfo: {
totalPriceStatus: "FINAL",
totalPrice: "25.00",
currencyCode: "EUR",
},
merchantInfo: {
merchantId: config.GoogleMerchantId, // when provided
merchantName: "Your shop name",
},
};
3. Close the flow with the charge — the token the button produces goes straight to the API:
{
"Amount": 2500,
"Currency": "EUR",
"PaymentMethodDetails": {
"Type": "googlepay",
"GooglePayToken": "<button token string>"
},
"ReturnUrl": "https://shop.example.com/return"
}
The response is final: SETTLED, or AUTHORIZED with PreAuthorization: true (capture later). No redirect step exists for wallet tokens.
Klarna
Klarna is a redirect method: the shopper authorizes on the Klarna page, so there is nothing to configure in the browser.
1. Check availability.
curl "https://app.roxpay.eu/api/v4/payments/klarna?StoreReference=STORE-1" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"Result": true,
"Enabled": true,
"StoreReference": "STORE-1",
"Methods": [
{ "type": "klarna", "name": "Klarna" },
{ "type": "klarna_paynow", "name": "Klarna Pay Now" }
]
}
Methods lists the variants Adyen offers for the shopper's country; the charge Type is always klarna and the provider picks the variant. Send Metadata.CountryCode ("IT", "DE", …) to override the shopper country — it decides the Klarna variant and currency rules. Klarna runs in EUR markets.
2. Start the flow.
curl -X POST https://app.roxpay.eu/api/v4/payments/charge \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"Amount": 2500,
"Currency": "EUR",
"PaymentMethodDetails": { "Type": "klarna" },
"ReturnUrl": "https://shop.example.com/return",
"Metadata": { "store_reference": "STORE-1" }
}'
Response (202): Status: "REDIRECT" with RedirectUrl pointing at Klarna's authorization page. Submit it in the shopper's browser (Handling a redirect).
3. Close the flow. The shopper confirms on Klarna and lands on ReturnUrl?redirectResult=.... POST it to POST /api/v4/payments/complete. Klarna keeps the funds authorized: the completion returns Status: "AUTHORIZED" and you settle with a capture:
curl -X POST https://app.roxpay.eu/api/v4/payments/capture \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "Items": [ { "TransactionId": "TRX-0E8908817D1E" } ] }'
Omit Amount for a full capture. Release instead (POST /api/v4/payments/release) to void the authorization.
PayPal
PayPal is a redirect method too, with the same shape as Klarna.
1. Check availability.
curl "https://app.roxpay.eu/api/v4/payments/paypal?StoreReference=STORE-1" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"Result": true,
"Enabled": true,
"StoreReference": "STORE-1",
"Methods": []
}
Methods is always empty for PayPal. Requires PayPal enabled on the Adyen store (Pay Later / Pay in 3 included).
2. Start the flow.
curl -X POST https://app.roxpay.eu/api/v4/payments/charge \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"Amount": 2500,
"Currency": "EUR",
"PaymentMethodDetails": { "Type": "paypal" },
"ReturnUrl": "https://shop.example.com/return",
"Metadata": { "store_reference": "STORE-1" }
}'
Response (202): Status: "REDIRECT" with RedirectUrl pointing at PayPal.
3. Close the flow. The shopper approves on PayPal and lands on ReturnUrl?redirectResult=.... POST it to POST /api/v4/payments/complete. PayPal honors PreAuthorization on the charge: false (default) settles on completion, true returns Status: "AUTHORIZED" for a later capture (or release to void).
Reconciliation and errors
- Treat webhooks as the source of truth for the final status — especially Klarna and PayPal, which can settle asynchronously after the completion call.
TransactionId+PspReferenceappear on the webhooks as well, so correlate on those.- Validation errors are
422with the offending wire path inMessage(e.g.PaymentMethodDetails.Type); provider declines surface as400with the provider result code. - Sandbox testing: see Test cards.
Next steps
- Checkout SDK — the hosted/embedded alternative
- Payment lifecycle — statuses, capture, refunds
- Webhooks — status notifications
- Test cards — sandbox credentials