Monitor card payments (Acquiring)

New
  • 2 minute(s) read
Prev Next

Submits a card-payment event from an acquiring flow for AML/screening. In acquiring, the merchant is your Customer (account holder) and the cardholder is the Counterparty.

Do not send card details that is protected by PCI-DSS. Use BIN, last-4 digits, expiry (YYYYMM), and holder name. This is typically sufficient for monitoring without expanding PCI DSS scope.

Minimal request example

{
   "tenantTransactionId":"c45d18a6-2384-49aa-98ab-60134a50a5d7",
   "tenantProcessingTimestamp":"2020-06-05T16:20:01.618Z",
   "initiatingParty":"FUNDS_ORIGINATOR",
   "accountHoldingParty":"FUNDS_BENEFICIARY",
   "fundsOriginator":{
      "accountId":"8713672ec1687d0dbbe462e04125b513",
      "last4Digits":"2253",
      "bankIdentifier":"542810",
      "expiry":"202812",
      "scheme":"MASTER",
      "bankCountry":"BR"
   },
   "fundsBeneficiary":{
      "accountId":"421083",
      "holder":"Limo Rental",
      "bankCountry":"DE",
      "scheme":"CARD_MERCHANTACCOUNT"
   },
   "initiatedAmount":400.00,
   "initiatedCurrency":"USD",
   "settledAmount":328.13,
   "settledCurrency":"EUR",
   "usage":"Rental #2345763",
   "paymentType":"AUTHORIZATION_CAPTURE",
   "transactionResult":"ACCEPTED",
   "channel":"ECOMMERCE",
   "masterData":{
      "accountHoldingPartyData":{
         "riskLevel":"high",
         "companyDetails":{
            "businessPurposes":[
               "7512"
            ],
            "organizationType": "FOR_PROFIT",
            "inBusinessSince": "2019-06-05"
         },
         "contactDetails":{
            "country":"DE",
            "street":"Hannes Friedrichstr. 27",
            "town":"Munich",
            "zip":"82101"
         },
		 "characteristics": {
			"customerSince": "2020-01-15",
			"expectedTicketSizeAverage": 600,
			"expectedIncomeMonthly": 80000
		 }
      }
   }
}

Try it out here

Field references

Field

Description

tenantTransactionId

Your unique transaction ID (traceability/idempotency).

tenantProcessingTimestamp

UTC timestamp when you processed the transaction (ISO-8601).

initiatingParty

Party that initiated the transaction (here: the cardholder = FUNDS_ORIGINATOR).

accountHoldingParty

Your customer in this flow (here: the merchant = FUNDS_BENEFICIARY).

fundsOriginator

Cardholder (payer) details object.

fundsBeneficiary

Merchant (payee) details object.

initiatedAmount

Amount as initiated at authorization.

initiatedCurrency

Initiated currency (ISO-4217 alpha-3).

settledAmount

Amount expected/posted at settlement (0 for declines/only-auth).

settledCurrency

Settlement currency (ISO-4217 alpha-3).

usage

Payment descriptor/reference (e.g., receipt, order number).

paymentType

Payment stage/type (e.g., AUTHORIZATION_CAPTURE, AUTHORIZATION, CAPTURE, REFUND, CHARGEBACK, REVERSAL, ACCOUNT_VERIFICATION, …).

transactionResult

Result code (e.g., ACCEPTED; for declines you may send FRAUD_SUSPICION, CARD_STOLEN, CARD_LOST, INSUFFICIENT_FUNDS, INVALID_CVV, …).

channel

Where/how it occurred (e.g., ECOMMERCE, POS, MOTO, BACKOFFICE).

masterData

Container for merchant master/customer data.

fundsOriginator (cardholder)

Field

Description

accountId

Card token/UUID or similar pseudonymous identifier.

last4Digits

Last four digits of the card PAN.

bankIdentifier

Card BIN (first 6 digits).

expiry

Card expiry in YYYYMM.

scheme

Card scheme (e.g., MASTER, VISA, AMEX, DISCOVER, MAESTRO, JCB, UNIONPAY).

bankCountry

Issuing country (ISO country code).

fundsBeneficiary (merchant)

Field

Description

accountId

Merchant ID / merchant account identifier.

holder

Merchant legal/trading name.

bankCountry

Merchant account country (typically the acquirer/processor country).

scheme

Always CARD_MERCHANTACCOUNT for merchant accounts.

masterData.accountHoldingPartyData

Field

Description

riskLevel

Merchant risk level from acquirer/processor (e.g., low/medium/high).

companyDetails

Company-level metadata about the merchant.

contactDetails

Registered contact/location info.

characteristics

Operational/expected behavior metrics.

companyDetails

Field

Description

businessPurposes

MCC(s) or equivalent merchant classification list (e.g., ["7512"]).

organizationType

Organization type (e.g., FOR_PROFIT).

inBusinessSince

Business start date (ISO-8601).

contactDetails

Field

Description

country

Merchant country (ISO code).

street

Street address.

town

City/Town.

zip

Postal/ZIP code.

characteristics

Field

Description

customerSince

Since when the merchant is your customer.

expectedTicketSizeAverage

Expected average ticket size (merchant base currency).

expectedIncomeMonthly

Expected monthly volume (merchant base currency).