Risk

Kronor Risk links payments that share a customer identifier (email, phone number, national identification number, card PAR, …) into one shopper profile, which you can inspect on the Risk Profile page in the merchant portal.

Purchases you process outside Kronor, for instance directly with Klarna, Avarda or Adyen, are invisible to Risk until you deliver them. This section describes how to deliver them and what to expect afterwards.

Delivering external transactions

Deliver externally processed transactions from your backend with the addExternalTransactions mutation, authenticated with your merchant API token (see Authentication).

Loading GraphiQL...

Input Parameters

Parameter	Description
merchantId	Your Kronor merchant id.
transactions	The transactions to deliver. At most 1000 per call.

Transaction Parameters

Parameter	Description
provider	The external payment provider that processed the transaction. One of the values defined at https://kronor-io.github.io/kronor/#definition-ExternalTransactionProvider.
orderReference	Your reference for the order, e.g. the order id or the provider’s order reference. Together with provider it identifies the transaction in later replays. Max length: 100.
transactionAt	When the transaction was processed at the provider, as an ISO8601 timestamp. Must not be in the future.
amount	The transaction amount in minor units, so 100,56 kr is 10056.
currency	The currency of the amount, e.g. SEK.
country	The country (market) the order was placed in, e.g. SE. Also gives the context for nationalIdentificationNumber and for nationally formatted phone numbers.
emails	The customer email addresses on the order. Send every one you have, at most 10. Max length: 100 each.
phoneNumbers	The customer phone numbers on the order, preferably in E.164 format (+46701234567). Nationally formatted numbers are interpreted in country. Send every one you have, at most 10. Max length: 100 each.
nationalIdentificationNumber	The customer’s national identification number (personnummer, fødselsnummer, CPR, henkilötunnus), interpreted together with country. Max length: 100.
dateOfBirth	The customer’s date of birth as an ISO8601 date, e.g. 1990-05-24.
cardPaymentAccountReference	The card’s Payment Account Reference (PAR) for card transactions, e.g. Adyen’s additionalData.paymentAccountReference. Max length: 100.
cardAlias	The provider’s identifier for the card, e.g. Adyen’s additionalData.alias. Max length: 100.
customerReference	Your own identifier for the customer, e.g. the value you send as Adyen’s shopperReference. Use the same value as in PaymentSessionAdditionalData.customerReference for your Kronor payments. Max length: 100.

At least one of emails, phoneNumbers, nationalIdentificationNumber, cardPaymentAccountReference, cardAlias and customerReference must be provided on each transaction.

Response Fields

Field	Description
insertedCount	The number of transactions that were stored as new records.
duplicateCount	The number of transactions that matched a record already delivered with the same provider and orderReference. They create no new record but top up the existing one, see Replays.

When to send

Send a transaction once the provider has approved it, i.e. it is authorised or captured. Do not send declined or abandoned attempts: there is no status field, and a delivered transaction counts as a completed purchase.

Send either right after each purchase completes or in periodic batches. Both work; sending sooner lets Risk react sooner.

Historical backfills are welcome. transactionAt keeps the original time, so the order and dates of the purchases are preserved. Split a backfill into calls of at most 1000 transactions.

What to send

Send every customer identifier you have. A transaction can only be linked to your Kronor payments through identifiers they share, so the more you send the better the match:

• all emails and phone numbers on the order,

• nationalIdentificationNumber together with country,

• cardPaymentAccountReference and cardAlias for card payments,

• your customerReference.

Send one entry per order, keyed by provider and orderReference.

Replays

Deliveries are idempotent per provider and orderReference within your merchant. Replaying a transaction is safe: a replay never creates a second record and never overwrites a stored value, but it adds emails and phone numbers not seen before and fills identifier fields that were still empty.

Replay an order whenever you learn more about it, for instance a phone number captured at delivery. Replayed transactions are reported in duplicateCount whether or not the replay added anything.

Validation

A call is validated as a whole. If any transaction is invalid, nothing is stored and the response carries an error per invalid field, named by its path in the input, e.g. transactions[3].emails[0]. Fix the entry and resend the batch.

Entries in one call that share provider and orderReference are merged before storing, so batching does not change what gets stored.

Processing

Clustering runs in the background on a schedule, so a delivered transaction appears on the Risk Profile some time after the call, not immediately. Transactions are processed in delivery order; a large backfill is worked through over several runs.

Once processed, the transaction shows up on the Risk Profile of the shopper it was linked to: the identifiers it carried get an external-transaction count, and the transaction itself is listed with its provider, reference, amount and date.