Event and account inputs

You can pass information about the “event” of the transaction and the account used to initiate the transaction. The minFraud service accepts inputs for:

various transaction identifiers
the time that the transaction was initiated,
the type of transaction,
and the payment method associated with a transaction.

Transaction identifiers

The minFraud services can accept inputs that are used to identify the storefront, the transaction, and the transactor (ID and party type: agent or customer). The storefront identifier is required when you are providing the minFraud service to your own customers for fraud detection. The identifiers for transactions and transactors can be used to cross reference transaction information in your own systems, and to improve risk scoring with velocity checks.

Storefront identifier

If you use minFraud on multiple storefronts, you must associate each transaction request with a particular shop or storefront, using a unique shop ID. Passing a shop ID allows the minFraud services to track fraud patterns specific to each individual merchant or users of the minFraud services, and makes risk scoring more accurate.

If you provide the minFraud service through your account to your own customers, those customers count as distinct “storefronts,” regardless of whether your customers use the minFraud services to provide fraud detection for e-commerce transactions, account logins, or any other kind of transaction. It doesn’t matter what kind of transactions are being assessed, it only matters that the minFraud service is being used by several vendors or merchants under a single MaxMind account.

No specific format is required for the shop ID, as long as every storefront or affiliate that submits transactions to the minFraud service through your account is unique.

If you are live-testing the minFraud service, please add a test prefix in front of the shop_id input. For example if your shop ID is foo23, then it should be testfoo23 or test:foo23. If you do not have a shop ID and are testing, please set the shop_id to test. Any request with a shop_id beginning with test will still be scored but will be excluded from model training and performance metrics.

You can read the full API specification for the shop ID input on our developer portal:

/event/shop_id

Transaction identifier

You can pass a unique ID that can be used to identify the transaction in your system. If you pass a transaction ID, it will be included in the minFraud logs for your account, and will be included in minFraud Alert notifications. Learn more about minFraud Alerts.

The transaction ID is also helpful for risk scoring, and may be used to improve velocity checks when you are also passing the IP address of the transactor as an input. Learn more about velocity checks.

You can read the full API specification for the transaction ID input on our developer portal:

/event/transaction_id

Transactor identifier

You can pass a unique ID that can be used to identify the account of the customer or end user who initiated the transaction in your system. If you pass a user ID, it will be included in the minFraud logs for your account, which can be helpful when you cross reference minFraud requests with your own systems.

You can read the full API specification for the transactor ID input on our developer portal:

/account/user_id

Transactor party

If you send transactions to the minFraud service that are submitted by a party other than the end user (i.e. an agent acting on behalf of the end user), we recommend passing this input. Identifying the party will allow us to assess other inputs such as IP address and device information more effectively.

You can read the full API specification for the transactor party input on our developer portal:

/event/party/

Transaction time

You do not need to send the transaction time as a minFraud input if you submit the transactions to minFraud as they occur. It is only necessary if you are submitting past transactions.

Please note that you cannot submit times more than one year in the past. If you submit an event time more than one year in the past, the current time will be used to score the transaction, and a warning will be returned.

If you submit transactions to the minFraud service after they have been initiated, you can also pass the time that the transaction was initiated. If you do not pass the transaction time as an input, the minFraud service will assume that the transaction takes place at the time of the minFraud request.

Passing the transaction time helps the minFraud service to accurately score your transactions.

Notably, if you submit many minFraud transactions at once, after the transactions have occurred, the minFraud service will assume that all these transactions are happening at roughly the same time. This may elevate the risk score due to velocity checks. Learn more about velocity checks.

You can read the full API specification for the transaction time input on our developer portal:

/event/time

Transaction type

You can submit a transaction type as an input to the minFraud service. The minFraud service accepts the following transaction types:

Transaction type	Description
`account_creation`	The transactor is attempting to create an account in your system.
`account_login`	The transactor is attempting to login to an account in your system.
`credit_application`	The transactor is attempting to submit an application for credit.
`email_change`	The transactor is attempting to change the email address associated with their account in your system.
`fund_transfer`	The transactor is attempting to transfer funds from one account to another.
`password_reset`	The transactor is attempting to reset their password in your system.
`payout_change`	The transactor is attempting to change how they will be paid in your system. The transactor may be sending you referral traffic or complete surveys, but this transaction type can be used in any circumstance in which you pay your users, and they are attempting to change how they are paid.
`purchase`	The transactor is attempting to make a purchase.
`recurring_purchase`	The transactor is attempting to set up a recurring purchase or subscription.
`referral`	The transactor is sending you referral traffic, for example referring someone to an e-commerce site with an ad.
`survey`	The transactor is attempting to begin or complete a survey.

If you don’t know what transaction type to use, feel free to reach out to our support team for guidance based on your specific use case.

If you are passing purchase transactions to the minFraud service, you may be interested in passing additional information about your customers’ orders so that the minFraud service can track fraud patterns specific to the products and promotions of your store. Learn more about order inputs.

You can read the full API specification for the transaction type input on our developer portal:

/event/type

Payment method information

You can pass the method of payment associated with a transaction. The minFraud service accepts the following payment method types:

Payment method	Description
`card`	Payment by card, such as a credit, debit, or charge card.
`crypto`	Payment via a cryptocurrency.
`bank_debit`	A direct debit of the customer's bank account.
`bank_redirect`	The customer authorizes payment after authentication via their bank.
`bank_transfer`	The customer pushes funds directly from their bank account.
`buy_now_pay_later`	Payment via a buy now, pay later provider (e.g. Affirm, Afterpay, Klarna, etc.).
`digital_wallet`	Payment from a digital wallet linked to a card or bank account (e.g. Apple Pay, Google Pay, PayPal, etc.).
`gift_card`	Payment via a merchant sponsored gift card.
`real_time_payment`	The customer pushes funds directly from their bank account or other funding source using an intermediary to authenticate, such as a phone number or other account (e.g. Pix, PayNow, Swish, etc.).
`rewards`	Payment via rewards or loyalty program incentives.

You can read the full API specification for the payment method input on our developer portal:

/payment/method/