Finyx Store

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 methodMethodsWhat Finyx does
Client-sidecard, applepay, googlepayMount 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-sidepaynow, wechatpay, alipay / alipaycn / alipayhkPOST /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. Element success when local status is authorised/captured (or Airwallex intent SUCCEEDED).
  • false: card and wallets stop at authorized (Authorised / Airwallex REQUIRES_CAPTURE — Finyx still emits success). Capture later with POST /api/v4/payments/:id/capture (merchant key).
  • QR and Alipay: the API forces auto-capture. Sending false does not create an auth-only PayNow / WeChat / Alipay payment.

Method families

resolveElementType(method.type):

FamilyTypesUI
cardcardCard fields + 3DS modal (Adyen) or in-element 3DS (Airwallex)
walletapplepay, googlepayWallet buttons. Hidden when the browser cannot pay (Apple Pay needs ApplePaySession; Google Pay is skipped on iOS and non-HTTPS).
qrpaynow, wechatpayQR canvas + poll getPayment every 3s. TTL: PayNow 10 min, WeChat 2 h.
alipayalipay, alipaycn, alipayhkQR + poll, or a full-page redirect. Adyen Alipay is not embedded — its checkout page sends frame-ancestors 'none'.
redirectanything elseFull-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 → element success
  • 3DS-Error → element error

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 intent SUCCEEDED | 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.