Radial OrderCreate Field Mapping

This guide explains how persisted payment data maps into Radial OrderCreateRequest XML, including units, transformations, and payment-type-specific field mappings.

Shadow mode

These instructions are for production mode not onboarding or shadow mode. Shadow mode is defined as a period of time that a Radial Fraud merchant on Fraud Zero is still processing on Fraud Zero and at the same time having transactions evaluated for Fraud by Riskified. Details for each merchant’s shadow mode process are inlcuded in their specific documentation -as requirements differ. Please consult your specific integration guides on your shadow mode process.

1. Data flow

Sample stores checkout and payment outcomes. OrderCreateRequest XML can be built from these data sources depending on how the merchant processes responses and relies on webhooks to update the source of truth.

2. Radial OrderCreate payment mapping (Gr4vy -> XML)

This document is for integrators who must fill the <Payment><Payments>...</Payments></Payment> section of a Radial OrderCreateRequest. It assumes you already have (or will store) the fields Gr4vy sends on transaction webhooks and/or transaction API responses, and you need to map Gr4vy concepts to XML elements.

It does not cover cart lines or shipping addresses.

OverArt backend behavior (payment -> XML)

Source of truth: Radial payment XML can be generated from persisted payment details (transactions.payments), including columns populated from Gr4vy webhooks and process-payment flows (for example payment_service_transaction_id, avs_response_code, radial_response_code, raw_response_code).
ExtendedAuthorizationResponseCodes: ResponseCodeDescription and ReasonCode are set to the same resolved value as Authorization/ResponseCode: sanitized radial_response_code, else sanitized raw_response_code, else the literal APPROVED.

3. Where Gr4vy puts the data

Gr4vy payloads are usually JSON. The same facts can appear under slightly different keys depending on whether you read the root, a transaction object, a target object (common on webhooks), or a nested payment_method / paymentMethod object.

Typical places to look:

What you need	Common Gr4vy locations (check what your integration receives)
Transaction id	Root or `transaction.id` (UUID string)
Amount	`amount` on transaction or target - integer in the smallest currency unit (for example cents)
Authorized amount	`authorized_amount` / `authorizedAmount` when present - same units
Status / outcome	`status` on transaction or target
Payment method type	`payment_method_type`, nested `payment_method.type`, or string `method` on the payment method object
Card brand / scheme	`scheme`, `card_scheme`, `brand`, or `network` on payment method or nested `details` / `card_details`
Saved payment method id	`payment_method.id` or `payment_method_id` (UUID) when the instrument is tokenized
Processor auth reference	`payment_service_transaction_id` / `paymentServiceTransactionId` on transaction or target
AVS / CVV (and Amex extras)	`avs_response_code`, `cvv_response_code`, and optionally `phone_response_code`, `name_response_code`, `email_response_code` (snake_case or camelCase)
Card expiration	`expiration_date` / `expiration` on payment method or card details
Order / cart correlation	`external_identifier` or similar on the transaction (how you tie the payment to your order)

Normalize these into the fields your mapper uses, then emit one XML payment child per Gr4vy transaction you include on the order (for example split tender = two transactions = two XML blocks).

4. Amounts: minor units -> Radial decimals

Gr4vy amounts are in minor units (integer). Radial XML expects decimal strings with two fractional digits (major units).

Rule: xml_amount = format_minor(minor), where format_minor divides by 100 and prints two decimals (for example 4999 -> "49.99").

Use the same rule for every money field in the payment XML (Amount, AmountAuthorized, and authorization amounts where applicable).

If your currency has an exponent other than 2, align with Radial and your OMS partner; Gr4vy still documents amounts in minor units for standard currencies.

5. Choose the XML wrapper and tender type

Radial expects one of three shapes under <Payments>: <CreditCard>, <PayPal>, or <StoredValueCard>. The choice comes from how Gr4vy classifies the payment method and card scheme (for cards).

Use this decision order (first match wins):

If Gr4vy indicates…	XML element	`<TenderType>` (inside `PaymentContext`)
PayPal (for example payment method type contains `paypal`)	`<PayPal>`	`PY`
Gift / stored value / SVS-style method (type contains `gift`, `stored`, or `svs`)	`<StoredValueCard>`	`SP`
Visa	`<CreditCard>`	`VC`
Mastercard	`<CreditCard>`	`MC`
American Express	`<CreditCard>`	`AX`
Discover	`<CreditCard>`	`DC`
Generic card or unknown scheme but clearly a card	`<CreditCard>`	`VC` (default card tender)

