Finance transactions

Use Sumsub API to send and receive finance transaction monitoring data.

A finance transaction is any applicant's attempt to send or receive money via your service. Finance transaction checks are intended to answer the following questions:

  • Where is money coming from?
  • Is that a legitimate originator or source?
  • Where is the money going?
  • Is that a legit beneficiary?
  • Are there suspicious patterns in the overall transaction process?

Create finance transaction

Use the type of transaction below to document all the finance activities of your users including deposits, withdrawals, transfers, purchases of goods and services, and conversion of funds.

The required fields may vary depending on the country and the payment method but basically include the following:

{
    "txnId": "631f268442d8290001e1eee9_newTxn",  //Unique transaction identifier within your system
    "applicant": {
      "externalUserId": "1234567abc",  //Unique ID number for the applicant in your system
      "FullName": "John Smith",  //Applicant’s name. If you don't have an applicant, you can still put some human-readable info here
      "type": "individual",  //Participant entity type: company or individual. Set to an individual by default
      "address": {
        "country": "DEU",  //Remitter country code per ISO 3166
        "street": "Chauseestr. 60",
        "postCode": "101115",
        "town": "Berlin"  //A textual string with a city/town name
      },
      "device": {
        "fingerprint": "141245124fgsdg",  //Unique device fingerprint used to track device usage
        "ipInfo": {
          "ip": "87.141.63.130"  //Applicant device IP used to detect account takeover if too many IP addresses are used 
        }
      },
      "institutionInfo": {
        "code": "DEUTDEDB101",  //Applicant’s bank BIC or SWIFT code or another identifier for the financial institution
        "name": "Deutsche Bank"  
      },
      "paymentMethod": {
        "type": "card",  //A string and you can utilize your own naming for payment methods. Can be utilized in Rules
        "accountId": "a3v09sc2ac65sxska12",  //Credit card hash number OR the actual account number/IBAN/DC Hash, crypto wallet address, etc.  Preferably unique for your organization. 
        "issuingCountry": "DEU"  //Payment method issuing country code per ISO 3166
      }
    },
    "counterparty": {
      "externalUserId": "1234567abc",  //Unique identifier of the beneficiary or the remitter of the transaction. In case of deposit/withdrawal applicant and counterparty should have the same ExternalUserID 
      "fullName": "John Smith",
      "type": "individual",
      "institutionInfo": {
        "code": "CRESCHZZXXX",  //Counterparty’s bank BIC or SWIFT code
        "name": "Credit Swiss (Schweiz)"
      }
    },
    "info": {
      "direction": "out",  //'in' for a deposit, 'out' for withdrawal
      "amount": 101.42,
      "currencyCode": "GBP",  //Payment currency code per ISO 4217. We will automatically convert GBP or other currency into your default currency like USD (there is also an amountInDefaultCurrency optional field for precise calculations)
      "paymentDetails": "Birthday Present"  //The text added by the user within the payment can be utilized to identify fraudulent/risky guidelines during funds transfer
    },
    "props": {
      "customProperty": "Custom value that can be used in rules"  //Custom value to be used in rules. For example, you can apply limits and customer types from your internal segmentation, etc. This field can be textual and numerical 
    }
  }

Check out response

The response contains the info from the created transaction (all attributes) above with additional objects that contain the current review and scoring info of the requested transaction:

{
    "id": "65a918f03c901d2b3c893479",
    "applicantId": "65a906b659df1414adf1107b",
    "scope": "events",
    "externalUserId": "dash-2385a803-1cce-46f6-a9f8-675957c0da32",
    "clientId": "clientId",
    "data": {
      "txnId": "631f268442d8290001e1eee9_newTxn",
      "txnDate": "2024-01-18 12:26:24+0000",
      "applicant": {
        "externalUserId": "dash-2385a803-1cce-46f6-a9f8-675957c0da32",
        "fullName": "response",
        "address": {
          "street": "Chauseestr. 60",
          "town": "Berlin",
          "postCode": "101115",
          "country": "DEU",
          "formattedAddress": "Chauseestr. 60, Berlin, Germany, 101115"
        },
        "type": "individual",
        "paymentMethod": {
          "type": "card",
          "accountId": "a3v09sc2ac65sxska12",
          "issuingCountry": "DEU"
        },
        "paymentMethodExtractedInfo": {
          "type": "bankAccount"
        },
        "device": {
          "ipInfo": {
            "ip": "87.141.63.130",
            "countryCode2": "DE",
            "countryCode3": "DEU",
            "city": "Berlin",
            "zipCode": "13355",
            "lat": 52.5448,
            "lon": 13.3862,
            "asn": 3320,
            "asnOrg": "Deutsche Telekom AG",
            "riskyAsn": false
          },
          "fingerprint": "141245124fgsdg"
        },
        "institutionInfo": {
          "code": "DEUTDEDB101",
          "name": "Deutsche Bank"
        },
        "institutionExtractedInfo": {
          "address": {
            "country": "DEU"
          }
        }
      },
      "counterparty": {
        "externalUserId": "1234567abc",
        "fullName": "John Smith",
        "type": "individual",
        "paymentMethodExtractedInfo": {
          "type": "bankAccount"
        },
        "institutionInfo": {
          "code": "CRESCHZZXXX",
          "name": "Credit Swiss (Schweiz)"
        },
        "institutionExtractedInfo": {
          "address": {
            "country": "CHE"
          }
        }
      },
      "type": "finance",
      "info": {
        "direction": "out",
        "amount": 101.42,
        "currencyCode": "GBP",
        "currencyType": "fiat",
        "amountInDefaultCurrency": 118.10890661337676,
        "defaultCurrencyCode": "EUR",
        "paymentDetails": "Birthday Present"
      },
      "sourceKey": "123",
      "props": {
        "customProperty": {  //Custom value that can be used in rules
          "Limit": "10000"  //Custom value to be used in rules. For example, you can apply limits on customer types from your internal segmentation, etc. This field can be textual and/or numerical. As an example - a limit on outgoing transactions can be added within Props
        }
      },
      "score": 0,  //Transaction risk score
      "review": {
        "reviewId": "PwAeq",
        "attemptId": "jgGvn",
        "attemptCnt": 0,
        "elapsedSincePendingMs": 281,
        "elapsedSinceQueuedMs": 281,
        "createDate": "2024-01-18 12:26:24+0000",
        "reviewResult": {
          "reviewAnswer": "GREEN"  //GREEN (approved), RED (rejected)
        },
        "reviewStatus": "completed"
      },
      "createdAt": "2024-01-18 12:26:24+0000",
      "scoringResult": {
        "score": 0,
        "dryScore": 0,  //The risk score of the transaction including the matched rules in the “dry run” mode
        "matchedRules": [],
        "unmatchedRules": [],
        "action": "score",
        "ruleCnt": 2,  //Matched rules total
        "dryRunRuleCnt": 0,  //Matched rules in the “dry run” mode total
        "tagScores": []
      },
      "typedTags": [],
      "txnInactive": false
    }
  }