Account

An Account in the Paylias network represents a bank account linked to a Domain. It's used to credit net settlement proceeds based on daily transactions that are attributed to a specific Domain. By linking Accounts to Domains, Organizations have the flexibility to manage multiple Bank Accounts based on the Domains they create.

Overview

Each Account:

Links to a single Domain through an Organization
Contains encrypted bank account details
Maintains settlement information
Tracks verification status

API Resource

Property	Type	Description	Notes
`token`	string	Unique identifier for the account	Auto-generated upon creation
`partner_id`	string	Associated Domain ID	Required for all operations
`encrypted_account_number`	string	Encrypted bank account number	Not exposed in JSON
`sha256_account_number`	string	Hashed account number	Not exposed in JSON
`masked_account_number`	string	Partially hidden account number	Shows last 4 digits
`routing_number`	string	Bank routing number
`account_title`	string	Name on the account
`status`	enum	Current account status	See Status Types
`type`	enum	Type of bank account	See Account Types
`institution`	object	Bank details	Includes name, address, contact
`created_at`	timestamp	Creation timestamp	Unix timestamp in seconds
`updated_at`	timestamp	Last update timestamp	Unix timestamp in seconds
`deleted_at`	timestamp	Deletion timestamp	Only present if deleted

Status Types

Status	Value	Description
`AS_None`	0	No status assigned
`AS_Unverified`	1	Account pending verification
`AS_Verified`	2	Account verified
`AS_Deleted`	3	Account deleted

Account Types

Type	Value	Description
`AT_None`	0	No type assigned
`AT_Checkings`	1	Checking account
`AT_Savings`	2	Savings account

Authentication

All Account-related operations require both:

JWT token in the Authorization header
Domain token in the X-Partner-ID header

API Endpoints

Create Account

Creates a new bank account for a Domain.

Required Parameters

Parameter	Type	Required	Description
`account_title`	string	Yes	Name on the account
`account_number`	string	Yes	Bank account number
`routing_number`	string	Yes	Bank routing number
`type`	string	Yes	Account type (AT_Checkings/AT_Savings)

`POST /api/v1/csp/account`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/account' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwt_token>' \
--data '{
    "account_title": "Safepay Inc.",
    "account_number": "123456789",
    "routing_number": "011000015",
    "type": "AT_Checkings"
}'

Example Response

{
    "ok": true,
    "data": {
        "token": "acct_cvg1hk420or769prtisg",
        "partner_id": "part_ct23b6420or249k5boag",
        "masked_account_number": "******7890",
        "routing_number": "011000015",
        "account_title": "Safepay Inc.",
        "status": 1,
        "type": 1,
        "created_at": {
            "seconds": 1742739664
        },
        "updated_at": {
            "seconds": 1742739664
        }
    }
}

Possible Error Codes

Error Code	Description
`error.bad_request`	Invalid or missing required parameters
`error.resource_conflict`	Account with similar details already exists
`error.unauthorized_access`	Invalid or missing authentication
`500`, `502`, `503`, `504`	Server-side errors

Find Account

Retrieves details of a specific bank account.

Path Parameters

Parameter	Type	Required	Description
`accountToken`	string	Yes	Account token to retrieve

`GET /api/v1/csp/account/{accountToken}`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/account/acct_cvg1hk420or769prtisg' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "token": "acct_cvg1hk420or769prtisg",
        "partner_id": "part_ct23b6420or249k5boag",
        "masked_account_number": "******7890",
        "routing_number": "011000015",
        "account_title": "Safepay Inc.",
        "status": 1,
        "type": 1,
        "institution": {
            "name": "FEDERAL RESERVE BANK",
            "routing_number": "011000015",
            "phone_number": "8773722457",
            "address": {
                "address": "1000 PEACHTREE ST N.E.",
                "city": "ATLANTA",
                "state": "GA",
                "postal_code": "30309"
            }
        },
        "created_at": {
            "seconds": 1742739664
        },
        "updated_at": {
            "seconds": 1742739664
        }
    }
}

Delete Account

Marks an account as deleted in the system.

`DELETE /api/v1/csp/account/{accountToken}`

curl --location --request DELETE 'https://production.oysterapi.net/csp/api/v1/csp/account/acct_cjm6g2vsemvs0bglqlu0' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "message": "success"
    }
}

Decrypt Account

Retrieves the decrypted account number for a specific account.

`GET /api/v1/csp/account/{accountToken}/decrypt`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/account/acct_cvg1k9s20or769prtit0/decrypt' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "account_number": "1234567890"
    }
}

Search Accounts

Retrieves a list of accounts based on specified filters.

Query Parameters

Parameter	Type	Required	Description
`routing_numbers`	string[]	No	Filter by routing numbers
`account_titles`	string[]	No	Filter by account titles
`status`	enum	No	Filter by account status
`limit`	integer	No	Results per page
`page`	integer	No	Page number

`GET /api/v1/csp/account`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/account?account_titles=Safepay%20Inc.&routing_numbers=011000015&status=AS_UNVERIFIED&limit=3&page=1' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "count": 3,
        "accounts": [
            {
                "token": "acct_ctf930420orabtojo3r0",
                "partner_id": "part_ct23b6420or249k5boag",
                "masked_account_number": "*****6789",
                "routing_number": "011000015",
                "account_title": "Safepay Inc.",
                "status": 1,
                "type": 1,
                "institution": {
                    "name": "FEDERAL RESERVE BANK",
                    "routing_number": "011000015",
                    "phone_number": "8773722457",
                    "address": {
                        "address": "1000 PEACHTREE ST N.E.",
                        "city": "ATLANTA",
                        "state": "GA",
                        "postal_code": "30309"
                    }
                },
                "created_at": {
                    "seconds": 1734250881
                },
                "updated_at": {
                    "seconds": 1734250881
                }
            },
            ...
        ]
    }
}

Common Error Codes

Error Code	Description
`error.resource_not_found`	Account not found
`error.unauthorized_access`	Invalid or missing authentication
`500`, `502`, `503`, `504`	Server-side errors