Transaction Screening API vs Sanctions & PEP API: Which Fits Your Payment Workflow?

Checklynx offers two API models that can support screening in a payment workflow, but they assign ownership differently.

Use POST /transactions when the payment and its parties should become a durable Checklynx transaction-screening run. Each request creates a generated run ID, keeps the supplied parties within one transaction context, supports later retrieval and may link actionable results to a Checklynx case.

Use POST /check/sanctions_pep when your application should remain the transaction and workflow system of record. The endpoint screens one target directly against sanctions, PEP and wanted-list data. Your application remains responsible for retaining its system-of-record copy of the payment context, party relationships, correlation, evidence and downstream review workflow.

This is not simply a choice between “more” and “less” screening. It is a choice about which system owns the transaction-screening execution and evidence model.

The decision in one view

The Transaction Screening API keeps several supplied parties inside one Checklynx execution:

client payment event → POST /transactions → Checklynx run ID → party results and run evidence → optional case → customer decision

The direct Sanctions & PEP API leaves that structure in the client platform:

client payment event → choose party → POST /check/sanctions_pep → store response under client transaction and party → repeat as needed → client review → customer decision

Both models can feed a payment workflow. The key question is whether Checklynx should hold a native transaction run or act as a direct screening layer inside an architecture that already owns the complete transaction and review record.

If the underlying question is instead how transaction screening differs from behavioural monitoring, see transaction screening vs transaction monitoring. This guide does not reopen that distinction.

What POST /transactions creates

POST /transactions is transaction-first. The request contains a transaction object and a screening object. The transaction requires a client-supplied transaction_reference_id and parties; the screening object requires a screening_profile_id.

The transaction may also include its type, occurrence time, amount and currency. Current documented transaction types include bank payment, card payment, remittance, cash deposit, cash withdrawal, internal transfer and other. These fields add payment context to the execution; they do not decide the legal treatment of the payment.

The response contains a Checklynx-generated id, transaction summary, execution status, hit_status, hit_count, screening_summary, creation time, per-party results and a case_id that may be null. The current contract defines run status as completed or failed and hit status as hit or clear. A hit status reflects actionable, unsuppressed results under the configured screening workflow; it is not a final legal conclusion.

The exact schemas can change, so implementations should use the current Checklynx developer guide and OpenAPI definition as their contract.

Several parties stay attached to one transaction run

The transaction request supports one to 100 parties. Current documented roles are:

debtor, creditor, customer, counterparty, ultimate_debtor, ultimate_creditor, debtor_agent, creditor_agent, intermediary_agent and merchant.

Each party needs a role and at least one usable screening input: a name, identity document or supported payment instrument. An optional external_customer_id can associate the party with an existing Checklynx customer using the client's stable identifier. If it does not resolve, Checklynx still screens the supplied party data and leaves the party unlinked for that run.

The native party model is useful where originator, beneficiary, intermediary, merchant or other policy-relevant roles need to remain connected to the same execution. The role list describes what the API supports—not which parties an organisation is legally required to screen. Scope must follow applicable requirements and the customer's policy.

The screening profile belongs to the run

The request requires screening.screening_profile_id. This identifies the Checklynx AML screening profile applied to the transaction run. It gives the transaction workflow a configured screening context rather than requiring every transaction request to reproduce all screening controls.

The inspected request model for POST /check/sanctions_pep does not contain screening_profile_id. It instead exposes direct controls such as fuzziness, exclusions and filters. This is a practical difference: one model invokes a configured profile for a transaction run; the other submits a direct target check with request-level screening parameters.

Bank accounts and wallet addresses are handled differently

The current transaction-party model supports bank_account and wallet_address payment instruments.

For a documented bank_account instrument, the request requires the account number and BIC. Checklynx uses the BIC for sanctions-identity screening. The account number is retained as supporting run evidence but is not currently parsed, checksum-validated or itself screened. The safe description is therefore “BIC screened, account number stored as evidence”—not blanket “IBAN screening”.

For a wallet_address instrument, the wallet address is used for sanctions-identity screening. A network is optional.

Both supported instrument types can carry an optional client external_instrument_id. It can be returned with the run, but the current contract says it is not included in case-hit records or webhook payloads. It should not be the integration's only cross-system case correlation key.

Payment-instrument checks depend on sanctions-identity screening being enabled in the selected screening profile.

Business IDs, run IDs and case IDs solve different problems

The transaction workflow uses three identifiers that should not be conflated:

Every POST /transactions creates a new screening run, even when the same transaction_reference_id is submitted again. That behaviour supports legitimate rescreening: several executions can belong to one business payment while each retains its own result and timestamp. It also means the client must prevent or reconcile accidental duplicate submissions.

