Citi API | Payments › Enhanced Inquiry Deprecated

This API allows clients to inquire details of their transactions for both Incoming and Outgoing payments based on various significant parameters.

Content-Type : Supports application/json and format PSRJ03 :
Authorization : The OAuth Token prefixed with ?Bearer? and space in between. :

Security

Body parameters

account?: string

This field holds the Citi bank Corporate Client's account number

account_servicer_reference?: string

This field represents Citi Transaction reference number for the transaction as displayed in account statements. Ex - MT940 (Account Servicing institution reference)

bic_or_bei?: string

This field holds the Citi bank Corporate Client's Bank Branch BIC code. Example - CITISGSGXXX. If the BIC code contains less than 11 digits then it will be treated an invalid request and rejected.

branch_identification?: string

This field holds the Citi bank Corporate Client's account Branch code. Only a valid Internal Bank Branch code should be provided containing 3/4 digits.

end_to_end_identification?: string

Unique identification assigned by the initiating party to clearly identify the transaction. This Identification is passed on, unchanged, throughout the entire end-to-end chain.

name?: string

This field represents Sender name, if transaction_flow_indicator = CR, and
Beneficairy name, if transaction_flow_indicator = DR. If clients want to search for a particular Remitter or Beneficiary name, then Account number and BIC / Branch code should be provided mandatorily. If not the request will be treated as invalid and rejected

page_number?: string

This field page number, user can input specfic page number based on the search results. The clients will be informed how many transactions the total result contains and along with the page number, If there are more results for their initial search which is not reported back on the first initial response.

remittance_information?: string

This field can be inputed with any payment details information, for ex - Payment Invoice numbers, etc. This field represents Service Type identifier.

requested_execution_date_from?: string

This field represents the from Date at which the initiating party requests the clearing agent to process the payment. Format YYYY-MM-DD

requested_execution_date_to?: string

This field represents the To Date at which the initiating party requests the clearing agent to process the payment. Format YYYY-MM-DD

transaction_flow_indicator?: string

This value indicates whether the transaction is a Credit or debit with the values CR or DR respectively. For Debit Transaction inquiry, this input is not required as by default Sytem will consider the query to be Debit. However for Credit Transaction inquiry this must be inputted as CR. Debit account number should be specified for outgoing transaction.Credit account number should be specified for incoming transaction

transaction_received_date_time_from?: string

This field represents the payment received date & time at Citi range starting from. It must be always specified in UTC format YYYY-MM-DDThh:mm:ss.sTZD. The ?transaction received date from? should not be greater than 90 days from the present business date

transaction_received_date_time_to?: string

This field represents the payment received date & time at Citi range ending to. It must be always specified in UTC format YYYY-MM-DDThh:mm:ss.sTZD. The ?transaction received date to? should not be less than 90 days from the present business date.

uetr?: string

Input UETR number. Unique EndtoEnd Transaction Reference identification assigned by the initiating party or payment processing bank to uniquely identify the transaction. 36 characters, made up to 32 hexadecimal characters, shown in five parts divided by hyphens/dashes as follows - xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

virtual_account?: string

A virtual account number assigned to any particular Citi bank corporate Client's account number.It Should be Virtual account number or payer id.This will be applicable only for Credit / Incoming transactions. This must be provided only when Transaction Indicatory = CR.If this is provided when the Transaction Indicatory = DR, then it will be an invalid request.

Response fields

TransactionResponse

Request example

curl https://$(catalog.host)/cards/vca/v2/paymentservices/v3/payment/enhancedinquiry \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{}'

200Example

