Payment Screening Troubleshooting & FAQs

Common troubleshooting scenarios

The following table summarizes frequent errors encountered in Payment Screening, why they happen, and how to resolve them.

How to debug

• Trace by eval_id: Use Case Management in the RiskOS™ Dashboard to follow the evaluation through each enrichment and decision step.
• Inspect enrichment results: Review the data_enrichments array in the response. Each entry shows which entity or instrument was screened, the list matches, and their scores.
• Check matchFields: The matchFields object shows which input fields contributed to a match (for example, name, DOB, address). Use this to understand why a match occurred.
• Review case_history: The case_history array shows events like case creation, status changes, and tags applied. This helps trace the decision flow.
• Validate inputs: Ensure entity names are plausible (not placeholders like "TEST" or "N/A"), dates are properly formatted, and enum values match supported options exactly.
• Compare Sandbox vs. Production: The Sandbox returns mocked responses and may not include all lists or features. If behavior differs between environments, confirm you are testing with production-equivalent data.

Fallback strategies

• Correct and retry: Fix malformed inputs (names, dates, entity types) and resubmit with a new unique id.
• Strengthen identifiers: If matches are too broad or too few, add additional data points — DOB, national ID, address, or BIC/SWIFT — to improve match precision.
• Adjust thresholds: If too many payments are routed to REVIEW, adjust the match score and entity correlation thresholds in your workflow conditions to better align with your risk tolerance.
• Route to manual review: Use tags and review_queues to route inconclusive results to compliance analysts for human investigation.

Escalation path

1. Reproduce the issue: Attempt to reproduce in Sandbox or staging with a known-good payload to isolate configuration issues from data issues.
2. Capture relevant identifiers: Collect the following before contacting support:
   • eval_id
   • Full request payload (with sensitive data redacted)
   • referenceId values from the response
   • Timestamps
   • Expected vs. actual decision
3. Open a support ticket: Email support@socure.com with these details, the workflow name, and any relevant logs or screenshots.
4. Live assistance: The Support team triages and, if needed, escalates to specialists for a live troubleshooting session.

Known issues

• Sandbox coverage limitations: Sandbox responses use mocked data and do not reflect the full range of Production watchlist coverage. Always validate critical flows in Production.
• Duplicate ID behavior: Reusing the id field causes RiskOS™ to treat the request as a re-run, which can produce unexpected results. Always generate a unique id per request.
• Risk-policy conditions: Granular risk-policy conditions (routing by jurisdiction, product, or amount) are coming in June 2026. Until then, configure routing through standard workflow conditions.

📘

Note:

Use Case Management in the RiskOS™ Dashboard to view the raw request/response for an evaluation for debugging or validation.

FAQs

Foundational concepts

What is Payment Screening in RiskOS™?

Payment Screening is a pre-configured use-case workflow in RiskOS™ that screens every entity and identifier in a payment transaction against global sanctions lists, PEP data, and Adverse Media in real time.

It evaluates source and destination parties — individuals, businesses, bank accounts, and crypto addresses — and returns an ACCEPT, REVIEW, or REJECT decision with detailed match data.

How does Payment Screening differ from Transaction Monitoring?

Payment Screening evaluates individual transactions at the point of execution to catch sanctioned parties or high-risk entities before a payment is processed.

Transaction Monitoring analyzes patterns of behavior over time — velocity, anomalies, structuring — to detect suspicious activity across a portfolio.

Payment Screening doesn't replace Transaction Monitoring. They serve complementary purposes.

Which industries and use cases does Payment Screening support?

Payment Screening is available globally and supports a wide range of industries, including:

• Payment Service Providers
• Banking
• Fintech and Crypto
• Marketplaces and Gig platforms
• E-Commerce
• Insurance
• Government

Common use cases include cross-border payments, domestic wire screening, account funding validation, and crypto on-ramp/off-ramp screening.

API and integration

What API endpoint does Payment Screening use?

Payment Screening uses the standard RiskOS™ evaluation endpoint:

