ThreatMetrix

When using UI Components v2 with UPL payment methods (Unzer Invoice, Direct Debit Secured, or Installment), ThreatMetrix fraud prevention is automatically handled by the component.

How It Works

1. ThreatMetrix scripts are automatically loaded when a UPL payment form is rendered
2. A unique ThreatMetrix session ID is generated internally
3. The threatMetrixId is returned in the submit() response
4. You extract the threatMetrixId from the response and include it in your authorize/charge API request

Implementation

Step 1: Initialize the UI Component

No special configuration is needed. The component handles ThreatMetrix automatically for UPL payment methods:

HTML

HTML

Copy

<unzer-payment
    id="unzer-payment"
    publicKey="s-pub-xyz"
    locale="de-DE">
    <unzer-paylater-invoice></unzer-paylater-invoice>
</unzer-payment>
<unzer-checkout id='unzer-checkout'>
    <button type="submit" id="yourPaymentButtonId">Pay</button>
</unzer-checkout>

Step 2: Handle the Submit Response

When the user submits the payment form, extract the threatMetrixId from the response:

JavaScript

JavaScript

Copy

Promise.all([
  customElements.whenDefined("unzer-payment"),
  customElements.whenDefined("unzer-paylater-invoice"),
]).then(() => {
  const unzerCheckout = document.getElementById("unzer-checkout");
  
  unzerCheckout.onPaymentSubmit = (response) => {
    if (response.submitResponse && response.submitResponse.success) {
      const paymentId = response.submitResponse.data.id;
      const { threatMetrixId } = response; // Extract ThreatMetrix ID
      
      // Send both to your server
      console.log("Payment ID:", paymentId);
      console.log("ThreatMetrix ID:", threatMetrixId);
      // Example: "myshop_01h0vw3x1234abcd5678efgh"
      
      // Send to your server for authorization
      sendToServer({ paymentId, threatMetrixId });
    } else {
      // Handle resource creation error
    }
  };
});

Step 3: Pass to Your Authorize/Charge Request

Include the threatMetrixId in your server-side authorize or charge request:

cURL

cURL JSON

Copy

curl https://api.unzer.com/v1/payments/authorize \
-X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <Base64 encoded privateKey>' \
-d '{
  "amount": "100.00",
  "currency": "EUR",
  "typeId": "s-pyl-...",
  "customerId": "s-cst-...",
  "additionalTransactionData": {
    "riskData": {
      "threatMetrixId": "myshop_01h0vw3x1234abcd5678efgh",
      "customerGroup": "TOP",
      "confirmedAmount": "2569",
      "confirmedOrders": "14"
    }
  }
}'

JSON

cURL JSON

Copy

{
  "amount": "100.00",
  "currency": "EUR",
  "typeId": "s-pyl-...",
  "customerId": "s-cst-...",
  "additionalTransactionData": {
    "riskData": {
      "threatMetrixId": "myshop_01h0vw3x1234abcd5678efgh",
      "customerGroup": "TOP",
      "confirmedAmount": "2569",
      "confirmedOrders": "14"
    }
  }
}

Supported Payment Methods

ThreatMetrix is automatically enabled for:

• Unzer Invoice (UPL)
• Direct Debit Secured
• Unzer Installment (Paylater)

For other payment methods, threatMetrixId will be undefined in the response.

ThreatMetrix ID Format

The automatically generated ID follows this pattern:

• Format: {merchantName}_{uuidv7}
• Example: "myshop_01h0vw3x1234abcd5678efgh"
• Characters: Only letters, digits, hyphens, and underscores
• Special characters from merchant name are automatically removed

Automatic Cleanup
The UI Component automatically cleans up ThreatMetrix scripts when the payment is submitted or the component is destroyed. No manual cleanup is required.

Troubleshooting

Q: I’m not receiving threatMetrixId in the response

Check the following:

• Verify you’re using a UPL payment method (Invoice, Direct Debit Secured, or Installment)
• Ensure a valid public key is provided to the <unzer-payment> component
• Check the browser console for ThreatMetrix loading errors or API errors

Q: Can I customize the ThreatMetrix session ID?

No, in UI Components v2, the ID is automatically generated to ensure uniqueness and compliance. For custom IDs, use the legacy implementation with direct API integration.

Q: Is ThreatMetrix required for UPL payment methods?

While not strictly required, we strongly recommend including the threatMetrixId to increase the acceptance rate of your UPL payment methods. It helps our risk assessment system make better decisions.