openapi: 3.0.3 info: title: IngoPay API — Risk (RiskSession + RiskScore) description: > The IngoPay Risk API provides two endpoints used together to assess transaction risk prior to initiating a pull (debit) payment. **Typical flow:** 1. Call `POST /risk/risksession/v2` to initialize a risk session and obtain a `risk_session_token`. 2. Integrate the Sardine device fingerprinting and behavioral data collection SDK on the client side using the `risk_session_token` to associate the session. 3. Call `POST /risk/riskscore/v2` with the transaction data and `risk_session_token` to receive a risk score and a `risk_assessment_token`. 4. Pass the `risk_assessment_token` into the subsequent debit process request (`/gateway/v12/debit/process`) via `transaction.risk_assessment_token`. **Risk Score Range:** | Score Range | Description | |---|---| | 2 – 299 | Discrete scores indicating some degree of high risk / fraud | | 300 – 3000 | Continuous scores correlating to discerned risk — 3000 is best | > **Prerequisites:** Usage of the IngoPay Risk API requires integration of third-party artifacts for device fingerprinting and behavioral data collection. SDK artifacts and packages will be provided by your assigned Integration Manager. > **Account type scope:** `account_type` for RiskScore is restricted to `CA` (card) and `AC` (ACH) only. > **Conditional objects:** `transaction_ifa{}` is required when the client is configured with Identity Fraud Assessment (`ifa_enabled` flag). `transaction_open_banking{}` is conditional based on client configuration. Contact your Ingo integration manager to confirm which objects apply to your integration. version: '2' contact: name: Ingo Money Developer Support url: https://developers.ingomoney.com servers: - url: https://payapi-sandbox.ingo.money description: Sandbox - url: https://payapi.ingo.money description: Production paths: /risk/risksession/v2: post: summary: Initialize a risk session description: > Initiates a risk session with Ingo Payments. Returns a `risk_session_token` that must be passed to the Sardine device fingerprinting SDK and subsequently to the RiskScore endpoint. operationId: riskSession tags: - Risk requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RiskSessionRequest' example: request: participant_id: '12345' timestamp: '1721337425' responses: '200': description: Risk session initialized successfully content: application/json: schema: $ref: '#/components/schemas/RiskSessionResponse' example: request: participant_id: '12345' timestamp: '1721413825' response: status: '100' message: Success duration: '0.30398297309875' session: risk_session_token: 1e97dde1-f10f-4caf-8726-da6fc207ecb8 '400': description: Validation error or unrecognized participant content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: request: participant_id: '12345' timestamp: '1721413825' response: status: '800' message: Unknown Client /risk/riskscore/v2: post: summary: Submit transaction data for risk scoring description: > Submits transaction data to receive a risk score and `risk_assessment_token`. The token returned is passed into the subsequent debit process request via `transaction.risk_assessment_token`. operationId: riskScore tags: - Risk requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RiskScoreRequest' examples: standard: summary: Standard risk score request value: request: participant_id: '12345' timestamp: '1721337427' transaction: account_type: AC transaction_amount: currency_code: USD amount: '15.00' customer_account_token: f40810e6-b382-4dd5-8012-9d8518136fdc customer_id: bb79062e-938c-427e-8494-1d69fa3f2295 risk_session_token: e9751823-fed0-4982-802b-6a4bb1cdc86c phone: '5555550100' phone_verified: 'false' email: customer@example.com email_verified: 'true' dob: 01/02/2000 transaction_ifa: ssn: '6789' dob: 01/02/2000 device_id: 99ABCDEF-01234567-89ABCDE geo_location: latitude: '33.76272140863938' longitude: '-84.39188882939422' with_open_banking_plaid: summary: Risk score with Plaid open banking value: request: participant_id: '12345' timestamp: '1721337427' transaction: account_type: AC transaction_amount: currency_code: USD amount: '15.00' customer_account_token: f40810e6-b382-4dd5-8012-9d8518136fdc customer_id: bb79062e-938c-427e-8494-1d69fa3f2295 risk_session_token: e9751823-fed0-4982-802b-6a4bb1cdc86c phone: '5555550100' phone_verified: 'false' email: customer@example.com email_verified: 'true' dob: 01/02/2000 transaction_ifa: ssn: '6789' dob: 01/02/2000 device_id: 99ABCDEF-01234567-89ABCDE geo_location: latitude: '33.76272140863938' longitude: '-84.39188882939422' transaction_open_banking: open_banking_plaid: processor_token: 5964250f-18b3-419c-913c-92f4143ecfd3 account_id: 47507fce-a89c-4fd5-b0c7-5b179da4c6a1 responses: '200': description: Risk score returned successfully content: application/json: schema: $ref: '#/components/schemas/RiskScoreResponse' example: request: participant_id: '12345' timestamp: '1721337427' response: status: '100' message: Success duration: '0.074021816253662' transaction: score: '3000' risk_assessment_token: de1a802d-e6d3-4bd7-8ee9-53171952d812 fraud_guarantee: guarantee_requested: '1' transaction_guaranteed: '1' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: request: participant_id: '12345' timestamp: '1721337427' response: status: '400' message: Validation Error components: schemas: RiskSessionRequest: type: object required: - request properties: request: type: object required: - participant_id - timestamp description: General information associated with the API request. properties: participant_id: type: string maxLength: 5 description: Unique participant identifier assigned by Ingo. example: '12345' timestamp: type: string maxLength: 32 description: Unix timestamp of the request. example: '1721337425' RiskSessionResponse: type: object properties: request: type: object properties: participant_id: type: string example: '12345' timestamp: type: string example: '1721413825' response: type: object properties: status: type: string description: > Numeric code describing the status of the API request. 100 = Success. example: '100' message: type: string description: Text description associated with the status code. example: Success duration: type: string description: Time in seconds to complete the request. example: '0.30398297309875' session: type: object description: > Identifiers to be embedded in client-side web/mobile code in support of device fingerprinting and behavioral data collection. properties: risk_session_token: type: string description: > Ingo-assigned session ID (UUID). Pass this value to the Sardine device fingerprinting SDK and subsequently to the `transaction.risk_session_token` field of the RiskScore request. Default session expiry is 30 minutes. example: 1e97dde1-f10f-4caf-8726-da6fc207ecb8 RiskScoreRequest: type: object required: - request - transaction description: > `transaction_ifa{}` is required when the client is configured with Identity Fraud Assessment (`ifa_enabled` flag). `transaction_open_banking{}` is conditional based on client open banking configuration. Contact your Ingo integration manager to confirm which objects apply to your integration. properties: request: type: object required: - participant_id - timestamp description: General information associated with the API request. properties: participant_id: type: string maxLength: 5 description: Unique participant identifier assigned by Ingo. example: '12345' timestamp: type: string maxLength: 32 description: Unix timestamp of the request. example: '1721337427' transaction: type: object required: - account_type - transaction_amount - customer_account_token - customer_id - phone - phone_verified - email - email_verified - dob description: General transaction and risk assessment information. properties: account_type: type: string enum: - CA - AC minLength: 1 description: > Account type of the transaction being assessed. `CA` = Card, `AC` = ACH. Only these two account types are supported by the risk scoring flow. example: AC transaction_amount: type: object required: - currency_code - amount properties: currency_code: type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ description: 3-character ISO-4217 (alpha) currency code. example: USD amount: type: string minLength: 1 maxLength: 12 description: > Transaction amount. Must be greater than 0 with a maximum of 2 decimal places. example: '15.00' customer_account_token: type: string minLength: 1 maxLength: 50 description: > Token representing the account number and customer data as provided in the response from a previous Verify API call. example: f40810e6-b382-4dd5-8012-9d8518136fdc customer_id: type: string maxLength: 64 description: | Client provided unique identifier for the customer. example: bb79062e-938c-427e-8494-1d69fa3f2295 risk_session_token: type: string maxLength: 36 nullable: true description: > The `risk_session_token` from the Risk Session Method response. Recommended to include for accurate device fingerprinting correlation. example: e9751823-fed0-4982-802b-6a4bb1cdc86c phone: type: string maxLength: 16 description: > Customer phone number. Accepted formats: (1) 10-character all-digit string treated as US number (e.g. `4151231234`), or (2) ISO E.164 format (e.g. `+14151231234`). Accepted characters: 0-9, +. example: '4045555555' phone_verified: type: string enum: - 'true' - 'false' description: | Indicates whether the customer phone number has been verified. example: 'false' email: type: string maxLength: 150 description: Customer primary email address from profile. example: customer@example.com email_verified: type: string enum: - 'true' - 'false' description: | Indicates whether the customer email has been verified. example: 'true' dob: type: string maxLength: 10 pattern: >- ^([0-9]{2}\/[0-9]{2}\/[0-9]{4})|(([0-9]{2}\-[0-9]{2}\-[0-9]{4}))$ description: > Customer date of birth. Accepted formats: `MM/dd/yyyy` or `MM-dd-yyyy`. example: 01/02/2000 transaction_ifa: type: object description: > Additional risk information for Ingo Fraud Alert (IFA). Required when the client is configured with `ifa_enabled`. When required, `ssn` must be provided. `dob` is conditionally required when providing last-4 SSN only. required: - ssn properties: ssn: type: string minLength: 4 maxLength: 11 pattern: ^(([0-9]{4})|([0-9]{9})|([0-9]{3}\-[0-9]{2}\-[0-9]{4}))$ description: > Full SSN (9 digits, no dashes), full SSN with dashes (XXX-XX-XXXX), or last-4 digits only (4 digits). When providing last-4, `dob` is required. example: '6789' dob: type: string minLength: 10 maxLength: 10 pattern: >- ^([0-9]{2}\/[0-9]{2}\/[0-9]{4})|(([0-9]{2}\-[0-9]{2}\-[0-9]{4}))$ description: > Date of birth in MM/DD/YYYY or MM-DD-YYYY format. Required when using SSN last-4. example: 01/02/2000 device_id: type: string minLength: 1 maxLength: 100 nullable: true description: > The ID of the device, captured by the Sardine device fingerprinting SDK. example: 99ABCDEF-01234567-89ABCDE geo_location: type: object nullable: true description: Geo-location information associated with the transaction. required: - latitude - longitude properties: latitude: type: string minLength: 1 maxLength: 22 pattern: ^-?[0-9]{0,2}\.[0-9]{0,18}$ description: > Latitude of the location. Range: -90 to 90 with a precision of up to 18 decimal places. example: '33.76272140863938' longitude: type: string minLength: 1 maxLength: 23 pattern: ^-?[0-9]{0,3}\.[0-9]{0,18}$ description: > Longitude of the location. Range: -180 to 180 with a precision of up to 18 decimal places. example: '-84.39188882939422' transaction_open_banking: type: object nullable: true description: > Open banking data for risk score assessment enrichment. Conditional based on client configuration and open banking partner. Passed through to the Sardine risk scoring vendor for downstream open banking enrichment. Exactly one of `open_banking_plaid` or `open_banking_other` should be provided — not both. properties: open_banking_plaid: type: object description: > Account data from Plaid open banking. Provides Sardine with direct access to Plaid account data for enhanced risk signal enrichment. Currently live for clients configured with Plaid. required: - processor_token - account_id properties: processor_token: type: string maxLength: 36 description: | The processor token for the account as provided by Plaid. example: 5964250f-18b3-419c-913c-92f4143ecfd3 account_id: type: string maxLength: 36 description: > The unique identifier of the account for the customer as provided by Plaid. example: 47507fce-a89c-4fd5-b0c7-5b179da4c6a1 open_banking_other: x-status: planned x-status-note: > Structure defined by Sardine's open banking API contract. Not yet implemented — included to preserve Layer 1 field definitions ahead of development. Do not use in production. type: object description: > Account data from an alternative open banking provider (non-Plaid). Supports `bank_data`, `mx_data`, `stripe_data`, and `teller_data` sub-objects depending on the provider used. Exactly one sub-object should be provided. properties: bank_data: type: object description: > Generic bank account and transaction data for providers not using Plaid (e.g. Finicity, Yodlee, or other). required: - source - accounts - transactions properties: source: type: string description: > Open banking data provider name (e.g. Finicity, Yodlee, or other). example: Finicity accounts: type: array description: List of bank accounts and related information. items: type: object required: - id - account_number - routing_number - account_type - name - balance - owners properties: id: type: string description: >- ID of bank account as defined by you or the financial data provider. example: acct_001 account_number: type: string description: Bank account number. example: '123456789' routing_number: type: string description: Bank routing number. example: '011000015' account_type: type: string description: Account type — checking, saving, or other. example: checking name: type: string description: Name of the bank account. example: Wells Fargo high-interest savings account balance: type: object required: - currency_code - current - available - last_updated properties: currency_code: type: string description: >- Currency code in ISO 3-digit format (e.g. USD). example: USD current: type: string description: >- Current balance in minor currency unit (e.g. cents). example: '150000' available: type: string description: >- Available balance in minor currency unit (e.g. cents). example: '148500' last_updated: type: string description: >- Unix timestamp indicating when balance was last updated. example: '1721337427' owners: type: object required: - names - addresses - emails - phone_numbers properties: names: type: string description: > Names associated with the account. Note: string not array as many banks don't return names as an array. example: Jane Doe addresses: type: array items: type: object properties: city: type: string example: Atlanta country: type: string example: US postal_code: type: string example: '30313' region: type: string example: GA is_primary: type: string example: 'true' emails: type: array items: type: object properties: email: type: string example: jane.doe@example.com is_primary: type: string example: 'true' phone_numbers: type: array items: type: object properties: phone_number: type: string description: Phone number in ISO E.164 format. example: '+14151231234' is_primary: type: string example: 'true' transactions: type: object required: - id - account_id - amount - currency_code - status - description - posted_date - transaction_date - type - merchant_name - categories - location description: List of transactions. properties: id: type: string description: ID of the transaction. example: txn_001 account_id: type: string description: ID of the bank account. example: acct_001 amount: type: string description: Amount in minor currency unit (e.g. cents). example: '5000' currency_code: type: string description: Currency code in ISO 3-digit format (e.g. USD). example: USD status: type: string description: Transaction status — active or pending. example: active description: type: string description: >- Description of transaction given by financial institution. example: Direct deposit posted_date: type: string description: >- Date when transaction was posted in YYYY-MM-DD format. example: '2026-04-22' transaction_date: type: string description: >- Date when transaction took place in YYYY-MM-DD format. example: '2026-04-21' type: type: string description: > Type of transaction. One of: atm, cash, check, credit, debit, deposit, directDebit, directDeposit, dividend, fee, intrest, payment, pointOfSale, repeatPayment, serviceCharge, transfer, or other. example: directDeposit merchant_name: type: string description: Name of merchant. example: Ingo Money categories: type: array items: type: string description: List of categories (e.g. overdraft, bankFee). example: - directDeposit location: type: array items: type: object properties: street: type: string example: 123 Main St city: type: string example: Atlanta region: type: string example: GA postal_code: type: string example: '30313' country: type: string example: US latitude: type: string example: '33.76272140863938' longitude: type: string example: '-84.39188882939422' mx_data: type: object description: | JSON responses from MX APIs for open banking enrichment. required: - accounts_response - transactions_response - account_owners_response - list_account_numbers_response properties: accounts_response: type: object description: > JSON from MX GET /users/{user_guid}/accounts. All pages of results required. transactions_response: type: object description: > JSON from MX GET /users/{user_guid}/accounts/{account_guid}/transactions. All pages of results required. account_owners_response: type: object description: > JSON from MX GET /users/{user_guid}/members/{member_guid}/account_owners. list_account_numbers_response: type: object description: > JSON from MX GET /users/{user_guid}/members/{member_guid}/account_numbers. stripe_data: type: object description: > JSON responses from Stripe Financial Connections APIs for open banking enrichment. required: - accounts_response - account_number - routing_number - transactions_response properties: accounts_response: type: object description: > JSON from Stripe Financial Connections GET/v1/financial_connections/accounts/:id with balance and ownership refresh. Always send latest balance; ownership only required on first call. account_number: type: string description: > Bank account number. Required on first call only. Ingo links the Stripe account ID to the account number for subsequent calls. example: '123456789' routing_number: type: string description: > Bank routing number. Required on first call only. Ingo links the Stripe account ID to the routing number for subsequent calls. example: '011000015' transactions_response: type: object description: > JSON list of transactions from Stripe Financial Connections at the account ID level. All pages of results required. teller_data: type: object description: | JSON responses from Teller APIs for open banking enrichment. required: - account_number - routing_number - account_response - balance_response - transactions_response properties: account_number: type: string description: > Bank account number. Required on first call only. Ingo links the Teller account ID for subsequent calls. example: '123456789' routing_number: type: string description: | Bank routing number. Required on first call only. example: '011000015' account_response: type: object description: Teller's Account API response. balance_response: type: object description: Teller's Account Balance API response. transactions_response: type: object description: Teller's Transactions API response. RiskScoreResponse: type: object properties: request: type: object properties: participant_id: type: string example: '12345' timestamp: type: string example: '1721337427' response: type: object properties: status: type: string description: > Numeric code describing the status of the API request. 100 = Success. example: '100' message: type: string description: Text description associated with the status code. example: Success duration: type: string description: Time in seconds to complete the request. example: '0.074021816253662' transaction: type: object description: Risk assessment results. properties: score: type: string description: > Ingo risk score for the transaction. Scores 2–299 indicate high risk / fraud. Scores 300–3000 are continuous risk scores — 3000 is best. example: '3000' risk_assessment_token: type: string description: > Ingo-assigned ID for the risk assessment. Must be included in the subsequent debit Process request via `transaction.risk_assessment_token`. example: de1a802d-e6d3-4bd7-8ee9-53171952d812 fraud_guarantee: type: object description: Indicators associated with transaction fraud guarantee. properties: guarantee_requested: type: string description: > Indicates whether a guarantee against fraud was requested. 1 = requested, 0 = not requested. example: '1' transaction_guaranteed: type: string description: > Indicates whether the transaction was guaranteed against fraud. Only present when `guarantee_requested` = 1. example: '1' ErrorResponse: type: object properties: request: type: object properties: participant_id: type: string example: '12345' timestamp: type: string example: '1721337427' response: type: object properties: status: type: string example: '400' message: type: string example: Validation Error securitySchemes: HmacAuth: type: http scheme: hmac-sha512 description: >- HMAC-SHA512 signed Authorization header. See the Authentication page for the complete signing guide. security: - HmacAuth: []