Payment Initiation | Citi Docs Demo

curl -X POST "https://b2b.tts.icgservices.citi.com/citiconnect/prod/paymentservices/v3/payment/initiation?client_id=client_id" \
     -H "Authorization: Bearer <token>" \
     -H "payloadType: payloadType" \
     -H "Content-Type: application/xml" \
     -d '{
  "CstmrCdtTrfInitn": {
    "GrpHdr": {
      "CreDtTm": "2017-06-02T10:17:55",
      "InitgPty": {
        "Nm": "ABC"
      },
      "MsgId": "8fc1b5da421611ecae9c005",
      "NbOfTxs": "1",
      "CtrlSum": "1200"
    },
    "PmtInf": [
      {
        "CdtTrfTxInf": [
          {
            "Amt": {
              "InstdAmt": {
                "Ccy": "CNY",
                "Value": "1200"
              }
            },
            "PmtId": {
              "EndToEndId": "1234567890"
            },
            "Cdtr": {
              "Nm": "同振证券外资公司",
              "Id": {
                "OrgId": {
                  "Othr": [
                    {
                      "Id": "M20241030151729"
                    }
                  ]
                }
              }
            },
            "CdtrAcct": {
              "Id": {
                "IBAN": "string",
                "Othr": {
                  "Id": "6221554579063681732"
                }
              }
            },
            "CdtrAgt": {
              "FinInstnId": {
                "ClrSysMmbId": {
                  "MmbId": "102891613014"
                },
                "Nm": "中国工商银行股份有限公司拜城支行"
              }
            },
            "RmtInf": {
              "Ustrd": [
                "订单后置"
              ]
            }
          }
        ],
        "Dbtr": {
          "Nm": "sample data",
          "PstlAdr": {
            "Ctry": "CN",
            "TwnNm": "SHANGAI"
          }
        },
        "DbtrAcct": {
          "Id": {
            "IBAN": "string",
            "Othr": {
              "Id": "1888665664"
            }
          }
        },
        "DbtrAgt": {
          "FinInstnId": {
            "BIC": "CITICN2XXXX"
          }
        },
        "PmtInfId": "8fc1b5da421611ecae9c005056b310ad",
        "PmtMtd": "TRF",
        "ReqdExctnDt": "2025-04-07",
        "NbOfTxs": "1",
        "PmtTpInf": {
          "LclInstrm": {
            "Prtry": "CITIA01"
          },
          "SvcLvl": {
            "Cd": "NURG"
          }
        }
      }
    ]
  }
}'

You can initiate a new payment through the Payment Initiation endpoint. This endpoint takes the necessary data required in ISOXML pain.001.001.03 format to initiate a payment through CitiConnect API. It can be used to initiate one outgoing payment request per API call.

Each payment method take different input values based on the type of payment. Input values are also based on regulatory or local requirements.

Note: The required parameters vary depending on the countries and currencies used in the request. For detailed and up-to-date information on the necessary fields and formats, see the Citi Payment Formatting Rules Tool.

The Payment Initiation service accommodates all different data attributes for all the available payment methods.

payloadType: Supports urn:iso:std:iso:20022:tech:xsd:pain.001.001.03.
Request: The request follows ISO XML V3 (pain.001.001.03) standards.
paymentBase64: ISO XML V3 (pain.001.001.03) file has to be converted to Base64 format and passed in <Request><paymentBase64> tags.
Response: The response follows ISO XML (pain.002.001.03) standards.

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

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

Contains the required fields of the ISOXML request body. The request body must be Base64 encoded and enclosed within the <Request><paymentBase64> tags.

Note: The required fields of the requestBody are highly dependent on the countries and currencies used in the payment. For the most specific and up-to-date fields use the Citi Payment Formatting Rules Tool. This example requestBody is provided for guidance.

CstmrCdtTrfInitnobjectRequired

The CustomerCreditTransferInitiation message is sent by the initiating party to the forwarding agent or debtor agent. This message is used to request movement of funds from the debtor account to a creditor.

Response

OK - your request was received and acknowledged successfully.

Check the response body for the transaction status.

Payment Status	Recommended Action
Decrypted payload is unintelligible	Make a payment status inquiry every 5 minutes for 15 minutes. If you do not receive a response, contact Citi.
ACTC/ACCP - Accepted	Make a payment status inquiry every 5 minutes
PDNG - Pending	Make a payment status inquiry every 60 minutes
RJCT - Rejected	See the status reason for more information
ACSP/ACSC - Payment successfully processed and cleared	No action required

Authentication

Headers

Query parameters

Request

Response