PayPal XML always uses a fixed account placeholder: <PaymentAccountUniqueId isToken="false">PAYPAL</PaymentAccountUniqueId>

For this pattern, do not copy a Gr4vy PayPal account id into that element.

6. Values from your order system (not Gr4vy)

These fields are required in payment XML but come from your order context, not Gr4vy’s card object.

XML path	What to put
`PaymentContext/PaymentSessionId`	A stable id for checkout session or order (commonly your order number or internal order id). Use the same value for every payment on that order.
`PaymentRequestId`	A stable unique id per payment - typically Gr4vy transaction id so retries and support tracing line up.
`CreateTimeStamp`	When authorization succeeded (ISO-8601). Use Gr4vy authorization timestamp when available; otherwise `created_at`, webhook time per policy, or your internal create timestamp.

7. `<CreditCard>` field mapping

Radial XML element	Source (Gr4vy / your store)	Required	Notes
`PaymentContext/PaymentSessionId`	Your order or session id	No	See section 6
`PaymentContext/TenderType`	From section 5 (`VC`, `MC`, `AX`, `DC`)	Yes
`PaymentContext/PaymentAccountUniqueId`	Saved payment method UUID converted to base62 (22 chars minimum), or `"card"`	Yes	If tokenized id exists: `isToken="true"` and include UUID body. If no id: `isToken="false"`. If literal `"card"`: `isToken="false"`.
`PaymentRequestId`	Gr4vy transaction id	No	See section 6
`CreateTimeStamp`	Authorization time	Yes	See section 6
`Amount`	Transaction `amount` (minor -> decimal)	No	See section 4
`Authorization/ResponseCode`	Mapped Radial-style code if available; else Gr4vy raw response code; else safe default like `APPROVED` only if OMS agrees	Yes	Sanitize nested or quoted strings before writing XML.
`Authorization/BankAuthorizationCode`	`payment_service_transaction_id` / processor reference	Yes	Often required for card. May be empty string only if truly absent and OMS allows it.
`Authorization/CVV2ResponseCode`	CVV result from Gr4vy	No	Omit value when absent (do not emit literal `null`).
`Authorization/AVSResponseCode`	AVS result from Gr4vy	Yes	Omit value when absent (do not emit literal `null`).
`Authorization/PhoneResponseCode`, `NameResponseCode`, `EmailResponseCode`	Gr4vy Amex-style fields	No	Only for American Express tender (`AX`) and only when present.
`Authorization/ExtendedAuthorizationResponseCodes/ResponseCodeDescription`	Same resolved string as `Authorization/ResponseCode` (radial -> raw -> `APPROVED`)	Yes	Mirrors persisted `radial_response_code` / `raw_response_code` after sanitize.
`Authorization/ExtendedAuthorizationResponseCodes/ReasonCode`	Same resolved string as `Authorization/ResponseCode` (radial -> raw -> `APPROVED`)	Yes	Mirrors persisted `radial_response_code` / `raw_response_code` after sanitize.
`Authorization/AmountAuthorized`	`authorized_amount` if set, else same as `Amount`	No	Minor -> decimal (section 4)
`ExpirationDate`	Card `expiration_date` / `expiration` from Gr4vy	No	Omit element if blank.

8. `<PayPal>` field mapping

Radial XML element	Source	Required	Notes
`Amount`	Transaction amount (minor -> decimal)	No
`AmountAuthorized`	Authorized amount or amount	Yes
`PaymentContext/PaymentSessionId`	Your order or session id	No	See section 6
`PaymentContext/TenderType`	Always `PY`	Yes
`PaymentContext/PaymentAccountUniqueId`	Fixed: `PAYPAL`, `isToken="false"`	No
`CreateTimeStamp`	Same policy as card	Yes	See section 6
`PaymentRequestId`	Gr4vy transaction id	No	See section 6
`Authorization/ResponseCode`	Same precedence as card	Yes	This pattern does not include bank auth / CVV / AVS children.

9. `<StoredValueCard>` field mapping