Store the returned run id alongside the client transaction record. GET /transactions/{id} retrieves that exact execution. GET /transactions/references/{transaction_reference_id} returns an aggregate for runs sharing the business reference, and GET /transactions lists transaction-reference aggregates with documented filtering and pagination. A reference lookup should not be treated as though it identifies one unique run.

This distinction matters during uncertain failures. If a caller does not know whether a request succeeded, blindly replaying it may create another run. The client needs an application-level submission state and reconciliation strategy; the current public contract does not promise exactly-once processing.

What POST /check/sanctions_pep does differently

The direct endpoint screens one target against sanctions, PEP and wanted-list data. It explicitly does not create a customer or case record, and its public response contract does not expose a transaction object, client transaction reference or persistent transaction-run ID equivalent to the /transactions run id.

The request provides exactly one of:

• search_term for a name-oriented check, such as a person, alias, company, vessel or aircraft name; or
• search_identity for an identifier-oriented check, such as a passport, tax ID, national ID, other document number, vessel IMO number, wallet value or bank-account value supported by the current contract.

The current OpenAPI documents fuzziness values "0", "1" and "2", with "1" as the default. It also documents filters and exclusions including source type, group type, nationality, birth year and gender. The response is organised around results and match_profiles.

This should be described as a direct screening model without a persisted Checklynx transaction object, not as a guarantee of literally zero backend storage or operational logging. “Stateless” is common market language, but the public contract does not establish that absolute claim for Checklynx.

Screening several payment parties with the direct endpoint

If a client wants to screen several parties, it calls the endpoint separately for each target in scope and reconstructs the payment relationship in its own system. A useful client-side mapping is:

client transaction ID → party and role → request payload and parameters → response and match profiles → timestamp → review status → workflow outcome

Returned result or match identifiers should not be described as transaction-run identifiers. The client should create its own correlation record before calling the API and update it atomically as results, review and payment state change.

This model can fit an established payment platform that already has a case system, event ledger and evidence store. It gives that platform control over which parties are checked, when calls occur, how responses are combined and where review happens. That flexibility also transfers more responsibility to the client: role relationships, duplicate protection, persistence, retrieval and investigation history do not come from a native Checklynx transaction run under this endpoint.

The current public documentation does not document an idempotency mechanism for POST /check/sanctions_pep, a standalone-check completion webhook or automatic case creation. Those are precise documentation boundaries—not claims that undocumented internal capabilities are impossible.

Architecture comparison

Neither model removes the need for the client to retain its business transaction state and final decision. The difference is how much of the screening execution, party context and review linkage is represented natively in Checklynx.

Evidence and case-management implications

With /transactions, retain at minimum the client business reference, Checklynx run id, relevant request and correlation data, payment-system state and subsequent business decision. The Checklynx run keeps the supplied transaction-screening execution and party results together. Where configured and applicable, case_id can connect actionable results to a review workflow.

With /check/sanctions_pep, the client needs a reconstructable record for every direct check: its transaction identifier, party and role, timestamp, supplied screening input, request parameters and filters, response and match profiles, downstream status, reviewer, rationale and outcome. That is an architecture recommendation based on the absence of a native transaction/case structure in this endpoint, not a claim that Checklynx prescribes a particular customer database schema.

Potential matches require evaluation. They should enter the organisation's applicable review and escalation process rather than being treated as automatic proof that the party is sanctioned. See how to document a sanctions alert investigation for the investigation record, and Audit Trail & Evidence and Case Management for Checklynx workflow context.

Authentication, webhooks and duplicate protection

The current OpenAPI uses the x-api-key header. Keep API keys in server-side systems and out of browser or mobile client code. Exact authentication and payload examples should come from the current developer documentation, not from older marketing-page examples that may have drifted from the contract.

For applicable transaction case events, Checklynx documents transaction_screening.case.opened. It is an event for a newly opened case arising from actionable transaction-screening hits—not a callback for every transaction request.

Webhook receivers should:

1. read the raw request bytes;
2. calculate base64(HMAC-SHA256(signing_secret, raw_request_body));
3. compare the result with X-Webhook-Signature before parsing or reserialising JSON;
4. reject signature mismatches; and
5. deduplicate retried deliveries using the documented event_id.

Webhook deduplication and transaction-request duplication are different controls:

Do not describe webhook delivery as exactly once. The documented deduplication requirement means receivers should expect possible retries.

Errors, retries and operational recovery

The public contract documents 429 as “Too many requests” and instructs callers to wait and retry with backoff. It does not establish one universal quota, fixed delay, latency target or SLA for this article to promise.