{
  "created_date_time": "created_date_time",
  "transactions": [
    {
      "confirmed_amount": {
        "amount": "amount",
        "currency": "currency"
      },
      "creditor": {
        "address_line": [
          "string",
          "string",
          "string"
        ],
        "any_bic": "any_bic",
        "country": "country",
        "country_sub_division": "x",
        "identification": "x",
        "name": "x",
        "postal_code": "x",
        "town": "x"
      },
      "creditor_account": {
        "identification": {
          "iban": "iban",
          "identification": "x"
        }
      },
      "creditor_agent": {
        "clearing_code": "x",
        "any_bic": "any_bic",
        "branch_id": "x"
      },
      "debtor": {
        "any_bic": "any_bic",
        "address_line": [
          "string",
          "string",
          "string"
        ],
        "country": "country",
        "country_sub_division": "x",
        "identification": "x",
        "name": "x",
        "postal_code": "x",
        "town": "x"
      },
      "debtor_account": {
        "identification": {
          "iban": "iban",
          "identification": "x"
        }
      },
      "debtor_agent": {
        "clearing_code": "x",
        "any_bic": "any_bic",
        "branch_id": "x"
      },
      "instructed_amount": {
        "amount": "amount",
        "currency": "currency"
      },
      "payment_event": [
        {
          "charge_amount": {
            "amount": "amount",
            "currency": "currency"
          },
          "charge_bearer": "DEBT",
          "date_time": "date_time",
          "from": "from",
          "to": "to",
          "additional_remittance_information": {
            "credit_virtual_account": "credit_virtual_account",
            "payment_contract": "payment_contract",
            "payment_method": "x",
            "return_account": "xxxx",
            "return_charge_currency": "return_charge_currency",
            "return_currency": "x",
            "return_exchange_rate": "x",
            "return_source_currency": "return_source_currency",
            "confidential": "x",
            "debit_virtual_account": "debit_virtual_account",
            "return_amount": "return_amount",
            "return_charge_amount": [
              "string"
            ],
            "return_contract": "return_contract",
            "return_target_currency": "x"
          },
          "foreign_exchange_details": {
            "exchange_rate": "x",
            "source_currency": "x",
            "target_currency": "x"
          }
        }
      ],
      "service_type_indicator": "xxx",
      "transaction_status": {
        "status": "ACCP",
        "status_reason_information": [
          {
            "reason": "x",
            "reason_description": [
              "string"
            ],
            "type": [
              "x"
            ]
          }
        ]
      },
      "uetr": "x",
      "account_servicer_reference": "x",
      "clearing_system_reference": "x",
      "end_to_end_identification": "x",
      "event_time": "event_time",
      "instruction_identification": "x",
      "originator": "x",
      "request_execution_date": "request_execution_date",
      "unstructured_remittance_information": [
        "string"
      ]
    }
  ]
}

Enhanced Inquiry Deprecated ->

post/payment/enhancedinquiry

Security

Request example

curl https://$(catalog.host)/cards/vca/v2/payment/enhancedinquiry \
    -X POST \
    -H 'Content-Type: undefined' \
    -H "Authorization: Bearer $ACCESS_TOKEN"

Payment Initiation -> unknown

post/payment/initiation

Payment initiation

This service allows you to initiate new payments by accommodating different data attributes for all the available payment methods. After the initial API request call, user receive a response that denotes whether the payment has passed the basic validations.

Initiating a payment using the Payment Initiation API involves making a well-formed POST request to the CitiConnect API.

Supported ISO formats under Payment Initiation API

|Payment Nature| ISO XML format||--|--||Outgoing Payment| pain.001.001.03||Direct Debit Payment| pain.008.001.02|

How to initiate CitiConnect Payment

1. Authenticate to CitiConnect API (Go To Link)
2. Make an API call by specifying the Payment Initiation service URL.
3. Specify your request headers. (See Appendix D: Payment Initiation API Reference for sample requests.)
4. Specify all mandatory values in the ISOXML file at the minimum and encode the XML file with Base64 to place it in the tag. Then sign and encrypt the payload in the body of the request.
5. Review further status using ?Payment Status Inquiry? API.

Verb

Service URL

POST

https://tts.{env_name1}.apib2b.citi.com/citiconnect/{env_name2}/paymentservices/v1/payment/initiation?client_id={client_id}

CTE Environment

{env_name1} = sandbox , {env_name2} = sb

PROD Environment

{env_name1} = NO value , {env_name2} = prod

API Client

client_id = API client_id shared

Parameters

Headers

i.Content-Type( required)
ii.PayloadType(required)
iii.Authorization (required)

Body

Specify all mandatory values in the ISOXML V3 (pain.001.001.03) file at the minimum and encode the XML file with Base64 to place it in the tag.

Response Types

HTTP Status Code

Reason Phrase

200

400

Bad request

401

OAuth header decryption failed! ? Invalid OAuth Token? Unauthorized

403

Forbidden

412

Precondition Failed

404

Service Not Found

405

Method Not Allowed

406

Duplicate Request Recieved

415

Unsupported Media Type

429

Too Many Requests

500

Internal Server Error

This API Allows You To Initiate Reconfirm Reject Fi Payments In Json And Xml Format ->

PaymentCancellation

post/payments/reconfirmations

This API allows you to initiate reconfirm/reject FI payments in JSON and XML format.

