swagger: '2.0'
info:
  title: Payment Services
  description: >-
    The Payment Reconfirmation for Financial Institutions endpoint is only
    available if you are a Financial Institution reconfirming a previously
    initiated payment using the Payment Initiation endpoint in the ISO XML
    pacs.008.001.08 or pacs.009.001.08 formats and received a pacs.002.001.10
    message with a status Pending reconfirmation.


    You must specify the mandatory request elements at the very least, encrypt
    and sign the payload before placing it in the header-populated request to
    invoke the endpoint via your application. Please note the below rules
    regarding the input parameters:


    1. Either of the 32- character UETR OrgnlUETR (JSON:uetr) or the
    32-character Citi Transaction Reference OrgnlClrSysRef (JSON:citi_reference)
    or the 16-character Instruction ID OrgnlInstrID (JSON:end_to_end_id or
    instruction_id) of the original transaction in the order of priority must be
    specified in the request parameters.

    2. If you specify either the 32- character Citi Transaction Reference or the
    16-character Instruction ID, then the value date ReqdExctnDt
    (JSON:interbank_settlement_date) of the original transaction must be
    specified along with it.

    3. The 4-character ISO reconfirmation code Cd (JSON:reason) is mandatory for
    this endpoint. Below is the complete list of cancellation codes that you may
    use:

    4. For the reconfirmation code specified as MS03, please enter further
    information on the reconfirmation reason in the RsnDesc (JSON: reason_desc)


    CitiConnect will respond with a 4-character standard ISO status code txnSts
    (JSON: transaction_status>status) along with additional information AddlInf
    (JSON: transaction_status>type) informing you of the Accept or Reject status
    of the reconfirmation request. Once reconfirmed, the payment will then
    proceed with further execution.


    <a href="specs.xlsx" download>Click to Download</a> the Payment
    Reconfirmation request.


    Download our SDKs:


    * [Python
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=python&apiTitle=all&isClientSecReq=true)

    * [Java
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=java&apiTitle=all&isClientSecReq=true)

    * [.Net
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=dotnet&apiTitle=all&isClientSecReq=true)

    * [Ruby
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=ruby&apiTitle=all&isClientSecReq=true)

    * [NodeJS
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=nodejs&apiTitle=all&isClientSecReq=true)

    * [Go
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=go&apiTitle=all&isClientSecReq=true)

    * [CLI Tool
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=ccapi-cli&apiTitle=all&isClientSecReq=true)


    Note: You must be logged in to download the SDKs.
  version: 3.0.0
  x-ibm-name: paymentservices
security:
  - clientCredentials: []
    Client ID: []
servers:
  - url: https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3
    description: production gateway URL
  - url: https://tts.apib2b.citi.com/citiconnect/sb/paymentservices/v3
    description: sandbox URL
