Linking Funding Accounts

When a user attempts to link a new External Account, it's common to validate ownership with Account Verification vendors to understand the risk associated with the external account in order to determine whether we should approve the request.

Type	Values
Monitoring Event Type	`external_account_created`
Minimum Required Fields	1. `external_entity_id` or `entity_token` 2. `external_account_id` 3. `timestamp` 4. `link_timestamp` 5. `entities[].external_entity_id`or`entities[].entity_token`
Recommended Fields	1. `routing_number` 2. `account_number`

Please reference events API for a full set of supported fields.

Account Linking Request

Since we are attempting to link an account to one or more entities, it is important to include all related entities under the entities[]. Please note that the array determines the linkage between the External Account that is being created with this event, while the top level external_entity_id denotes the entity PII that is being hydrated and sent to data services.

{
    "event_type": "external_account_created",
    "data": {
        "external_account_id": "9478cf5a-61b6-4c73-a4bf-e71d133f4cd7",
        "external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
        "account_number": "0123456",
        "routing_number": "021000021",
        "timestamp": "2024-03-28T02:16:26.983Z",
        "entities": [
            {
                "account_holder_type": "primary",
                "external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7"
            }
        ],
        "link_timestamp": "2024-03-28T02:16:26.983Z",
        "supplemental_data": {
            "bank_accounts": [
                {
                    "account_number": "0123456",
                    "routing_number": "021000021",
                    "type": "checking"
                }
            ]
        }
    }
}

Account Linking Response

With this example, there is no additional verification or user action to take after evaluating with the source workflow. Hence, we can determine the next system action by retrieving the outcome from evaluations[].summary.outcome. Depending on your setup and business logic, an denial can generate an alert that is automatically decision to be suspicious. Under this situation, journey_applications will be populated with information related to the alert.

If the request is determined to be suspicious that require additional reviews, or actions, an alert will be generated with journey_applications section populated. We recommend subscribing to the Journeys Webhooks for any asynchronous response that might dictate your business logic.

{
    "status_code": 201,
    "event_request_token": "EV-05TArFls32OimGO6XEoc",
    "_links": {
        "self": {
            "href": "/v1/events/EV-05TArFls32OimGO6XEoc"
        }
    },
    "event": {
        "event_type": "external_account_created",
        "event_status": "PROCESSED",
        "data": {
            "routing_number": "021000021",
            "is_linked_account": true,
            "link_timestamp": "2024-03-28T02:16:23.862Z",
            "entities": [
                {
                    "entity_token": "P-TfkFe6lCPkElc9Xktd3V",
                    "external_entity_id": "cf88a0a1-34d6-492d-b617-c8b43785e7b7",
                    "account_holder_type": "primary"
                }
            ],
            "account_number": "0123456",
            "external_account_id": "9478cf5a-61b6-4c73-a4bf-e71d133f4cd7",
            "account_token": "A-uiQyEF3kvfvBUZ7fXblb"
        },
        "evaluations": [
            {
                "error": null,
                "evaluation_token": "S-xQ8QXzvKKV2Pw4dQRspm",
                "workflow_token": "ch719NVZb7o7NKZRjStg7L3YqtG85JM8",
                "workflow_version_id": 2,
                "prefiltered": false,
                "summary": {
                    "result": "success",
                    "outcome": "Denied",
                    "tags": [
                        "Unverified Ownership"
                    ]
                },
                "_links": {
                    "self": {
                        "href": "/v1/evaluations/S-xQ8QXzvKKV2Pw4dQRspm"
                    }
                }
            }
        ],
        "journey_applications": []
    }
}

Unlinking Account

When the original account linking request was made, the account was already characterized as “linked” in Alloy with the provided link_timestamp. In order to maintain the correct data in Alloy, we recommend sending an update via external_account_updated with the unlink_timestamp to properly classify the External Account.

Type	Values
Monitoring Event Type	`external_account_updated`
Minimum Required Fields	1. `external_account_id` 2. `timestamp` 3. `unlink_timestamp` 4. `entities[].external_entity_id`or`entities[].entity_token`
Recommended Fields	-

Since we are not evaluating the unlink request, but simply storing the update to maintain the data integrity in Alloy. The response will return as in a confirmation of the submitted updates.

{
    "event_type": "external_account_updated",
    "event_status": "successful",
    "event_lifecycle_id": "X99-43jf-74382",
    "data": {
        "external_account_id": "9478cf5a-61b6-4c73-a4bf-e71d133f4cd7",
        "external_entity_id": "efa4cfa2-379c-4f9e-aab5-1a9a933cde15",
        "timestamp": "2024-03-28T02:32:51.351Z",
        "unlink_timestamp": "2024-03-28T02:32:51.351Z"
    },
    "supplemental_data": {}
}

{
    "status_code": 201,
    "event_request_token": "EV-OYyPwOsoiYE7V6I6ncse",
    "_links": {
        "self": {
            "href": "/v1/events/EV-OYyPwOsoiYE7V6I6ncse"
        }
    },
    "event": {
        "event_type": "external_account_updated",
        "event_status": "PROCESSED",
        "data": {
            "account_number": "0123456",
            "account_number_encrypted": "4f76aaf90607...",
            "account_number_hashed": "3badcec68d9a6...",
            "cif_number": null,
            "account_type": null,
            "product_code": null,
            "product_name": null,
            "opening_date": null,
            "maturity_date": null,
            "closing_date": null,
            "activation_date": null,
            "expiration_date": null,
            "meta": null,
            "routing_number": "021000021",
            "external_ingestion_identifier": null,
            "card_network": null,
            "account_name": null,
            "tokenization_method": null,
            "merchant_category_code": null,
            "name_on_card": null,
            "account_number_last4": null,
            "avs": null,
            "account_class": null,
            "country_code": null,
            "description": null,
            "program_name": null,
            "mcc_description": null,
            "is_linked_account": true,
            "link_timestamp": "2024-03-28T02:16:26.983Z",
            "unlink_timestamp": "2024-03-28T02:32:51.351Z",
            "entities": [
                {
                    "entity_token": "P-pHoEYGBD5I0O7weUUOoo",
                    "external_entity_id": "efa4cfa2-379c-4f9e-aab5-1a9a933cde15",
                    "account_holder_type": "primary"
                }
            ],
            "currency": "USD",
            "account_hash": null,
            "external_account_id": "9478cf5a-61b6-4c73-a4bf-e71d133f4cd7",
            "account_token": "A-uiQyEF3kvfvBUZ7fXblb"
        },
        "evaluations": [],
        "journey_applications": []
    }
}