Managing linked accounts API Workflow

Whether created via SDK with zerohash Powered Plaid Link, or created directly through the zerohash API with Self Service Plaid Link, external accounts can always be managed by platforms through the zerohash API.

Create external account

POST /payments/external_accounts

This API call is only relevant to platforms using Self Service Plaid Link. Platforms using zerohash Powered Plaid Link should invoke the zerohash SDK to link a new bank account.

Sample request

{
    "message": {
        "participant_code": "ABC123",
        "account_nickname": "Chase",
        "plaid_processor_token": "db884a3e-7eb7-4253-92ee-04ff5efbc365"
    }
}

Sample response

{
    "message": {
        "request_id": "0f65678e-2114-469d-b505-c850d776e078",
        "participant_code": "ABC123",
        "platform_code": "XYZ789",
        "account_nickname": "Chase",
        "account_type": "checking",
        "external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
        "created_at": 1561996924964
    }
}

Close external accounts

POST /payments/external_accounts/{external_account_id}/close

This enables closing a customer bank account so it cannot be used with zerohash any longer.

Sample response

{
    "message": {
        "request_id": "0f65678e-2114-469d-b505-c850d776e078",
        "participant_code": "ABC123",
        "platform_code": "XYZ789",
        "account_nickname": "Chase",
        "account_type": "checking",
        "external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
        "status": "closed",
        "created_at": 1561996924964
    }
}

Get external accounts

External account updates can be fetched via API, and received via external account status webhooks.

Query parameters include

page: (optional) the page you would like to request – default value is 1
size: (optional) the number of records per page – default value is 200
participants: (optional) array of the participants for which to filter the result

Returns an array of all accounts that have been posted for ACH transactions.

Response parameters

Parameter	Description	Type
request_id	The unique identifier generated by zerohash associated with the request.	string
account_number	The full bank account number of the external account. Value will be empty because of the Plaid token relationship.	string
routing_number	The routing number of the bank where the external account is held. Value will be empty because of the Plaid token relationship.	string
participant_code	The code of the participant that wants to create a new ACH transaction, required.	string
platform_code	Platform unique identifier.	string
account_nickname	Name given to the account. This does not impact further zerohash functionality so it is purely for platform reference.	string
account_type	Indicates if the account is checking or savings.	string
status	Account status. Could be one of the following: `pending` `approved` `rejected` `locked` `disabled` `rejected` `closed`	string
external_account_id	The unique identifier generated by zerohash for the account. This must be stored and used to make subsequent payment requests.	string
created_at	Timestamp when the account was created.	timestamp
updated_at	Timestamp when the account was last changed.	timestamp

Sample response

{
    "message": [
        {
            "request_id": "0f68333e-2114-469d-b505-c850d776e063",
            "account_number": "",
            "routing_number": "",
            "participant_code": "ALI123",
            "platform_code": "TES123",
            "account_nickname": "test1",
            "account_type": "checking",
            "external_account_id": "0f68333e-2114-469d-b505-c850d776e063",
            "created_at": "1975-08-19T23:15:30.000Z",
            "updated_at": "1975-08-19T23:15:30.000Z"
        }
    ],
    "page": 1,
    "total_pages": 1,
    "page_size": 200,
    "count": 10
}