Inquire for the latest status of transations matching additional parameters. | Citi Docs Demo

curl -G https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/payments \
     -H "Authorization: Bearer <token>" \
     -d batch_id=492084893 \
     -d client_id=6d3cf821-db6d-496d-bec0-064a362e9c31 \
     --data-urlencode creation_date_time_end=2022-09-13T08:23:49.554Z \
     --data-urlencode creation_date_time_start=2022-09-13T08:23:49.114Z \
     -d creditor_account_last4=0783 \
     -d debtor_account_last4=6373 \
     -d end_to_end_id=1L00IF2BCWUZF09 \
     -d instructed_amount=73945.27 \
     -d network_id=209323283934 \
     -d settlement_amount=50000.23 \
     -d status_code=ACCC \
     --data-urlencode status_date_time_end=2022-09-13T08:23:49.331Z \
     --data-urlencode status_date_time_start=2022-09-13T08:23:49.224Z

[
  {
    "debtor": {
      "account": "897654321"
    },
    "creditor": {
      "account": "44227754321"
    },
    "method": {
      "country": "TH",
      "instructed_currency": "THB",
      "method": "IP",
      "type": "CT"
    },
    "transaction": {
      "end_to_end_id": "r/434SKtUcdGQ",
      "uetr": "4f09214d-296c-494b-8e9c-810bf1d9fc93",
      "creation_date_time": "2022-09-13T08:23:49.112Z",
      "status": {
        "date_time": "2022-09-13T08:23:56.223Z",
        "code": "ACCC",
        "description": "Completed"
      },
      "network_id": "209323283934",
      "local_reference": "7634an78543",
      "type": "credit",
      "purpose": "CASH",
      "value_date": "2022-09-13",
      "instructed_amount": 29876.98,
      "settlement_currency": "THB",
      "settlement_amount": 29876.98,
      "reasons": [
        {
          "description": "Citi validated and commercially completed the transaction. Account posting may be pending."
        }
      ]
    }
  },
  {
    "debtor": {
      "account": "557654321"
    },
    "creditor": {
      "account": "66227754321"
    },
    "method": {
      "country": "TH",
      "instructed_currency": "THB",
      "method": "IP",
      "type": "CT"
    },
    "transaction": {
      "end_to_end_id": "r/434SKtUcdGQ",
      "uetr": "4f00214d-296c-404b-8e9c-810bf1d9fc93",
      "creation_date_time": "2022-09-13T08:23:49.112Z",
      "status": {
        "date_time": "2022-09-13T08:23:56.223Z",
        "code": "ACCC",
        "description": "Completed"
      },
      "network_id": "209323283934",
      "local_reference": "9634an78543",
      "type": "credit",
      "purpose": "CASH",
      "value_date": "2022-09-13",
      "instructed_amount": 276.98,
      "settlement_currency": "THB",
      "settlement_amount": 276.98,
      "reasons": [
        {
          "description": "Citi validated and commercially completed the transaction. Account posting may be pending."
        }
      ]
    }
  }
]

-Get the latest statuses of payment transactions using matching criteria. Currently, you can get the latest transactions statuses up to 90 days from the payment initiation date. If the latest transactions statuses date is 90+ days old, the endpoint responds with HTTP status 404 (not found). -You can use this endpoint to pull the transactions of all payment methods that includes Wires, ACH, and IP. For ACH and Wires, use the end_to_end_id to pull the transactions.

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.

Headers

encrypted-paramsstringOptionalformat: "\w*\W*"

Encrypt the key values as below. Debtor account or creditor account is mandatory.

debtor_account: Your Citi account for instant payment (debit) / outgoing
creditor_account: Your Citi account for instant payment (credit) / incoming
debtor_proxy_id: Debtor proxy identification - For US RTP Instant Payment - debtor_proxy_id header param is not applicable
creditor_proxy_id: Creditor proxy identification - For US RTP Instant Payment - creditor_proxy_id header param is not applicable
debtor_virtual_account: Your Citi virtual account for instant payment (debit) / outgoing - For US RTP Instant Payment - debtor_virtual_account header param is not applicable
creditor_virtual_account: Your Citi virtual account for instant payment (credit) / incoming - For US RTP Instant Payment - creditor_virtual_account header param is not applicable

Sample header before encryption: {“debtor_account”:“3001386964”,“creditor_proxy_id”:“a93d@gmail.com”}

Query parameters

client_idstringRequired

Your unique identification, same as the identification you use for OAuth token generation, Citi shared with you during your CitiConnect API onboarding

end_to_end_idstringOptionalformat: "^(?!\s*$).+"1-35 characters

Transaction identification provided by the debtor

network_idstringOptional<=36 characters

Transaction reference generated for or by a network (e.g., PromptPay)

batch_idstringOptional<=35 characters

Identification for your Citi account consolidated debit or credit posting for the transactions

creation_date_time_startdatetimeOptional

GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)

Instant Payment (Debit) - Start of date time, generated by CitiConnect API, when CitiConnect API accepted a payment initiation after validation
Instant Payment (Credit) - Start of date time, either provided by the debtor bank or generated by Citi’s transaction processing application, when a transaction was created

creation_date_time_enddatetimeOptional

GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)

Instant Payment (Debit) - End of date time, generated by CitiConnect API, when CitiConnect API accepted a payment initiation after validation
Instant Payment (Credit) - End of date time, either provided by the debtor bank or generated by Citi’s transaction processing application, when a transaction was created

instructed_amountdoubleOptional<=1000000000000000

Instructed amount

settlement_amountdoubleOptional<=1000000000000000

Settlement amount (e.g., after any currency exchange or charge on the instructed amount)

status_date_time_startdatetimeOptional

GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)

Instant Payment - Start date time of the transaction status change (when CitiConnect API change the status of the transaction)

status_date_time_enddatetimeOptional

GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)

Instant Payment - Start end time of the transaction status change (when CitiConnect API change the status of the transaction)

status_codeenumOptional

ISO 20022 transaction status code

Allowed values:

debtor_account_last4stringOptionalformat: "^[0-9]{4}$"

Last 4 digits of a debtor account in combination with your Citi creditor account

creditor_account_last4stringOptionalformat: "^[0-9]{4}$"

Last 4 digits of a creditor account number in combination with your Citi debtor account

offsetintegerOptionalDefaults to 0

Payment status inquiry result page you want Citi to respond to you with

limitintegerOptional1-1000Defaults to 100

Limit you want Citi to apply to your payment status inquiry results

Maximum value is 1,000.

Response headers

request_idstringOptional

Citi's unique identification for your request

resultinteger

Number of transaction status matching your request

Response

Payment status

debtorobject

Debtor information

creditorobject

Object representing the receiver of a transaction.

methodobject

transactionobject

message_idstringOptional<=35 characters

Message Identification

If transaction.status.code = ACCC/PDNG/RJCT/ACWP then this field may be present

ultimate_debtorobjectOptional

ultimate_creditorobjectOptional

intermediarylist of objectsOptional

Intermediary agent information status

instructed_agentobjectOptional

instructing_agentobjectOptional

account_validationobjectOptional

initiating_partyobjectOptional

original_paymentobjectOptional

Either populate uetr OR (end_to_end_id AND value_date) for the refund to be processed

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error