Radial XML element	Source	Required	Notes
`PaymentContext/PaymentSessionId`	Your order or session id	No	See section 6
`PaymentContext/TenderType`	`SP` (gift / stored value in this mapping)	Yes	Final value depends on gift card processor contract.
`PaymentContext/PaymentAccountUniqueId`	Saved payment method UUID converted to base62, or `"gift-card"`	Yes	`isToken="true"` when tokenized, `isToken="false"` for `"gift-card"`.
`PaymentRequestId`	Gr4vy transaction id	No	See section 6
`CreateTimeStamp`	Same policy as card	Yes	See section 6
`Amount`	Transaction amount (minor -> decimal)	Yes	This shape often has no separate `Authorization` subtree. Confirm with OMS XSD or partner.

10. Response codes and wrapped values

Gr4vy or processor systems may return AVS/CVV or status strings in nested or nullable encodings. Before writing XML:

Trim whitespace.
If value is logically empty, omit optional values (CVV2ResponseCode, AVSResponseCode) instead of emitting null as text.

If you map Gr4vy outcomes to Radial-specific auth response codes, apply that mapping before writing Authorization/ResponseCode; otherwise pass through the processor string your OMS expects.

The ExtendedAuthorizationResponseCodes block mirrors that same resolved ResponseCode string for both ResponseCodeDescription and ReasonCode.

11. Order-level custom attributes tied to payments

Some Radial integrations also send order <CustomAttributes> entries that reference payment details, for example:

Processor or gateway transaction id (often your internal id for the first payment on the order).
Fraud or session correlation id from checkout/risk systems.

Keys and requiredness are contract-specific.

12. Sample: persisted Gr4vy response