• Sandbox: https://riskos.sandbox.socure.com/api/evaluation
• Production: https://riskos.socure.com/api/evaluation

Set the workflow field to the value assigned to your Payment Screening workflow in the RiskOS™ Dashboard.

What authentication is required?

Include a Bearer token in the Authorization header. Obtain your API key from RiskOS™ Dashboard > Developer Workbench > API Keys.

You can optionally include an X-API-Version header to pin a specific API version (for example, 2025-01-01.orion).

What is the minimum required payload for a Payment Screening request?

Every request requires four top-level fields:

• id — a unique identifier for the evaluation (must not be reused)
• timestamp — a valid RFC 3339 timestamp
• workflow — your environment-specific workflow identifier
• data — the transaction data, including at least a source or destination entity with a plausible full name

What entity types does Payment Screening support?

Payment Screening supports two entity types:

• INDIVIDUAL — requires individual sub-object with name fields (given name and surname)
• BUSINESS — requires business sub-object with entity name

Both source and destination entities can be either type, independently.

What instrument types are supported?

Two instrument types are supported:

• BANK_ACCOUNT — requires an account sub-object with fields like IBAN, BIC/SWIFT, and account number
• CRYPTO_ADDRESS — requires a crypto_address sub-object with the wallet address, currency, and network

Supported crypto currencies include BTC, ETH, USDT, XMR, ZEC, XRP, LTC, SOL, and others. Supported networks include bitcoin, ethereum, tron, solana, polygon, and others.

Can I screen both the sender and the beneficiary in a single API call?

Yes. A single API call screens all entities and instruments provided in the request — source individual or business, destination individual or business, and their associated bank accounts or crypto addresses. RiskOS™ returns enrichment results for each screened component.

Decisions and results

What decisions can Payment Screening return?

Payment Screening returns one of three decisions:

• ACCEPT — no material matches found; allow the payment to proceed
• REVIEW — potential matches found; hold the payment and route to manual review
• REJECT — high-confidence matches found; block the payment

What data is included in the response?

The response includes:

• Decision and routing — the final decision, tags, and review queue assignment
• Enrichment results — match details for each screened entity and instrument, including list name, match score, entity correlation score, matched fields, and source URLs
• Case history — events such as case creation and status changes
• Lifecycle metadata — eval_status, timestamps, and execution context

What are matchScore and entityCorrelationScore?

These scores indicate the strength of a watchlist match:

• matchScore — measures how closely a specific field (for example, name) matches a list entry
• entityCorrelationScore — measures overall confidence that the screened entity corresponds to a specific list entry, combining multiple matching signals

Higher scores indicate stronger matches. Your workflow conditions and thresholds determine how these scores influence the final decision.

What does eval_status mean, and should I use it for business decisions?

eval_status tracks the lifecycle state of an evaluation:

• evaluation_completed — processing is finished
• evaluation_paused — evaluation is paused (for example, awaiting input)
• evaluation_in_progress — evaluation is still running

Use eval_status for monitoring only. Base business decisions on the decision field.

Performance and configuration

What is the expected response time for Payment Screening?

Payment Screening provides real-time sanctions screening with response times under 200 ms.

Can I customize the screening workflow?

Yes. The Payment Screening workflow in RiskOS™ is fully configurable. You can:

• Enable or disable specific enrichments
• Configure allow/deny lists for email addresses, phone numbers, IP addresses, and devices
• Set conditions for tagging, monitoring, and routing
• Adjust match score and entity correlation thresholds

What are the workflow components in a Payment Screening workflow?

A Payment Screening workflow consists of four components:

• Input — collects transaction data from the API request
• Enrichment — screens entities and instruments against watchlists
• Condition — applies tags and monitoring logic based on results
• Decision — emits the final ACCEPT, REVIEW, or REJECT outcome

Can I test Payment Screening in Sandbox before going to Production?

Yes. Use the Sandbox endpoint (``) with your Sandbox API key. Sandbox responses are mocked and may not reflect the full range of Production list coverage.

Updated 24 days ago.