Skip to navigation
ReferenceFeaturesRisk checksExternal risk checks

Riskified

When processing transactions through the IXOPAY platform, Riskified external risk checks can be utilized to enhance your transaction security. This guide covers the fields Riskified expects and the steps required to initiate these checks.

Transaction fields

Riskified fraud screening relies primarily on standard fields already used by the Transaction API, enriched with a small set of extraData keys that have no standard field equivalent.

Standard fields

IXOPAY API fieldRiskified API fieldRequiredNotes
amountorder.total_priceYesDecimal string, e.g. 49.99
currencyorder.currencyYesISO 4217, e.g. EUR
languageorder.client_details.accept_languageRecommendedISO 639-1, e.g. en. extraData["3ds:browserLanguage"] — the browser language observed during a 3DS/redirect flow — takes precedence over this field when present

customer object fields

IXOPAY API fieldRiskified API fieldRequiredNotes
customer.emailorder.customer.emailYesMax 255 characters
customer.emailVerifiedorder.customer.verified_emailRecommendedBoolean
customer.firstNameorder.customer.first_nameRecommendedUsed for both billing and shipping; max 50 characters
customer.lastNameorder.customer.last_nameRecommendedUsed for both billing and shipping; max 50 characters
customer.ipAddressorder.browser_ipYesIPv4 or IPv6; max 50 characters. Falls back to extraData["3ds:browserIpAddress"] — the client IP observed during a 3DS/redirect flow — when not set
customer.billingAddress1, customer.billingAddress2, customer.company, customer.billingCity, customer.billingState, customer.billingPostcode, customer.billingCountry, customer.billingPhoneorder.billing_address.address1, .address2, .company, .city, .province/.province_code, .zip, .country/.country_code, .phoneRecommendedBilling address, billingCountry as ISO 3166-1 alpha-2
customer.shippingAddress1, customer.shippingAddress2, customer.shippingCompany, customer.shippingCity, customer.shippingState, customer.shippingPostcode, customer.shippingCountry, customer.shippingPhoneorder.shipping_address.address1, .address2, .company, .city, .province/.province_code, .zip, .country/.country_code, .phoneRecommendedShipping address, shippingCountry as ISO 3166-1 alpha-2
customer.identificationorder.customer.idConditionalFallback only — takes effect when no customer profile (vault) is linked to the transaction, which normally supplies this ID. Left empty if neither is set. Riskified requires one of the two sources whenever customer.extraData["account_type"] is registered.

items[] array fields

Include one entry per product in the order.

IXOPAY API fieldRiskified API fieldRequiredNotes
items[n].priceline_items[].priceRecommendedDecimal string or number
items[n].quantityline_items[].quantityRecommendedInteger ≥ 1
items[n].nameline_items[].title; also the fallback for line_items[].brandRecommendedProduct display name; always sent as title, and used as brand unless items[n].extraData.brand is set
items[n].identificationline_items[].sku; also the fallback for line_items[].product_idRecommendedYour SKU/product ID; always sent as sku, and used as product_id unless items[n].extraData.product_id is set
items[n].descriptionline_items[].categoryOptionalUsed as a fallback product category unless items[n].extraData.category is set
items[n].extraData.product_idline_items[].product_idOptionalDistinct product ID, if different from the SKU
items[n].extraData.categoryline_items[].categoryOptionalProduct category; takes precedence over items[n].description
items[n].extraData.brandline_items[].brandOptionalBrand name; takes precedence over items[n].name
items[n].extraData.sub_categoryline_items[].sub_categoryOptionalProduct sub-category
items[n].extraData.requires_shippingline_items[].requires_shippingOptionaltrue/false or 1/0
items[n].extraData.delivered_toline_items[].delivered_toConditionalRequired for mixed shipment orders. Either shipping_address or store_pickup

l2l3Data fields

IXOPAY API fieldRiskified API fieldRequiredNotes
l2l3Data.freightAmountshipping_lines.priceRecommendedTransaction-level total shipping cost
items[n].l2l3Data.typeline_items[].product_typeYesEither physical or digital; sent verbatim, so any other value is rejected by Riskified

extraData fields

Custom key-value pairs passed inside the transaction-level extraData object.

