Payment collection (v4)
How Finyx checkout maps onto /api/v4/payments. SDK install and element APIs stay on the integration guide. Statuses, webhooks, capture/refund APIs, and the QA matrix live in the backend docs (payment_backend/docs/payment-collection-flow.md and payment-collection-test-cases.md).
Finyx uses the outlet checkout key in the browser. Capture and refund need a merchant key on your server (or the dashboard). Do not put the merchant key in client code.
Client-side vs server-side
| Who collects the method | Methods | What Finyx does |
|---|---|---|
| Client-side | card, applepay, googlepay | Mount Adyen Web or Airwallex Elements. PAN / wallet token never hits your DOM. Adyen then POST /api/v4/payments/:id/confirm. Airwallex confirms with client_secret inside the SDK. |
| Server-side | paynow, wechatpay, alipay / alipaycn / alipayhk | POST /api/v4/payments already starts the PSP session. Finyx only shows a QR (and polls) or follows a redirect. |
You can still create a card payment on your server and pass client_secret / clientKey into a Finyx element. Collection of the card or wallet stays client-side.
autoCapture
Passed on createElement / createPayment (autoCapture ?? true). Finyx also sends iframe3ds: true.
true(default): authorize and capture after the customer pays. Elementsuccesswhen local status is authorised/captured (or Airwallex intentSUCCEEDED).false: card and wallets stop at authorized (Authorised/ AirwallexREQUIRES_CAPTURE— Finyx still emitssuccess). Capture later withPOST /api/v4/payments/:id/capture(merchant key).- QR and Alipay: the API forces auto-capture. Sending
falsedoes not create an auth-only PayNow / WeChat / Alipay payment.
Method families
resolveElementType(method.type):
| Family | Types | UI |
|---|---|---|
card | card | Card fields + 3DS modal (Adyen) or in-element 3DS (Airwallex) |
wallet | applepay, googlepay | Wallet buttons. Hidden when the browser cannot pay (Apple Pay needs ApplePaySession; Google Pay is skipped on iOS and non-HTTPS). |
qr | paynow, wechatpay | QR canvas + poll getPayment every 3s. TTL: PayNow 10 min, WeChat 2 h. |
alipay | alipay, alipaycn, alipayhk | QR + poll, or a full-page redirect. Adyen Alipay is not embedded — its checkout page sends frame-ancestors 'none'. |
redirect | anything else | Full-page window.location to the PSP URL |
3DS
Airwallex runs 3DS inside Elements. Adyen redirect / redirect_iframe and native 3DS2 (IdentifyShopper / ChallengeShopper) use the Finyx modal. The v4 callback postMessages:
3DS-Success→ elementsuccess3DS-Error→ elementerror
returnUrl is optional. Pass it for the merchant result page after full-page flows. Finyx always creates payments with iframe3ds: true so Adyen can return in-page.
Polling QR
After createPayment, if next_action.qrcode (or Adyen action.qrCodeData) is present, Finyx polls GET /api/v4/payments/:id and uses interpretPaymentInfo:
- Success: local
Authorised|Scheduled|Processing Settlement|Settled, or intentSUCCEEDED|REQUIRES_CAPTURE - Failure:
Cancelled/FAILED/EXPIRED/AUTHENTICATION_FAILED
Listen for success / error on the element; do not assume the first createPayment response is final for QR.
After collection
Cancel uncaptured payments with the outlet key (POST /:id/cancel). Capture and refund with the merchant key. Merchant webhooks (transaction.created, authorized, capturing, captured, refunded, canceled) are configured on the outlet, not in this SDK.