x-ibm-configuration:
  enforced: true
  phase: realized
  testable: true
  cors:
    enabled: true
  properties:
    FIPaymentsStops:
      value: https://payments-dev-168554.nam.nsroot.net
      description: ''
      encoded: false
    PaymentInitiationAkamai:
      value: https://payments-inbound-168554.cloudgsl.nam.nsroot.net/v3/router
      description: ''
      encoded: false
    Payments:
      value: https://payments-inbound-168554.cloudgsl.nam.nsroot.net/v3/router
      description: ''
      encoded: false
    FIPayments:
      value: https://payments-168554.namicggtd12d.nam.nsroot.net
      description: ''
      encoded: false
    PaymentInquiry-ECS:
      value: https://payment-inquiry-168554.namicggtd12d.nam.nsroot.net
      description: ''
      encoded: false
    PaymentInitiation:
      value: https://payments-inbound-168554.cloudgsl.nam.nsroot.net/v3/router
      description: ''
      encoded: false
    BE-EnquiriesService:
      description: ''
      encoded: false
      value: >-
        https://sit2citiconnectbeservices.nam.nsroot.net/citi-connect-war/services/CitiConnectInquiriesService
  catalogs:
    UAT1:
      properties:
        BE-EnquiriesService: >-
          https://payment-inquiry-ms-uat-168554.namicgswd11u.nam.nsroot.net/paymentservices/v3/inquiry
        PaymentInitiation: https://payments-inbound-uat-168554.nam.nsroot.net/v3/router
        PaymentInquiry-ECS: https://payment-inquiry-uat-168554.namicgswd10u.nam.nsroot.net
        FIPayments: https://payments-uat-168554.namicgswd10u.nam.nsroot.net
        Payments: https://payments-inbound-uat-168554.nam.nsroot.net/v3/router
        PaymentInitiationAkamai: https://payments-inbound-uat-168554.wlb3.nam.nsroot.net/v3/router
        FIPaymentsStops: https://payments-uat-168554.nam.nsroot.net
    SIT5:
      properties:
        BE-EnquiriesService: >-
          https://payment-inquiry-ms-168554.namicggtd10d.nam.nsroot.net/paymentservices/v3/inquiry
        PaymentInitiation: https://payments-inbound-dev-168554.nam.nsroot.net/v3/router
        PaymentInquiry-ECS: https://payment-inquiry-168554.namicggtd12d.nam.nsroot.net
        FIPayments: https://payments-168554.namicggtd12d.nam.nsroot.net
        Payments: https://payments-inbound-dev-168554.nam.nsroot.net/v3/router
        PaymentInitiationAkamai: https://payments-inbound-dev-168554.wlb3.nam.nsroot.net/v3/router
        FIPaymentsStops: https://payments-dev-168554.nam.nsroot.net
    Sandbox:
      properties:
        BE-EnquiriesService: >-
          https://payment-inquiry-ms-168554.namicgswd11u.nam.nsroot.net/paymentservices/v3/inquiry
        PaymentInitiation: https://payments-inbound-cte-168554.nam.nsroot.net/v3/router
        PaymentInquiry-ECS: https://payment-inquiry-cte-168554.namicgswd12u.nam.nsroot.net
        FIPayments: https://payments-cte-168554.namicgswd12u.nam.nsroot.net
        Payments: https://payments-inbound-cte-168554.nam.nsroot.net/v3/router
        PaymentInitiationAkamai: https://payments-inbound-cte-168554.wlb3.nam.nsroot.net/v3/router
        FIPaymentsStops: https://payments-cte-168554.nam.nsroot.net
    PROD:
      properties:
        BE-EnquiriesService: >-
          https://payment-inquiry-legacy-168554.cloudgsl.nam.nsroot.net/paymentservices/v3/inquiry
        PaymentInitiation: https://payments-inbound-168554.cloudgsl.nam.nsroot.net/v3/router
        PaymentInquiry-ECS: https://payment-inquiry-168554.cloudgsl.nam.nsroot.net
        FIPayments: https://payments-168554.nam.nsroot.net
        Payments: https://payments-inbound-168554.cloudgsl.nam.nsroot.net/v3/router
        PaymentInitiationAkamai: https://payments-inbound-168554.wlb3.nam.nsroot.net/v3/router
        FIPaymentsStops: https://payments-168554.nam.nsroot.net
    PTE:
      properties:
        BE-EnquiriesService: >-
          https://payment-inquiry-ms-pte-168554.namicgswd12u.nam.nsroot.net/paymentservices/v3/inquiry
        PaymentInitiation: >-
          https://payments-inbound-pte-wip-168554.cloudgsl.nam.nsroot.net/v3/router
        PaymentInquiry-ECS: https://payment-inquiry-pte-168554.namicgswd12u.nam.nsroot.net
        FIPayments: https://payments-pte-168554.namicgswd12u.nam.nsroot.net
        Payments: >-
          https://payments-inbound-pte-wip-168554.cloudgsl.nam.nsroot.net/v3/router
        PaymentInitiationAkamai: https://payments-inbound-pte-168554.wlb3.nam.nsroot.net/v3/router
        FIPaymentsStops: https://payments-pte-wip-168554.nam.nsroot.net
    UAT2:
      properties:
        PaymentInquiry-ECS: https://payment-inquiry-uat-168554.namicgswd10u.nam.nsroot.net
        FIPayments: https://payments-uat-168554.namicgswd10u.nam.nsroot.net
        PaymentInitiation: https://payments-inbound-uat-168554.nam.nsroot.net/v3/router
        PaymentInitiationAkamai: https://payments-inbound-uat-168554.wlb3.nam.nsroot.net/v3/router
        FIPaymentsStops: https://payments-uat-168554.nam.nsroot.net
  externalDocs: []
  attachments: []
  gateway: datapower-gateway
  assembly:
    execute:
      - operation-switch:
          title: operation-switch
          case:
            - operations:
                - verb: post
                  path: /payments/reconfirmations
              execute:
                - proxy:
                    title: proxy
                    timeout: 60
                    verb: keep
                    cache-response: protocol
                    cache-ttl: 900
                    version: 1.0.0
                    tls-profile: citiconnect-ssl-profile
                    target-url: $(FIPayments)/v3/payments/reconfirmations