extraData keyRiskified API fieldRequiredNotes
extraData["riskified_session_id"]order.cart_tokenAutomatic — usually set for youSession ID from the Riskified beacon script. Attached to the payment token by payment.js at tokenization, or seeded with the transaction UUID by the HPP beacon script — see Initializing the risk script. Only set this manually if your integration uses neither path. Falls back to the transaction UUID if not set
extraData["referring_site"]order.referring_siteOptionalThe webpage the customer arrived from before checkout — not the payment page itself (e.g. an external referrer like https://search.example.net/?q=artisan+goods, or an internal one like https://shop.example.org/products/shoes)
extraData["source"]order.sourceYesRiskified enum, sent through as-is — not free text. One of: desktop_web, mobile_web, mobile_app, mobile_app_android, mobile_app_ios, web, chat, third_party, phone, in_store, shopify_draft_order, unknown, subscription, ai_agent. Any other value is rejected by Riskified
extraData["user_agent"]order.client_details.user_agentRecommendedBrowser User-Agent string. Falls back to extraData["3ds:browserUserAgent"] when not set
extraData["total_discounts"]order.total_discountsYesTotal discount amount; send 0 if no discounts apply
extraData["shipping_title"]shipping_lines.titleRecommendedDisplay name of the selected shipping method
extraData["note"]order.noteOptionalFree-text note about the order
extraData["order_id"]order.idOptionalYour own order ID. If set, it’s used instead of the transaction UUID and reused for every subsequent event (checkoutDenied, decision) linked to this transaction

customer.extraData fields

Custom key-value pairs passed inside the extraData object of the customer object.

customer.extraData keyRiskified API fieldRequiredNotes
customer.extraData["account_type"]order.customer.account_typeRecommendedguest or registered
customer.extraData["account_creation_date"]order.customer.created_atRecommendedISO 8601 timestamp; falls back to the transaction date if omitted

Automatically populated fields

These order-level fields are derived entirely from existing transaction and merchant data — there’s nothing to configure.

Riskified fieldSource
order.emailCustomer email (duplicated at the top level of order, in addition to order.customer.email)
order.created_atTransaction creation timestamp
order.vendor_nameMerchant name configured on the project
order.gatewayAdapter/gateway name; _3ds is appended when the transaction carries a 3D Secure liability shift

Payment details

IXOPAY platform also builds payment_details automatically from the transaction’s card and BIN data. The shape sent depends on the payment method, and both shapes are sent with the decide and decision calls.

Card payments :

Riskified fieldSource
typecard
avs_result_codeAVS result code recorded on the transaction
cvv_result_codeCVV2 match code from the transaction result data
credit_card_binCard BIN digits
credit_card_companyCard brand from the BIN lookup
credit_card_countryIssuing country (ISO 3166-1 alpha-2) from the BIN lookup
credit_card_numberMasked PAN, e.g. XXXX-XXXX-XXXX-1234
authorization_idScheme transaction identifier from the payment network response
authentication_result.liability_shiftDerived from the card’s ECI value; true for an authenticated or attempted 3D Secure liability shift
authentication_result.eciECI value recorded on the card

PayPal payments

Riskified fieldSource
payment_typepaypal
payer_emailWallet owner email recorded on the transaction, if available
midMerchant ID from the connector’s configuration

Decision

decision is sent automatically once the transaction succeeds, to confirm the approval to Riskified. It carries the same payment_details shape as decide, plus:

Riskified fieldSource
decision.external_statusAlways approved — IXOPAY platform only reports successful transactions this way
decision.decided_atTransaction creation timestamp
decision.amountTransaction amount
decision.currencyTransaction currency

Checkout denied

If a payment or validation error occurs after the initial decide call, IXOPAY platform automatically sends a minimal checkoutDenied call:

Riskified fieldSource
checkout.idSame order ID resolved for the decide call
checkout.payment_details[0].authorization_error.created_atTransaction timestamp
checkout.payment_details[0].authorization_error.error_codeError code from the transaction error
checkout.payment_details[0].authorization_error.messageError message from the transaction error

Initializing the risk script

Riskified correlates its device fingerprinting beacon with an order via a session ID (cart_token). How that session ID reaches the transaction depends on whether you use payment.js or an IXOPAY platform hosted payment page.

  • Using payment.js
  • Without payment.js

With payment.js, the Riskified beacon is handled automatically once an active Riskified risk rule is configured: the beacon loads on the merchant’s page, and its session ID is attached to the payment token as additionalData.riskified_session_id during tokenization. When the transaction is created with that transactionToken, the session ID is carried over as extraData["riskified_session_id"] before the risk check runs.

important

Tokenize first, then create the transaction. The beacon session ID travels with the token — a transaction created before tokenization cannot carry it and falls back to the transaction UUID as cart_token.

If Init Scripts Automatically is disabled on the connector, initialize the beacon manually:

<script>
  const payment = new PaymentJs("1.2");
  payment.init("public-integration-key", "number_div", "cvv_div", (payment) => {
    // ...
    try {
      payment.initRiskScript({ type: "riskified" }, function (sessionId) {
        // beacon loaded; sessionId will be attached automatically at tokenize
      });
    } catch (exception) {
      //this might happen on an invalid configuration at risk profile or connector level
    }
  });
</script>

If your payment form is an IXOPAY platform hosted payment page instead of payment.js or your own checkout page, the Riskified decide call is made when the transaction is created — before the customer opens the payment page — so a session ID generated on the page can never reach that call. Instead, seed the beacon with the transaction UUID : IXOPAY platform automatically sends the UUID as cart_token when no riskified_session_id extra data is present.

Add to the payment template:

<script src="https://gateway.ixopay.com/js/risk-scripts/riskified-dc.min.js"></script>
<script>
  // retrieve your shop domain from your Riskified dashboard
  const riskifiedShopDomain = "your-shop-domain";
  const riskifiedDc = new RiskifiedDcHandler(riskifiedShopDomain, document.getElementById("uuid").value);
  riskifiedDc.initRiskifiedDc();
</script>

Remember to accurately include all necessary information for successful risk checks with Riskified. If you encounter issues, review your connector configuration or the extra data you’re providing.