openapi: 3.2.0
info:
  title: PayerID Management Services Payer ID Reservation API
  description: CitiConnectAPI service enable straight-through processing (STP) for Payer ID management functionality where client ERP system can invoke API request for Payer ID management functionalities.
  version: 1.0.3
  contact:
    name: CitiConnect API Team
servers:
- url: https://tts.apib2b.citi.com/citiconnect/prod
  description: production gateway url
- url: https://tts.sandbox.apib2b.citi.com/citiconnect/sb
  description: sandbox url
security:
- oAuth2:
  - /authenticationservices/v1
tags:
- name: PayerIdReservation
  description: PayerID Reservations API has an ability to reserve PayerID.
paths:
  /receivablesservices/v1/payerids/reservations:
    post:
      summary: Reserve Payer IDs
      description: PayerID Reservations API has an ability to reserve PayerID with Reservations services supported in JSON format.
      operationId: payerIdReservation
      tags:
      - PayerIdReservation
      servers:
      - url: https://tts.apib2b.citi.com/citiconnect/prod
        description: production gateway url
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/IdempotencyId'
      requestBody:
        description: This endpoint describes the process of reserving Payer_ID numbers. Uniqueness of currencies should be maintained for different `client_accounts`. Since multiple currencies are supported for a single unique client account number, client account should be unique. In the given example, client_account 10823201 and 10823200, can have `instruction_currencies` as GBP, or any other currency respectively. However, `client_account` 10823201 and 10823200 cannot be assigned to same `instruction_currencies` as GBP.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payer-ID-Reservation-Request'
            examples:
              PayerIdReservationExample:
                $ref: '#/components/examples/Payer-ID-Reservation-Request-Example'
        required: true
      responses:
        '202':
          $ref: '#/components/responses/OKResponseForReservation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/IdempotencyDuplication'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeOrRequestedResourceNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oAuth2:
        - /authenticationservices/v1
      callbacks:
        asynchronous-reservation-push-notification:
          $ref: '#/components/callbacks/PayerIdReservationPushNotification'