tags: []
securityDefinitions:
  Client ID:
    description: ''
    in: query
    name: client_id
    type: apiKey
  clientCredentials:
    type: oauth2
    flow: application
    tokenUrl: /authenticationservices/v1/oauth/token
    description: >-
      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.
    x-scopeValidate:
      tls-profile: citi-direct-ssl-profile
paths:
  /payments/reconfirmations:
    post:
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/definitions/fi_response'
            application/xml:
              schema:
                $ref: '#/definitions/fi_response'
              example: >-
                <?xml version="1.0"
                encoding="UTF-8"?><TxInfAndSts><TxSts>RJCT</TxSts><AddtlInf>Transaction
                Not Found</AddtlInf></TxInfAndSts>
        '400':
          description: Bad Request
          examples:
            application/json:
              errors:
                - action: >-
                    Please provide valid value for either uetr or
                    (citi_reference/instruction_id with
                    interbank_settlement_date).
                  issue: uetr/citi_reference/instruction_id cannot be null or empty.
              http_code: 400
              status: FAILED
            application/xml:
              errors:
                - action: >-
                    Please provide valid value for either uetr or
                    (citi_reference/instruction_id with
                    interbank_settlement_date).
                  issue: uetr/citi_reference/instruction_id cannot be null or empty.
              http_code: 400
              status: FAILED
          schema:
            $ref: '#/definitions/error_response'
        '401':
          description: Unauthorized
          examples:
            application/json:
              errors:
                - action: Please try again with valid credentials.
                  issue: Authorization failed.
              http_code: 401
              status: FAILED
            application/xml:
              errors:
                - action: Please try again with valid credentials.
                  issue: Authorization failed.
              http_code: 401
              status: FAILED
          schema:
            $ref: '#/definitions/error_response'
        '405':
          description: Method Not Allowed
          examples:
            application/json:
              errors:
                - action: Please use valid Http Verb.
                  issue: Method not allowed.
              http_code: 405
              status: FAILED
            application/xml:
              errors:
                - action: Please use valid Http Verb.
                  issue: Method not allowed.
              http_code: 405
              status: FAILED
          schema:
            $ref: '#/definitions/error_response'
        '415':
          description: Unsupported Media Type
          examples:
            application/json:
              errors:
                - action: Resend request in valid format.
                  issue: provided content-type of the request is not valid.
              http_code: 415
              status: FAILED
            application/xml:
              errors:
                - action: Resend request in valid format.
                  issue: provided content-type of the request is not valid.
              http_code: 415
              status: FAILED
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Internal Server Error
          examples:
            application/json:
              errors:
                - action: Please try again after sometime.
                  issue: unable to process your request at this moment.
              http_code: 500
              status: FAILED
            application/xml:
              errors:
                - action: Please try again after sometime.
                  issue: unable to process your request at this moment.
              http_code: 500
              status: FAILED
          schema:
            $ref: '#/definitions/error_response'
      parameters:
        - description: >-
            This field used to identify request is for reconfirm/reject (Example
            - RECNFRM / RJCTCNFRM) FI Payments.
          in: header
          maxLength: 12
          name: request_type
          required: true
          type: string
        - description: >-
            Unique reference which was shared during CitiConnect API
            on-boarding(client_id which used during oauth token generation)
          in: query
          name: client_id
          required: true
          type: string
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/fi_reconfirmation_request'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/definitions/fi_reconfirmation_request'
          application/xml:
            schema:
              $ref: '#/definitions/fi_reconfirmation_request'
            example: >-
              <?xml version="1.0"
              encoding="UTF-8"?><TransacService><InstrId>2009360588</InstrId><ReqdExctnDt>2020-09-25</ReqdExctnDt><Rsn>DUPL</Rsn></TransacService>
        required: true
      operationId: fiPaymentReconfirmation
      summary: Payment Reconfirmation
      description: >-
        This API allows you to initiate reconfirm/reject FI payments in JSON and
        XML format.
