Update, Add, or Remove Merchant and Beneficiary Details Associated with a Specific Payer ID | Citi Docs Demo

curl -X PUT "https://tts.sit.apib2b.citi.com/citiconnect/sit5/receivablesservices/v1/payerids?client_id=898918181818181aczta&payerid-number=payerid-number" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "country_code": "HK",
  "party_type_details": "C",
  "merchant": {
    "address": "XXX, 123",
    "zipcode": "1234573",
    "city": "ABCDEFHG",
    "state": "XXX",
    "country_code": "GB",
    "name_1": "XXX",
    "name_2": "YYY",
    "date": "2022-02-28",
    "tax_identifier": "12345678",
    "website": "http://www.abc.com"
  },
  "beneficiary": [
    {
      "address": "SAN STREET 878",
      "zipcode": "545432678",
      "city": "Paris",
      "state": "PPP",
      "country_code": "GB",
      "beneficiary_id": "123456",
      "last_name": "YYY",
      "middle_name": "ZZZ",
      "first_name": "HHH",
      "dob": "2023-02-28"
    },
    {
      "address": "SAN STREET 123",
      "zipcode": "4657898",
      "city": "London",
      "state": "XXX",
      "country_code": "GB",
      "beneficiary_id": "888888",
      "last_name": "YYY",
      "middle_name": "ZZZ",
      "first_name": "AAA",
      "dob": "2022-02-28",
      "tax_identifier": "12345676"
    },
    {
      "address": "SAN STREET 666",
      "zipcode": "09090909",
      "city": "Barbados",
      "state": "NJNJ",
      "country_code": "HK",
      "last_name": "BBB",
      "middle_name": "JJJ",
      "first_name": "VVV",
      "dob": "2020-02-28",
      "tax_identifier": "12345676"
    }
  ]
}'

This endpoint can update, add, or remove assignee details of a particular Payer ID.

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

payerid-numberstringRequired1-35 characters

Unique number assigned for payers and beneficiaries to identify incoming payments.

client_idstringRequired

This is your unique identifier shared during your CitiConnect API onboarding. This is the same client_id used for OAuth token generation.

Request

Describes the payer ID assignee details for update.

country_codestringRequiredformat: "^[A-Z]{2}$"

The ISO country code specifying the country where the account is held. For example, if we receive a request for Germany then the county code is DE. For France, it is FR. The list of allowed country codes are:
DE - Germany
FR - France
GB - Great Britain
IE - Ireland
NL - Netherlands
US - United States
CA - Canada
HK - Hong Kong
SG - Singapore
AU - Australia

party_type_detailsenumRequired

Account party type details. Allowed account part type values are:

S - sole trader, which is an enterprise owned or run by a single person.
C - a company that is owned by an organization or business entity

Allowed values:

merchantobjectOptional

beneficiarylist of objectsOptional

Response

Accepted

status_codestring<=20 characters

Status of the request sent as synchronous response to client. Status code will have value as PIPND.

status_descriptionstring<=500 characters

Incoming request acknowledgement message, example as Payer ID Update assignee request is in-progress.

request_idstring<=32 characters

Auto-generated unique identifier assigned for the incoming request.

Errors

400

Bad Request Error

401

Unauthorized Error

405

Method Not Allowed Error

415

Unsupported Media Type Error

500

Internal Server Error