components:
  examples:
    Method-Not-Allowed-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: Method not supported
          action: Please use valid HTTP verb.
          code: CC00001
    Requested-Resource-Not-Found:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: Resource that you are searching was not found.
          action: Please use valid resource details.
          code: CC00006
    Idempotency-Duplication:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: Idempotency-Id provided is currently being used in another request.
          action: please do not repeat the same request again.
          code: VC00016
    OK-Response-Reservation-Success-Example:
      value:
        status_code: PIPND
        status_description: Payer IDs reservation request is in progress.
        request_id: 9801bac6a4c74662ae78136bd4eba422
    Unsupported-Media-Type-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: Media type not supported
          action: Please use valid content-type in the header.
          code: CC00002
    Payer-ID-Reservation-Request-Example:
      value:
        country_code: GB
        number_of_payerids_required: 2
        accounts:
        - client_account: '10823201'
          branch_code: '600'
          instruction_currencies:
          - GBP
        - client_account: '10823200'
          branch_code: '600'
          instruction_currencies:
          - ANY
    Internal-Server-Error-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: Unable to serve your request at this moment
          action: Please refer the prescribed action in error for a resolution of this error.
          code: CC00004
    Bad-Request-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: country_code is mandatory and it cannot be empty
          action: please provide valid value for property country_code.
          code: VC00002
    Payer-ID-Reservation-Push-Notification-Example:
      value:
        country_code: GB
        accounts:
        - client_account: '10823201'
          branch_code: '600'
          instruction_currencies:
          - GBP
        - client_account: '10823200'
          branch_code: '600'
          instruction_currencies:
          - ANY
        request_id: eec8de9d-f6c5-4af2-89c2-f9b3erX7
        status_code: PIAC
        status_description: Payer ID Reservation Successful
        payerid_number:
        - GB87CITI18500870909334
        - GB60CITI18500870909335
    Payer-ID-Reservation-Error-Push-Notification-Example:
      value:
        country_code: GB
        request_id: eec8de9d-f6c5-4af2-89c2-f9b3erX7
        accounts:
        - client_account: '123456'
          branch_code: '600'
          instruction_currencies:
          - UPN
          - LHO
          - XLL
        status_code: PIRJ
        status_description: Payer ID Reservation Rejected
        errors:
        - error_code: PI1004
          error_description: Client account 123456 is not onboarded.
    Unauthorized-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: User not authorized for this functionality
          action: Please use valid credentials to access this functionality.
          code: CC00007
  schemas:
    Payer-ID-Error-Detail:
      type: object
      title: Payer-ID-Error-Detail
      properties:
        issue:
          type: string
          title: issue
          description: More information about the issue.
          maxLength: 150
        action:
          type: string
          title: action
          description: The corrective action to be taken to resolve the issue.
          maxLength: 150
        code:
          type: string
          title: code
          description: Error category that provides more details on error types.
          maxLength: 10
    Payer-ID-Reservation-Push-Notification:
      required:
      - country_code
      type: object
      title: Payer-ID-Reservation-Push-Notification
      properties:
        country_code:
          type: string
          title: country_code
          maxLength: 2
          description: The country code used for the payer ID.
        accounts:
          type: array
          title: accounts
          maximum: 30
          description: The account parameter under which the client account, branch code, or instruction currency will be displayed. Instruction currency cannot be same for different client account numbers in a single request.
          items:
            $ref: '#/components/schemas/Payer-ID-Account'
        request_id:
          type: string
          title: request_id
          maxLength: 32
          description: Auto-generated unique identification assigned for the incoming request.
        status_code:
          type: string
          title: status_code
          maxLength: 10
          description: Status code sent in asynchronous push notification responses. Status code will have values such as `PIRJ`, `PIAC`, `PIPND`
        status_description:
          type: string
          title: status_description
          maxLength: 500
          description: 'Detailed status description sent in asynchronous push notification responses. Status description will have the following values: <br>`PIRJ` - Payer Id Creation Rejected<br>`PIAC` - Payer ID Creation Successful<br>`PIPND - Payer Id Activation In Progress`'
        payerid_number:
          type: array
          title: payerid_number
          maxItems: 1000000
          description: List of reserved payer IDs.
          items:
            $ref: '#/components/schemas/Payer-Id'
        errors:
          type: array
          title: errors
          items:
            $ref: '#/components/schemas/Errors'
    Instruction-Currency:
      type: string
      title: Instruction-Currency
      pattern: ^[A-Z]{3}$
      description: The 3-character ISO currency code. It is a payment currency, for example, 'EUR' or 'GBP'.
    Payer-ID-Errors:
      type: object
      title: Payer-ID-Errors
      properties:
        ref_id:
          type: string
          title: ref_id
          description: Unique identifier which can be used to track your request.
        error_details:
          type: array
          title: error_details
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Payer-ID-Error-Detail'
    Payer-Id:
      type: string
      title: Payer-Id
      minLength: 1
      maxLength: 35
    Payer-ID-Reservation-Response:
      required:
      - status_code
      - status_description
      - request_id
      type: object
      title: Payer-ID-Reservation-Response
      properties:
        request_id:
          type: string
          title: request_id
          maxLength: 32
          description: Auto-generated unique identification assigned for the incoming request.
        status_code:
          type: string
          title: status_code
          maxLength: 10
          description: 'Status code sent in asynchronous push notification responses. Status codes are: <br>`PIRJ`<br>`PIAC`<br>`PIPND`'
        status_description:
          type: string
          title: status_description
          maxLength: 500
          description: 'Detailed status description sent in asynchronous push notification responses. Status description will have the following values: <br> `PIRJ`- Payer ID creation rejected<br>`PIAC`- Payer ID creation successful<br>`PIPND`- Payer ID activation in progress'
    Errors:
      required:
      - error_code
      - error_description
      type: object
      title: Errors
      properties:
        error_code:
          title: error_code
          minLength: 1
          maxLength: 35
          type: string
          description: 'Specifies the error code for the rejected activation request sent in an asynchronous response. Error codes will have the following values: `V005`<br>`V002`<br>`PI1001`<br>`RR10`<br>`PI1003`<br>`PI1004`<br>`PI1005`<br>`PI1006`<br>`PI1007`<br>`AC04`<br>`AC06`<br>`MD07`<br>`BLKD`<br>`REST`'
        error_description:
          title: error_description
          minLength: 1
          maxLength: 500
          type: string
          description: Specifies the error description of the rejected activation request sent in an asynchronous response. Error description for each each error codes will have following descriptions as <br> `V005 - Invalid combination of input parameters {Country code}{Branch code}`<br>`V002 - Please provide valid value for {payerid_number} or Please provide valid value for Action`<br>`PI1001 - PYID is already active`<br>`RR10 - Invalid Character Set`<br>`PI1002 - PYID Activation request is already in progress`<br>`PI1003 - Payer ID XXXXXXXXX is being processed`<br>`PI1004 - Client account has not been onboarded`<br>`PI1005 - Payer ID XXXXXXXXX could not be activated. Please contact your Client Executive`<br>`PI1006 - Payer ID XXXXXXXXX is under compliance review and has been temporarily deactivated. Please contact your Client Executive for further assistance`<br>`PI1007 - Payer ID XXXXXXXXX could not be activated. Please contact your Client Executive`<br>`AC04 - ClosedAccountNumber`<br>`AC06 - BlockedAccount`<br>`MD07 - EndCustomerDeceased`<br>`BLKD - Blocked`<br>`REST - Restricted`
    Payer-ID-Account:
      required:
      - client_account
      - branch_code
      - instruction_currencies
      type: object
      title: Payer-ID-Account
      properties:
        client_account:
          type: string
          title: client_account
          minLength: 1
          maxLength: 35
          description: The client's account.
        branch_code:
          type: string
          title: branch_code
          minLength: 3
          maxLength: 4
          description: Citi's Internal branch code.
        instruction_currencies:
          type: array
          title: instruction_currencies
          uniqueItems: true
          minItems: 1
          maxItems: 30
          description: The 3-character ISO currency code. It is a payment currency, for example, 'EUR' or 'GBP'.
          items:
            $ref: '#/components/schemas/Instruction-Currency'
    Payer-ID-Reservation-Request:
      required:
      - country_code
      - number_of_payerids_required
      - accounts
      type: object
      title: Payer-ID-Reservation-Request
      properties:
        country_code:
          type: string
          title: country_code
          pattern: ^[A-Z]{2}$
          description: 'The ISO country code specifying which country the account is held with. For example, if we receive a request for Germany, then the county code is ''DE'', for France, the country code is ''FR''. The list of allowed country codes are: <br>''DE'' - Germany<br> ''FR'' - France<br> ''GB'' - Great Britain<br>''IE'' - Ireland<br>''NL'' - Netherlands<br>''US'' - United States<br>''CA'' - Canada<br> ''HK'' - Hong Kong<br> ''SG'' - Singapore<br>''AU'' - Australia<br>''NZ'' - New Zealand<br>''LU'' - Luxembourg'
        number_of_payerids_required:
          type: integer
          title: number_of_payerids_required
          minimum: 1
          maximum: 50000
          description: Specifies number of payer IDs to be reserved in a single reservation request.
        accounts:
          type: array
          title: accounts
          minItems: 1
          maxItems: 30
          description: Identification of account parameter under which client account, branch code, or instruction currency is to be displayed. The instruction currency cannot be same for different client account numbers in a single request.
          items:
            $ref: '#/components/schemas/Payer-ID-Account'
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payer-ID-Errors'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/Unauthorized-Example'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payer-ID-Errors'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/Bad-Request-Example'
    UnsupportedMediaTypeOrRequestedResourceNotFound:
      description: Unsupported Media Type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payer-ID-Errors'
          examples:
            UnsupportedMediaTypeExample:
              $ref: '#/components/examples/Unsupported-Media-Type-Example'
            RequestedResourceNotFound:
              $ref: '#/components/examples/Requested-Resource-Not-Found'
    MethodNotAllowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payer-ID-Errors'
          examples:
            MethodNotAllowedExample:
              $ref: '#/components/examples/Method-Not-Allowed-Example'
    OKResponseForReservation:
      description: Accepted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payer-ID-Reservation-Response'
          examples:
            OKResponseExampleForReservation:
              $ref: '#/components/examples/OK-Response-Reservation-Success-Example'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payer-ID-Errors'
          examples:
            InternalServerErrorExample:
              $ref: '#/components/examples/Internal-Server-Error-Example'
    IdempotencyDuplication:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payer-ID-Errors'
          examples:
            IdempotencyDuplicationExample:
              $ref: '#/components/examples/Idempotency-Duplication'
  callbacks:
    PayerIdReservationPushNotification:
      /asynchronous-reservation-push-notification:
        post:
          summary: Asynchronous Reservation Push Notification
          description: This callback describes the asynchronous push notifications schema definition and examples for Payer ID Reservation.
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Payer-ID-Reservation-Push-Notification'
                examples:
                  OKReservationNotificationExample:
                    $ref: '#/components/examples/Payer-ID-Reservation-Push-Notification-Example'
                  NotOKReservationNotificationExample:
                    $ref: '#/components/examples/Payer-ID-Reservation-Error-Push-Notification-Example'
          responses:
            '202':
              description: Accepted
              content:
                application/json:
                  schema:
                    type: object
  parameters:
    IdempotencyId:
      name: Idempotency-Id
      in: header
      required: true
      schema:
        type: string
        maxLength: 128
        example: a44cbb60-6de4-4edb-9a7a-123414bba3bb
      description: Your unique identification for a POST request for CitiConnect to perform an idempotency check. The same `client_id` is to be maintained by the requestor. You can retry the request within 48 hours.
    ClientId:
      name: client_id
      in: query
      description: This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for OAuth token generation.
      required: true
      schema:
        type: string
        example: 898918181818181aczta
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: authenticationservices/v3/oauth/token
          scopes:
            /authenticationservices/v1: Grant read-only access to receivable services