Separate failures by stage. A transport timeout does not prove that a server-side run was never created. A completed API response does not prove that a downstream payment update or case assignment succeeded. Record submission state, run ID where returned, response status, downstream handoff and reconciliation outcome independently.

Avoid copying full names, identity documents, account details or wallet addresses into general application logs. Prefer the minimum correlation IDs, status and diagnostic metadata needed for operation, with sensitive evidence retained only in appropriately controlled systems.

Which API fits your payment architecture?

Prefer the Transaction Screening API when:

• several parties need to remain attached to one payment context;
• one durable Checklynx execution record is useful;
• analysts need transaction and party context inside Checklynx;
• the same business payment may be screened more than once and each run must remain individually retrievable;
• lookup by Checklynx run ID or client business reference matters;
• actionable results should be able to link to a Checklynx case; or
• screening execution and review evidence should be more tightly coupled in the Checklynx workflow.

Prefer the direct Sanctions & PEP API when:

• the client platform is deliberately the transaction system of record;
• it already owns its case, workflow and evidence architecture;
• the unit of work is one direct target check;
• the client wants to orchestrate separately which payment parties to screen;
• it can persist transaction, role, request, response and reviewer relationships itself; or
• Checklynx should act as a screening service inside a broader client-owned application.

Neither is universally better. The right model is the one whose ownership boundaries match the systems that operations, engineering and compliance can reliably support. See AML integration workflows, the Checklynx transaction screening workflow and the real-time sanctions and PEP screening API for the wider product context.

Where batch fits—and where it does not

POST /check/sanctions_pep/batch accepts multiple independent screening targets and supports request_item_id for item-level correlation. It does not turn those checks into a native transaction with a transaction reference, related parties, transaction run ID, transaction-reference retrieval or transaction case/webhook relationship.

CSV screening similarly fits defined bulk populations. It is not a third transaction-ownership architecture and should not be confused with behavioural transaction monitoring. Use the API vs batch sanctions screening guide when the decision is event-driven screening versus a population exercise.

Compliance scope and payment decisions remain with the customer

An API's supported party roles do not define which parties must be screened. Applicable sanctions regimes, the organisation's exposure and its documented policy determine scope. U.S. banking guidance, for example, frames OFAC controls around an institution's risk profile, products, customers, transactions, geographies and available technology; it should not be universalised into one rule for every industry or country.

A screening hit is a signal for review, not automatically a confirmed match or mandatory payment disposition. A clear response is also not universal legal permission: sanctions restrictions can involve ownership, control, licences, exemptions and facts outside a simple listed-name comparison.

Checklynx provides screening and workflow infrastructure. The customer defines which transactions and parties are in scope, supplies relevant data, evaluates potential matches and remains responsible for payment handling and legal or reporting decisions. For broader control design, see the sanctions screening practical guide.

Payment screening implementation checklist

Frequently asked questions

Is the Sanctions & PEP API stateless?

The safe architectural statement is that POST /check/sanctions_pep does not create a customer, case or documented Checklynx transaction-run object. The client owns the transaction and workflow record. The public contract does not establish that Checklynx performs literally zero backend storage or operational logging, so an absolute “stateless” guarantee would go beyond the documentation.

Can transaction_reference_id prevent duplicate transaction runs?

No. It is a non-unique client business reference and not an idempotency key. Every POST /transactions creates a new run. Store the returned run id and implement client-side duplicate prevention and reconciliation.

Does every transaction hit create a Checklynx case?

No. case_id may be null. The current contract supports synchronous case creation or linkage for applicable actionable results, but the integration should not promise that every hit automatically produces a case.

Does the transaction endpoint screen the bank account number?

For the currently documented bank_account instrument, the BIC is used for sanctions-identity screening. The account number is retained as supporting evidence and is not currently parsed, checksum-validated or itself screened.

Is there a webhook for every direct Sanctions & PEP API response?

The current public event catalogue does not document a standalone completion webhook for POST /check/sanctions_pep. The documented transaction event concerns a newly opened transaction-screening case, not every screening call.

Does either API decide whether to release or stop a payment?

No. The customer uses screening results within its policy, review and legal framework. A potential match requires evaluation, and the correct transaction action depends on the applicable regime and facts.

Choose the API model that matches your system of record

Use Checklynx Transaction Screening when transaction parties, screening results and review evidence should remain connected in a durable screening run. Use the Sanctions & PEP API when your own platform retains the transaction workflow and Checklynx provides the direct screening response.

The choice should be explicit before implementation: it determines identifiers, persistence, multi-party orchestration, case handoff, duplicate protection and the evidence each system must retain.