Update Virtual Accounts | Citi Docs Demo

curl -X PATCH https://tts.sandbox.apib2b.citi.com/citiconnect/sb/receivablesservices/v2/virtualaccounts \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "action": "UPDATE",
  "header_account": {
    "account": "01010202030",
    "branch_code": "930"
  },
  "virtual_account": {
    "account": "0123456789",
    "entity": {
      "country_of_operation": "CA",
      "last_name": "INC",
      "id": "EN_45678901234567890",
      "website": "www.ddee.com",
      "store_name": "ABC",
      "business_purpose": "Trade",
      "acronym": "Buss",
      "type": "C",
      "org_prvt_identification": {
        "type": "TAX_ID",
        "id": "1234567890",
        "country_of_issuance": "US"
      },
      "address": {
        "street_name": "3210 Abcd st",
        "building_number": "123",
        "postal_code": "L5B 111",
        "town_name": "North York",
        "country_sub_division": "Ontario",
        "country": "CA"
      }
    },
    "beneficial_owner": [
      {
        "date_of_birth": "2001-05-01",
        "first_name": "White",
        "last_name": "James",
        "address": {
          "street_name": "3210 Abcd st",
          "building_number": "123",
          "postal_code": "L5B 111",
          "town_name": "North York",
          "country_sub_division": "Ontario",
          "country": "CA"
        }
      },
      {
        "date_of_birth": "2000-05-01",
        "first_name": "White",
        "last_name": "Mark",
        "address": {
          "street_name": "3210 Abcd st",
          "building_number": "123",
          "postal_code": "L5B 111",
          "town_name": "North York",
          "country_sub_division": "Ontario",
          "country": "CA"
        }
      }
    ]
  }
}'

The virtual account update (using the update service endpoint) allows you to modify virtual account information.

Use the PATCH verb for Update action
- The API support XML and JSON formats.
- The update functionality is identified based on the request payload (action).
- You specify values for input parameters in the body of your XML/JSON document.
- You encrypt the payload, place it in your request, and send it with your application.

The virtual account update endpoint allows you to modify the virtual account details and status.
Below are the sub-object combinations allowed under the virtual_account object for updates:

- VALID combination 1: For virtual_account.entity.type = C (Company), update the entity details under a virtual_account using the virtual_account.entity as well as virtual_account.beneficial_owner
- VALID combination 2: For virtual_account.entity.type = S (Sole Trader), update the entity details under a virtual_account using the virtual_account.entity
- VALID combination 3: Apply the posting restrictions on virtual_account use only the virtual_account.credit_debit_preferences object

Below are the INVALID object combinations for the PATCH endpoint:
- INVALID combination 1: Only with virtual_account.entity for virtual_account.entity.type = C (Company)
- INVALID combination 2: Only with virtual_account.beneficial_owner
- INVALID combination 3: With all 3 objects, virtual_account.entity, beneficial_owner, credit_debit_preferences
- INVALID combination 4: With 2 objects, virtual_account.entity, credit_debit_preferences
- INVALID combination 5: With 2 objects, virtual_account.beneficial_owner, credit_debit_preferences

<font size=‘2’>Content-Type: Supports application/xml and application/json.
Authorization: The OAuth Token prefixed with Bearer and space in between.

Allowed characters: A-Z, a-z, 0-9, Space
Allowed punctuation marks: ’ ( ) * - , . / : ; _ & $ # @ [ ]

Authentication

AuthorizationBearer

All CitiConnect APIs use the oAuth2 authentication scheme, which requires a bearer token to authenticate your API call. The Token URL includes the version of authentication used by this API. See the Citi Authentication API reference for information on requesting a token.

Query parameters

client_idstringRequired<=40 characters

Unique reference shared during CitiConnect API onboarding (client_id used during OAuth token generation).

Request

Describes the virtual account creation endpoint request body parameters.

actionenumRequired

Action is a request type.
- Choose the action value as ‘UPDATE’, if you want to update the virtual account details that were stored earlier.

Allowed values:

header_accountobjectOptional

virtual_accountobjectOptional

Response headers

DeprecationstringOptional

The date when this API was stopped or will be stopped by the system owner. ISO 8601-1:2019 format.

SunsetstringOptional

The date when this API will no longer be Supported by the system owner. The API will no longer be responsive and all REQUESTS will generate an error. ISO 8601-1:2019 format.

LinkstringOptional

Latest working URL that can be used for the same purpose.

RateLimit-LimitstringOptional

The rate limit ceiling for that given request measured in a 24 hour cycle.

RateLimit-RemainingstringOptional

The number of requests left in a 15 minute window.

RateLimit-ResetstringOptional

The remaining window before the rate limit resets. ISO 8601-1:2019.

Response

Accepted

request_idstringOptional1-40 characters

Auto-generated unique identification assigned for the request.

statusstringOptional1-20 characters

Status of the request.
Possible statuses are
SUCCESS
REJECTED
PENDING

messagestringOptional1-400 characters

Detailed response for the particular request.

actionstringOptional

Action of the given request.
- ”RESERVATION”
- ”ACTIVATION”.

branch_codestringOptional3-4 characters

Citi's bank code associated with given a header account number.

error_detailslist of objectsOptional

accountlist of objectsOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

405

Method Not Allowed Error

409

Conflict Error

415

Unsupported Media Type Error

429

Too Many Requests Error

500

Internal Server Error