Validation

A Validation in the Paylias network represents a verification strategy to confirm account ownership. The primary method uses microdeposits - small random deposits that must be verified by the account owner, similar to a 4-digit OTP verification.

Overview

Each Validation:

Links to a specific Account
Uses a defined strategy (currently microdeposits)
Tracks verification status
Processes through a specified vendor

API Resource

Property	Type	Description	Notes
`token`	string	Unique identifier for the validation	Auto-generated upon creation
`account_id`	string	ID of account being validated	Links to Account record
`status`	enum	Current validation status	See Status Types
`strategy`	enum	Validation method used	See Strategy Types
`vendor`	enum	Service provider for validation	See Vendor Types
`created_at`	timestamp	Creation timestamp	Unix timestamp in seconds
`updated_at`	timestamp	Last update timestamp	Unix timestamp in seconds

Status Types

Status	Value	Description
`VStatus_None`	0	No status assigned
`VStatus_Init`	1	Validation initialized
`VStatus_Complete`	2	Validation completed

Strategy Types

Strategy	Value	Description
`VStrat_None`	0	No strategy assigned
`VStrat_Microdeposit`	1	Microdeposit verification

Vendor Types

Vendor	Value	Description
`VVendor_None`	0	No vendor assigned
`VVendor_Paylias`	1	Paylias internal vendor

Authentication

All Validation-related operations require both:

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

API Endpoints

Create Validation

Initiates a new validation process for an account.

Required Parameters

Parameter	Type	Required	Description
`strategy`	string	Yes	Validation strategy to use
`vendor`	string	Yes	Vendor to process validation

`POST /api/v1/csp/validate/{accountToken}`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/validate/acct_cjm6g2vsemvs0bglqlu0' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwt_token>' \
--data '{
    "strategy": "VStrat_Microdeposit",
    "vendor": "VVendor_Paylias"
}'

Example Response

{
    "ok": true,
    "data": {
        "validation": {
            "token": "val_cvgo7uc20or769prtiu0",
            "account_id": "acct_ctf930420orabtojo3r0",
            "status": 1,
            "vendor": 1,
            "created_at": {
                "seconds": 1742832633
            },
            "updated_at": {
                "seconds": 1742832633
            }
        },
        "vendor_response": "success"
    }
}

Complete Validation

Verifies the microdeposit amounts to complete the validation process.

Required Parameters

Parameter	Type	Required	Description
`amounts`	array	Yes	Array of deposit amounts to verify
`amounts[].currency`	string	Yes	Currency of deposit
`amounts[].amount`	integer	Yes	Amount of deposit in lowest denomination

`POST /api/v1/csp/validate/{accountToken}/{validationToken}`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/validate/acct_cjm6g2vsemvs0bglqlu0/val_ck3at8nsemvnplblqdtg' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwt_token>' \
--data '{
    "amounts": [
        {
            "currency": "USD",
            "amount": 17
        },
        {
            "currency": "USD",
            "amount": 4
        }
    ]
}'

Example Response

{
    "ok": true,
    "data": {
        "validation": {
            "token": "val_cvgo7uc20or769prtiu0",
            "account_id": "acct_ctf930420orabtojo3r0",
            "status": 2,
            "vendor": 1,
            "created_at": {
                "seconds": 1742832633
            },
            "updated_at": {
                "seconds": 1742832788
            }
        },
        "vendor_response": "success"
    }
}

Find Validation

Retrieves details of a specific validation.

Path Parameters

Parameter	Type	Required	Description
`accountToken`	string	Yes	Account token
`validationToken`	string	Yes	Validation token

`GET /api/v1/csp/validate/{accountToken}/{validationToken}`

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

Example Response

{
    "ok": true,
    "data": {
        "token": "val_cvgo7uc20or769prtiu0",
        "account_id": "acct_ctf930420orabtojo3r0",
        "status": 2,
        "vendor": 1,
        "created_at": {
            "seconds": 1742832633
        },
        "updated_at": {
            "seconds": 1742832788
        }
    }
}

Common Error Codes

Error Code	Description
`error.bad_request`	Invalid or missing required parameters
`error.resource_conflict`	Validation already exists
`error.resource_not_found`	Validation or Account not found
`error.unauthorized_access`	Invalid or missing authentication
`500`, `502`, `503`, `504`	Server-side errors