Secure Form (Radial) Versus Secure Fields (Radial/Gr4vy)

Radial’s secure form iframe and the Radial/Gr4vy Secure Fields integration both keep card data out of your app, but they differ in authentication (how JWTs are used), where payment data flows, and how much control you get over the UI and orchestration.

High-level difference

• Radial Secure Form iframe:

  • Radial-hosted card and CVV iframes inject into your checkout.
  • You initialize Radial JS using an access token (JWT) and use createSecureForm() to render fields.
  • On submit, you call getEncryptedPaymentData() and then your backend calls Radial Payment APIs directly with the encrypted payload.

• Radial/Gr4vy Secure Fields:

  • Gr4vy-hosted field iframes (card number, expiry, CVV, etc.) embed into your own form layout.
  • You authenticate with Gr4vy using a signed JWT from your backend, create a checkout session, and then initialize Secure Fields for that session.
  • On submit, Secure Fields sends card data directly to Gr4vy, which returns a vaulted payment method or token that your backend uses with Gr4vy’s Payments API; Gr4vy then routes to configured PSPs.

Authentication and JWT usage

Radial Secure Form

• You must obtain a Radial access token (JWT) from Radial auth before using Radial JS.
• The secure iframe docs show that if the token is invalid or expired, you see an Invalid Authentication Error with errorCode 40001, indicating “provided JWT is either invalid or expired, please try with valid Access Token.”
• Flow from your perspective:
  1. Backend calls Radial auth to get an access token.
  2. Frontend includes that token when initializing Radial JS.
  3. radial.createSecureForm(customConfig) uses this token to authorize card collection and encryption.
  4. Later, your backend uses Radial APIs (with its own auth) to submit the encrypted card data received from getEncryptedPaymentData().

JWT scope: authorizes the secure form JS to operate and encrypt card data for a given merchant/context; errors show up at iframe creation time if it’s expired or invalid.

Radial/Gr4vy Secure Fields

• Gr4vy’s Secure Fields documents a Gr4vy JWT signed by your backend as the primary auth mechanism.
• Typical pattern:
  1. Your backend signs a JWT for Gr4vy containing merchant/tenant info and permissions (e.g., which buyer/checkout this session is for), using your Gr4vy private key.
  2. Your backend creates a checkout session with Gr4vy’s API using that JWT.
  3. Frontend initializes Secure Fields using the Gr4vy instance details and the session information returned from Gr4vy.
  4. On submit, Secure Fields uses that session context to vault the card and returns a token/paymentMethodId via callbacks in your frontend.

JWT scope: authorizes the creation of a checkout session and access to Gr4vy’s vault/transaction APIs, and scopes Secure Fields to that session and buyer context.

UI integration and field behavior

Radial Secure Form iframe

• You configure Radial’s secure form with a customConfig object that includes card, code, and optional savedWallet.
• Each of these maps to a secure iframe; you specify iframeConfig, style, attributes, and config to place and style them.
• Validation and events:
  • Radial JS performs real-time validation (Luhn, CVV length, card type).
  • It emits RadialSecureFormEvent with types like cardValidationSuccess, cardValidationFailed, secureCodeValidationFailed, cardEncrypted, etc., which you handle via a window event listener.
• Saved wallet:
  • If savedWallet: true, Radial only renders the CVV field and returns just the encrypted security code.
  • Multi-card: you can call createSecureForm multiple times and identify each pair via cardPairId.

Front-end implication: you mostly treat the Radial iframe as a pre-built card input widget with styling hooks and window events, and you only control outer layout and error presentation.

Radial/Gr4vy Secure Fields

• Secure Fields exposes field-level iframes for card number, expiry, CVV, and extra fields like postal code, which you place within your own markup.
• Your Secure Fields quick-start overview describes:
  • A container initialization (e.g., a Secure Fields root object).
  • Per-field configuration and mounting into DOM elements you choose.
• Events and validation:
  • Secure Fields emits per-field validity, completeness, and metadata (e.g., scheme, card brand), and you wire that into your own validation UI.
• Stored cards:
  • You can initialize Secure Fields against an existing vaulted payment method, collecting only CVV (or other required verification fields) and getting back a token suitable for reuse.

Front-end implication: you retain more layout and UX control, assembling multiple field iframes into your own form, while Gr4vy handles PCI and vaulting under the hood.

Data flow and where the payment happens

Radial Secure Form iframe

1. Shopper enters card data inside Radial’s iframes.
2. Radial JS validates and encrypts card and CVV.
3. On submit, you call radial.getEncryptedPaymentData(isSavedWallet, cardPairId) to retrieve encrypted values.
4. Your backend calls Radial Payment APIs with:
   • Encrypted card number and CVV, plus order and tender details.
5. Radial processes authorization/capture as your payment provider.

Key point: Radial is both card capture and processor; the encrypted data is only useful within Radial’s payment environment.

Radial/Gr4vy Secure Fields

1. Backend signs a JWT and creates a checkout session with Gr4vy.
2. Frontend initializes Secure Fields using the session (and any configuration provided by Radial/Gr4vy).
3. Shopper enters card data in Gr4vy’s hosted fields.
4. On submit, Secure Fields:
   • Sends card data directly to Gr4vy, which vaults it and returns a token or paymentMethodId via your configured callbacks.
5. Backend calls Gr4vy’s Payments API with that token and order details.
6. Gr4vy routes the transaction to the configured PSP or gateway according to your routing/orchestration rules.

Key point: Gr4vy is the capture and orchestration layer; the token from Secure Fields is a Gr4vy vault identifier, not a Radial-specific encryption blob.

JWT and error handling differences

• Radial Secure Form

  • If the JWT (access token) is invalid or expired, createSecureForm() fails and returns an error with errorCode: "40001" and message “Invalid Authentication Error.”
  • Other errors (missing options, JS load errors) use separate codes like 40006 or 40007.

• Radial/Gr4vy Secure Fields

  • If your Gr4vy JWT is invalid or expired, the error surfaces when creating the checkout session or when initializing Secure Fields for that session.
  • Errors typically indicate bad signature, invalid claims, or insufficient permissions, and your docs recommend regenerating a JWT and retrying session creation.

Gr4vy Secure Fields Events

Events you can expect from Gr4vy’s Secure Fields integration when using addEventListener on the Secure Fields instance or on individual fields.

Reference: Gr4vy Secure Fields events

Global events

Attach handlers to the SecureFields instance with addEventListener.

Field-level events

Attach handlers to individual fields (returned by addCardNumberField, addExpiryDateField, addSecurityCodeField, or addField).

Documentation links

Radial Documentation

https://docs.radial.com/Content/js-integration/secure-iframe.htm

Radial / Gr4vy Documentation

https://radial.mintlify.app/guides/payments/secure-fields/quick-start/overview