definitions:
  ErrorDetail:
    properties:
      action:
        description: corrective action to be taken to resolve above issue
        maxLength: 350
        type: string
      issue:
        description: more details about the  issue
        maxLength: 200
        type: string
    type: object
    xml:
      name: error
  error_response:
    properties:
      errors:
        description: >-
          Indicates actual error details with issues and corresponding actions
          to resolve the issue
        items:
          $ref: '#/definitions/ErrorDetail'
        xml:
          wrapped: true
      http_code:
        description: Indicates http status code to specify http response status
        format: int32
        pattern: ^[0-9]{3}$
        type: integer
      status:
        description: >-
          This field  indicates the status of the reconfirm/reject or
          cancel/recall request with set of values. for example- FAILED
        maxLength: 6
        type: string
    type: object
  fi_cancellation_request:
    properties:
      citi_reference:
        description: >-
          This field specifies the Product processor Reference Number for the
          transaction that needs to be cancelled or recalled. UETR or
          citi_reference with interbank_settlement_date or end_to_end_id /
          instruction_id with interbank_settlement_date is mandatory.
        maxLength: 32
        type: string
      end_to_end_id:
        description: >-
          This is a  unique end-to-end  reference number that identifies a
          transaction that needs to be cancelled. UETR or citi_reference with
          interbank_settlement_date or end_to_end_id / instruction_id with
          interbank_settlement_date is mandatory.
        maxLength: 35
        type: string
      instruction_id:
        description: >-
          This is a  unique end-to-end  reference number that identifies a
          transaction that needs to be cancelled. UETR or citi_reference with
          interbank_settlement_date or end_to_end_id / instruction_id with
          interbank_settlement_date is mandatory.
        maxLength: 35
        type: string
      interbank_settlement_date:
        description: >-
          This field specifies the value date (yyyy-MM-dd) of the original
          transaction that needs to be cancelled or recalled (the date on which
          funds were credited to the account).
        type: string
      reason:
        description: >-
          This is the four digits cancellation code (Example - DUPL) which is
          specified by the  customer to request to cancel the transaction
        maxLength: 4
        type: string
      reason_description:
        description: >-
          Further details on the request reason. Required for CUST and MS03
          reason codes applicable to Stop and Reconfirmation services
          respectively.
        maxLength: 150
        type: string
      uetr:
        description: >-
          Unique End-to-end Transaction Reference (UETR) relating to a payment
          has been identified as being associated with a Request for
          Cancellation. it should follow UUID version 4 format. UETR or
          citi_reference with interbank_settlement_date or end_to_end_id /
          instruction_id with interbank_settlement_date is mandatory.
        type: string
    required:
      - reason
    type: object
  fi_reconfirmation_request:
    properties:
      citi_reference:
        description: >-
          This field specifies the Product processor Reference Number for the
          transaction that needs to be reconfirm/reject. UETR or citi_reference
          with interbank_settlement_date or instruction_id with
          interbank_settlement_date is mandatory.
        maxLength: 32
        type: string
        xml:
          name: ClrSysRef
      instruction_id:
        description: >-
          This is a unique instrution id that identifies a transaction that
          needs to be reconfirm/reject. UETR or citi_reference with
          interbank_settlement_date or instruction_id with
          interbank_settlement_date is mandatory.
        maxLength: 35
        type: string
        xml:
          name: InstrId
      interbank_settlement_date:
        description: >-
          This field specifies the value date (yyyy-MM-dd) of the original
          transaction that needs to be reconfirm/reject (the date on which funds
          were credited to the account).
        format: date
        type: string
        xml:
          name: ReqdExctnDt
      reason:
        description: >-
          This is the five digits reconfirm/reject code (Example DUPL) which is
          specified by the  customer to request to reconfirm/reject the
          transaction
        maxLength: 5
        type: string
        xml:
          name: Rsn
      uetr:
        description: >-
          Unique End-to-end Transaction Reference (UETR) relating to a payment
          has been identified as being associated with a Request for
          reconfirm/reject. It should follow UUID version 4 format. UETR or
          citi_reference with interbank_settlement_date or instruction_id with
          interbank_settlement_date is mandatory.
        type: string
        xml:
          name: UETR
    required:
      - reason
    type: object
    xml:
      name: TransacService
  fi_response:
    properties:
      transaction_status:
        $ref: '#/definitions/transaction_status_detail'
    type: object
  transaction_status_detail:
    properties:
      status:
        description: >-
          This field  indicates the status of the reconfirm/reject or
          cancel/recall request with set of values. for example- ACCP for
          Accepted or RJCT for Rejected
        maxLength: 4
        type: string
        xml:
          name: TxSts
      type:
        description: >-
          This field provides additional information of the transaction when it
          is rejected/accepted.
        maxLength: 500
        type: string
        xml:
          name: AddtlInf
    type: object
    xml:
      name: TxInfAndSts
  payments_request:
    properties:
      paymentBase64:
        description: Base64 encoded string of ISO XML payment initiation input xml
        format: byte
        type: string
    required:
      - paymentBase64
    type: object
  payments_response:
    properties:
      psrDocument:
        description: Base64 encoded string of ISO XML payment initiation response xml
        format: byte
        type: string
    required:
      - psrDocument
    type: object
  payments_error_response:
    properties:
      correlationId:
        description: input request tracking unique id
        type: string
      message:
        description: message providing information about error
        type: string
      status:
        description: error status code
        type: string
    type: object