{
  "type": "transaction",
  "id": "91236c5a-eadf-4ea7-a077-488a51f59888",
  "reconciliation_id": "4Ps4hiW1C7ugVqioYyMJvU",
  "merchant_account_id": "secure-fields-capture",
  "currency": "CAD",
  "amount": 2091,
  "status": "authorization_succeeded",
  "authorized_amount": 2091,
  "captured_amount": 0,
  "refunded_amount": 0,
  "settled_currency": null,
  "settled_amount": 0,
  "settled": false,
  "country": "CA",
  "external_identifier": "SFCS-090501",
  "intent": "authorize",
  "payment_method": {
    "type": "payment-method",
    "approval_url": null,
    "country": null,
    "currency": null,
    "details": {
      "bin": "222240",
      "card_type": null,
      "card_issuer_name": null
    },
    "expiration_date": "03/30",
    "fingerprint": "b959707dff1ec859c26ee892e1e4677e27f287747899cdf04bb51a94f340c96a",
    "label": "0005",
    "last_replaced_at": null,
    "method": "card",
    "mode": "card",
    "scheme": "mastercard",
    "id": "c5f141a0-fd78-4f04-9259-0d1dbd1de179",
    "approval_target": null,
    "external_identifier": null,
    "payment_account_reference": "fEh1QAgDtJENYP139PCPMOPG5BRq9"
  },
  "method": "card",
  "instrument_type": "pan",
  "error_code": null,
  "payment_service": {
    "type": "payment-service",
    "id": "1af984c1-ebd8-4304-b6a7-db6d22f5994f",
    "payment_service_definition_id": "adyen-card",
    "method": "card",
    "display_name": "Adyen"
  },
  "pending_review": false,
  "buyer": {
    "type": "buyer",
    "id": "e99744e8-b281-4885-9921-462a8a797a8b",
    "display_name": "Luc Dubois",
    "external_identifier": "buyer_1776198110641",
    "billing_details": {
      "first_name": "Luc",
      "last_name": "Dubois",
      "email_address": "luc.dubois@example.ca",
      "phone_number": "+15145550202",
      "address": {
        "city": "Montreal",
        "country": "CA",
        "postal_code": "H3B 1A6",
        "state": "Quebec",
        "state_code": "CA-QC",
        "house_number_or_name": "456",
        "line1": "456 Rue Sainte-Catherine",
        "line2": null,
        "organization": null
      },
      "tax_id": null
    },
    "account_number": null
  },
  "raw_response_code": null,
  "raw_response_description": null,
  "shipping_details": {
    "first_name": "Luc",
    "last_name": "Dubois",
    "email_address": "luc.dubois@example.ca",
    "phone_number": "+15145550202",
    "address": {
      "city": "Montreal",
      "country": "CA",
      "postal_code": "H3B 1A6",
      "state": "Quebec",
      "state_code": "CA-QC",
      "house_number_or_name": "456",
      "line1": "456 Rue Sainte-Catherine",
      "line2": null,
      "organization": null
    },
    "id": "968eea4a-ec88-4c56-9eca-83283f28ffdc",
    "buyer_id": "e99744e8-b281-4885-9921-462a8a797a8b",
    "type": "shipping-details"
  },
  "checkout_session_id": null,
  "gift_card_redemptions": [],
  "gift_card_service": null,
  "created_at": "2026-04-14T20:21:51.360920+00:00",
  "updated_at": "2026-04-14T20:21:52.843130+00:00",
  "disputed": false,
  "airline": null,
  "auth_response_code": null,
  "avs_response_code": null,
  "cvv_response_code": "match",
  "anti_fraud_decision": null,
  "payment_source": "ecommerce",
  "merchant_initiated": false,
  "is_subsequent_payment": false,
  "cart_items": [
    {
      "name": "Green Wall Art",
      "quantity": 1,
      "unit_amount": 1501,
      "discount_amount": 0,
      "tax_amount": 0,
      "external_identifier": null,
      "sku": "2",
      "upc": null,
      "product_url": "https://overart.us/products/2",
      "image_url": null,
      "categories": null,
      "product_type": "physical",
      "seller_country": null,
      "tax_exempt": null,
      "unit_of_measure": null,
      "commodity_code": null,
      "description": null,
      "duty_amount": null,
      "shipping_amount": null
    }
  ],
  "statement_descriptor": null,
  "scheme_transaction_id": "TF9D2TR230414",
  "three_d_secure": null,
  "payment_service_transaction_id": "GSHKW78R9JN73PV5",
  "additional_identifiers": {
    "payment_service_authorization_id": "GSHKW78R9JN73PV5",
    "payment_service_capture_id": null,
    "payment_service_processor_id": null
  },
  "metadata": null,
  "authorized_at": "2026-04-14T20:21:52.750391+00:00",
  "captured_at": null,
  "voided_at": null,
  "canceled_at": null,
  "approval_expires_at": null,
  "buyer_approval_timedout_at": null,
  "intent_outcome": "succeeded",
  "multi_tender": false,
  "account_funding_transaction": false,
  "recipient": null,
  "merchant_advice_code": "24",
  "installment_count": null,
  "session_token": null,
  "tax_amount": null,
  "merchant_tax_id": null,
  "purchase_order_number": null,
  "customer_reference_number": null,
  "amount_includes_tax": null,
  "supplier_order_number": null,
  "duty_amount": null,
  "shipping_amount": null,
  "iso_response_code": null
}

13. XML custom attributes

For OrderCreateRequest, three custom attributes should be updated/created from Gr4vy and Beacon data.

As discussed in fraud guidance, Beacon JavaScript is placed on web pages to collect behavior and device signals.

Previously, device fingerprint data was sent with key RDFUID:

<CustomAttributes>
  <Attribute>
    <Key>RDFUID</Key>
    <Value>0cb4c6e2-981f-4b77-a9b1-c5006c2ee76d</Value>
  </Attribute>
  ...
</CustomAttributes>

For Riskified, reuse the RDFUID key and set value to BEACON_ + Beacon id. The prefix is always required:

<CustomAttributes>
  <Attribute>
    <Key>RDFUID</Key>
    <Value>BEACON_12390aehber32ck</Value>
  </Attribute>
  ...
</CustomAttributes>

If no Beacon id is available, keep the prefix-only value:

<Value>BEACON_</Value>

Two additional attributes are required:

Gr4vyTransactionId: Gr4vy transaction id.
RiskifiedOrderId: Gr4vy reconciliation_id (the id Gr4vy sends to Riskified during fraud review).

Example:

<CustomAttributes>
  ...
  <Attribute>
    <Key>Gr4vyTransactionId</Key>
    <Value>91236c5a-eadf-4ea7-a077-488a51f59888</Value>
  </Attribute>
  <Attribute>
    <Key>RiskifiedOrderId</Key>
    <Value>4Ps4hiW1C7ugVqioYyMJvU</Value>
  </Attribute>
  ...
</CustomAttributes>