Create and Update Account States APIs

post

Create account

Body

coordinate_tagsstring[]Optional

Strictly optional application-scoped tags for the account coordinates.

created_atstring · date-timeOptional

Optional Account created date. If not provided, the current date will be used.

idstring · uuidRequired

A globally unique identifier for the account request.

namestringRequired

Customer defined name of the account

product_idstring · uuidRequired

UUID of product configuration to be used

product_versionstringOptional

Version of product configuration to be used

referencestringRequired

A globally unique identifier for the account.

Responses

200

Response to /api/v2.0/account

application/json

created_atstring · date-timeRequired

The time at which the account was created in the XYB system.

currencystringRequired

The currency in which the account is denominated.

default_walletstringOptional

Default wallet code of the account

idstring · uuidRequired

A globally unique identifier for the account, generated on creation.

namestringRequired

Customer defined name of the account.

product_uuidstring · uuidRequired

Product UUID of the account

product_versionstringRequired

Product Version of the account

referencestringRequired

A globally unique identifier for the account.

statestring · enumRequired

One of the Account States.

Possible values:

state_idstring · uuidOptional

An globally unique identifier that is updated on each recorded change of the state field to match the id of the associated AccountStateChange.

updated_atstring · date-timeRequired

The time at which the account was updated in the XYB system.

post/api/v2.0/account

POST /api/v2.0/account HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 1278

{
  "attributes": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "coordinate_tags": [
    "text"
  ],
  "coordinates": {
    "acceptor": {
      "acquirer_id": "text",
      "facilitator_id": "text",
      "id": "text",
      "mcc": "text",
      "terminal_id": "text"
    },
    "banking": {
      "account_code": "text",
      "account_number": "text",
      "account_type": "text",
      "balance_account_number": "text",
      "bank_code": "text",
      "bic": "text",
      "bic_bank_code": "text",
      "bic_branch_code": "text",
      "bic_location_code": "text",
      "branch_code": "text",
      "country_code": "text",
      "currency": "text",
      "iban": "text",
      "national_id": "text",
      "owner_account_number": "text",
      "routing_code": "text"
    },
    "external": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "internal": {
      "account_id": "123e4567-e89b-12d3-a456-426614174000",
      "account_reference": "text",
      "card_id": "123e4567-e89b-12d3-a456-426614174000",
      "contact_account_id": "text",
      "currency_code": "text",
      "legacy_account_id": 1
    },
    "reference": "text"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "jurisdiction": {
    "classification": "INTERNATIONAL",
    "country_code": "text"
  },
  "name": "text",
  "owner": {
    "affiliation": "CUSTOMER",
    "aspects": [
      {
        "aspect": {},
        "identifier": "123e4567-e89b-12d3-a456-426614174000",
        "relation": "text"
      }
    ],
    "reference": "text",
    "type": "INDIVIDUAL"
  },
  "product_id": "123e4567-e89b-12d3-a456-426614174000",
  "product_version": "text",
  "reference": "text"
}

200

Response to /api/v2.0/account

{
  "account_coordinates": [
    {
      "coordinates": {
        "acceptor": {
          "acquirer_id": "text",
          "facilitator_id": "text",
          "id": "text",
          "mcc": "text",
          "terminal_id": "text"
        },
        "banking": {
          "account_code": "text",
          "account_number": "text",
          "account_type": "text",
          "balance_account_number": "text",
          "bank_code": "text",
          "bic": "text",
          "bic_bank_code": "text",
          "bic_branch_code": "text",
          "bic_location_code": "text",
          "branch_code": "text",
          "country_code": "text",
          "currency": "text",
          "iban": "text",
          "national_id": "text",
          "owner_account_number": "text",
          "routing_code": "text"
        },
        "external": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "internal": {
          "account_id": "123e4567-e89b-12d3-a456-426614174000",
          "account_reference": "text",
          "card_id": "123e4567-e89b-12d3-a456-426614174000",
          "contact_account_id": "text",
          "currency_code": "text",
          "legacy_account_id": 1
        },
        "reference": "text"
      },
      "external": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tags": [
        "text"
      ]
    }
  ],
  "attributes": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "currency": "text",
  "default_wallet": "text",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "jurisdictions": [
    {
      "classification": "INTERNATIONAL",
      "country_code": "text"
    }
  ],
  "name": "text",
  "owner": {
    "affiliation": "CUSTOMER",
    "aspects": [
      {
        "aspect": {},
        "identifier": "123e4567-e89b-12d3-a456-426614174000",
        "relation": "text"
      }
    ],
    "reference": "text",
    "type": "INDIVIDUAL"
  },
  "product_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "product_version": "text",
  "reference": "text",
  "state": "PENDING",
  "state_changes": [
    {
      "account_id": "123e4567-e89b-12d3-a456-426614174000",
      "applied_at": "2026-01-01T00:00:00.000Z",
      "external_reference": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "previous_state": "PENDING",
      "reason": "text",
      "state": "PENDING"
    }
  ],
  "state_id": "123e4567-e89b-12d3-a456-426614174000",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "wallets": [
    {
      "account_balance": "text",
      "available_balance": "text",
      "code": "text",
      "currency": "text",
      "hold_balance": "text",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

post

Update account state

Path parameters

idRefstringRequired

Body

account_uuidstring · uuidOptional

Account identifier

employee_idinteger · int64Optional

Employee id

employee_usernamestringOptional

Employee username

idstring · uuidRequired

Id of the request

reasonstringOptional

A human-readable reason for the change of account state.

statestring · enumRequired

One of OPEN , BLOCKED , CLOSED or FINALIZED .

Possible values:

Responses

200

Response to /api/v2.0/account/{idRef}/state

application/json

account_idstring · uuidOptional

A globally unique internal identifier for account

applied_atstring · date-timeRequired

The ISO-8601 time at which the state was applied.

external_referencestringOptional

A globally unique external identifier for account

idstring · uuidRequired

A globally unique identifier assigned on state change.

previous_statestring · enumOptional

Account previous state value. One of OPEN , BLOCKED , CLOSED or FINALIZED .

Possible values:

reasonstringOptional

A human-readable reason for the change of account state.

statestring · enumRequired

One of OPEN , BLOCKED , CLOSED or FINALIZED .

Possible values:

post/api/v2.0/account/{idRef}/state

POST /api/v2.0/account/{idRef}/state HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 176

{
  "account_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "employee_id": 1,
  "employee_username": "text",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "reason": "text",
  "state": "PENDING"
}

200

Response to /api/v2.0/account/{idRef}/state

{
  "account_id": "123e4567-e89b-12d3-a456-426614174000",
  "applied_at": "2026-01-01T00:00:00.000Z",
  "external_reference": "text",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "previous_state": "PENDING",
  "reason": "text",
  "state": "PENDING"
}