x-components:
  examples:
    accpStatusXmlExample:
      value:
        status: ACCP
        type: >-
          Your request has been registered. We will notify you once the txn is
          reconfirmed / rejected.
    fi_cancellation:
      value: >-
        <Document
        xmlns='urn:iso:std:iso:20022:tech:xsd:camt.056.001.09'><FIToFIPmtCxlReq><Undrlyg>
        <TxInf><CxlId>98a8011be00e406999d8822c0a25d4be</CxlId><OrgnlGrpInf><OrgnlMsgId>d3a99efb5a8b45339829b4d620cc73cd</OrgnlMsgId>
        <OrgnlMsgNmId>pacs.008.001.02</OrgnlMsgNmId></OrgnlGrpInf><OrgnlUETR>eeea24a4-02ea-4fa9-b624-64647ddb4fbf</OrgnlUETR>
        <OrgnlClrSysRef>citi201</OrgnlClrSysRef><OrgnlInstrId>endtoendid101</OrgnlInstrId><OrgnlTxRef>
        <ReqdExctnDt><Dt>2020-09-25</Dt></ReqdExctnDt></OrgnlTxRef></TxInf><OrgnlGrpInfAndCxl>
        <CxlRsnInf><Rsn><Cd>DUPL</Cd><Prtry>DUPL</Prtry></Rsn><AddtlInf>DUPL</AddtlInf>
        </CxlRsnInf></OrgnlGrpInfAndCxl></Undrlyg></FIToFIPmtCxlReq></Document>
    fi_cancellation_response:
      value: >-
        <Document
        xmlns='urn:iso:std:iso:20022:tech:xsd:pacs.002.001.10'><FIToFIPmtStsRpt><TxInfAndSts><TxSts>ACCP</TxSts><AddtlInf>Your
        request has been registered. We will notify you once the txn is
        stopped/recalled.</AddtlInf></TxInfAndSts></FIToFIPmtStsRpt></Document>
    rjctStatusXmlExample:
      value:
        status: RJCT
        type: Transaction not found.
    withCitiReference:
      value:
        citi_reference: KK14MY7FP3X7
        interbank_settlement_date: '2020-09-25'
        reason: DUPL
    withEndToEndId:
      value:
        end_to_end_id: 2009360588
        interbank_settlement_date: '2020-09-25'
        reason: DUPL
    withInstructionId:
      value:
        instruction_id: 2009360588
        interbank_settlement_date: '2020-09-25'
        reason: DUPL
    withUETR:
      value:
        reason: DUPL
        uetr: eb6305c9-1f7f-49de-aed0-16487c27b42d