This API Allows You To Initiate Stop Recall Fi Payments In Json And Xml Format ->

PaymentCancellation

post/payments/stops

This API allows you to initiate stop/recall FI payments in JSON and XML format.

Domain types

PaymentCancellation = { transaction_status }

TransactionResponse = { created_date_time, transactions }

Payments

Inquiry

payments.inquiry

Methods

Payment Status Inquiry ->

post/payment/inquiry

Payment Status inquiry

This service allows you to access the status of your payments where it generates payment details with status of the payment transaction.

How to initiate to Payment Status Inquiry

To initiate status inquiry to CitiConnect API, you must perform the following tasks in your source code:

1. Authenticate to CitiConnect API (go To link)
2. Make an API call by specifying the Payment Status Inquiry service URL.
3. Specify your request headers.
4. Specify all mandatory values in the XML file at the minimum. Then sign and encrypt the payload in the body of the request with mandatory header values.
5. Review further status using ?Payment Status Inquiry? API.

Verb

Service URL

POST

https://tts.{env_name1}.apib2b.citi.com/citiconnect/{env_name2}/paymentservices/v1/payment/inquiry?client_id={client_id}

CTE Environment

{env_name1} = sandbox , {env_name2} = sb

PROD Environment

{env_name1} = NO value , {env_name2} = prod

API Client

client_id = API client_id shared

Parameters

Headers

i.Content-Type( required)
ii.Authorization ( required)

Body

i.EndToEndId( required):

Unique identification assigned by the initiating party to clearly identify the transaction. This Identification is passed on, unchanged, throughout the entire end-to-end chain.

ii.CreDt:

Date when the payment initiation started. The date format is: YYYY-MM-DD.

iii.InstdAmt, Ccy :

Amount of money transferred between the debtor and the creditor before any deduction of charges is made. This is expressed in the currency that is specified by the initiating party.

iv. ReqdExctnDt :

Date that the initiating party requests that the clearing agent process the payment.

Response Types

HTTP Status Code

Reason Phrase

200

400

Bad request

401

OAuth header decryption failed! ? Invalid OAuth Token? Unauthorized

403

Forbidden

412

Precondition Failed

404

Service Not Found

405

Method Not Allowed

406

Duplicate Request Recieved

415

Unsupported Media Type

429

Too Many Requests

500

Internal Server Error

Payment Status Inquiry ->

get/payment/inquiry

Payment Status inquiry- GET

This service allows you to access the status of your payments in an innovative way where it generates payment details with status of the payment transaction.

How to initiate to Payment Status Inquiry

To initiate status inquiry to CitiConnect API, you must perform the following tasks in your source code:

1. Authenticate to CitiConnect API
2. Make an API call by specifying the Payment Status Inquiry service (GET Verb) URL.
3. Specify your request headers.
4. Specify all mandatory values in the XML file at the minimum. Then sign and encrypt the payload in the body of the request with mandatory header values.
_5_. Review further status using ?Payment Status Inquiry(GET Verb)? API.

Verb

Service URL

GET

https://tts.{env_name1}.apib2b.citi.com/citiconnect/{env_name2}/paymentservices/v1/payment/inquiry?client_id={client_id}

CTE Environment

{env_name1} = sandbox , {env_name2} = sb

PROD Environment

{env_name1} = NO value , {env_name2} = prod

API Client

client_id = API client_id shared

Parameters

Headers

i.Content-Type( required)
ii.Authorization ( required)

Request Parameters

i.GlobalTranNo (required):

UETR number or the global Tran Number

ii.EndToEndId (required):

Unique identification assigned by the initiating party to clearly identify the transaction. This Identification is passed on, unchanged, throughout the entire end-to-end chain.

iii.CreDt:

Date when the payment initiation started. The date format is: YYYY-MM-DD.

iv.InstdAmt, Ccy :

Amount of money transferred between the debtor and the creditor before any deduction of charges is made. This is expressed in the currency that is specified by the initiating party.

v. ReqdExctnDt:

Date that the initiating party requests that the clearing agent process the payment.

Response Types

HTTP Status Code

Reason Phrase

200

400

Bad request

401

OAuth header decryption failed! ? Invalid OAuth Token? Unauthorized

403

Forbidden

412

Precondition Failed

404

Service Not Found

405

Method Not Allowed

406

Duplicate Request Recieved

415

Unsupported Media Type

429

Too Many Requests

500

Internal Server Error

Retrieve ->

get/payment/inquiry/{EndToEndId}