openapi: 3.2.0 info: title: Payments Initiate Payment API x-ibm-name: Payments version: 3.1.11 description: The Payment API provides authenticated clients with a secure and streamlined way to initiate payments and retrieve transaction status programmatically. x-pathalias: payments-v3 contact: url: https://www.citizensbank.com/corporate-finance/overview.aspx?cmclmkt#next-step name: Commercial Sales team x-ibm-summary: '' x-source-url: https://developer.citizensbank.com/product/commercial-banking/api/payments-v3 x-harvested: '2026-09-05' x-harvest-method: searched x-environment: production servers: - url: https://apis.citizensbank.com/v3/payments security: - client-id: [] tags: - name: Initiate Payment paths: /initiate-payment: post: summary: Initiates a payment instruction description: Allows consumer to submit payment instructions of different payment types. operationId: initiatePayment parameters: - $ref: '#/components/parameters/x-fapi-trace-id' - $ref: '#/components/parameters/x-fapi-channel-id' - $ref: '#/components/parameters/authorization' requestBody: required: true description: The request body must include account identifiers and bank identifiers to initiate account inquiry process. content: application/json: schema: $ref: '#/components/schemas/PaymentInitiationRequest' responses: '200': description: The operation was successful. content: application/json: schema: $ref: '#/components/schemas/PaymentInitiationResponse' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized Access or app-token is not valid. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' tags: - Initiate Payment components: schemas: PaymentInitiationResponse: type: object required: - paymentId - paymentStatus - receivedDateTime properties: paymentId: type: string example: M20190404OR description: Unique identifier for the payment submission request maxLength: 15 paymentStatus: type: string example: RECEIVED description: Status of the payment instruction. maxLength: 30 enum: - RECEIVED receivedDateTime: format: date example: '2024-09-30' description: The date and time when the request was received. description: Response fields of the ACH Credit transfer initiated. UltimateDebtor: type: object required: - name properties: name: type: string example: ACME CORP description: Name of the ultimate debtor party. maxLength: 140 id: type: string example: '187658' description: Id of the ultimate debtor party. maxLength: 35 postalAddress: $ref: '#/components/schemas/Address' description: Ultimate debtor (3rd party) details CounterpartyAccountInformation: type: object required: - accountNumber - routingNumber properties: routingNumber: type: string example: 53000196 description: Counteryparty account holder's ABA(routing) number. minLength: 9 maxLength: 9 accountNumber: type: string example: 123456789 description: Counteryparty account holder's account number. maxLength: 17 description: Counterparty is the crediting bank for RTP and ACH Credit; or debiting bank for ACH Debit. RtpDetails: type: object required: - counterpartyAddressInformation properties: debtor: $ref: '#/components/schemas/Debtor' ultimateDebtor: $ref: '#/components/schemas/UltimateDebtor' ultimateCreditor: $ref: '#/components/schemas/UltimateCreditor' counterpartyAddressInformation: $ref: '#/components/schemas/CounterpartyAddressInformation' description: This object provides the list of request fields needed to originate a RTP credit transfer. This section is driven by the paymentType. This object becomes mandatory for paymentType RTP. Error: type: object required: - errorDetails - result - source properties: result: type: string example: FATAL description: It represents the error status. Its value should be either WARNING or FATAL. * `FATAL` - is an error which represents that something is not correct while processing the request. It could be because of the request or something is not correct with the processing system. * `WARNING` - is a success with some information which means it is not an absolute successful transaction. However response will have information about what is needed in order to be an absolute successful transaction. maxLength: 7 enum: - FATAL - WARNING source: type: string example: Payments System description: Source system or provider system which causes error. maxLength: 100 errorDetails: type: array items: $ref: '#/components/schemas/Error_errorDetails' PaymentAccountInformation: type: object required: - accountNumber - routingNumber properties: routingNumber: type: string example: '2523216' description: Client account holder's ABA(routing) number. minLength: 9 maxLength: 9 accountNumber: type: string example: '766060252' description: Client account holder's account number. maxLength: 17 description: The client party's account details Address: type: object required: - city - line1 - postalCode properties: line1: type: string example: 1 CITIZENS PLAZA description: Address line 1, associated with the address. maxLength: 70 line2: type: string example: SUITE 100 description: Address line 2, associated with the address. maxLength: 70 city: type: string example: PROVIDENCE description: City. maxLength: 35 postalCode: type: string example: 2903 description: Postal Code of address. maxLength: 16 state: type: string example: RI description: State of address. minLength: 1 maxLength: 35 country: type: string example: US description: Two digit ISO country code of address. minLength: 2 maxLength: 2 pattern: ^[a-zA-Z]+$ PaymentInitiationRequest: type: object required: - amount - counterpartyAccountInformation - paymentAccountInformation - paymentId - paymentType properties: paymentId: type: string example: MCCSAP20190404A description: Unique identifier assigned by the consumer for the payment submission request maxLength: 15 paymentAccountInformation: $ref: '#/components/schemas/PaymentAccountInformation' counterpartyAccountInformation: $ref: '#/components/schemas/CounterpartyAccountInformation' amount: type: number format: double example: 100.23 description: Initiated payment amount for the transaction. Decimal point has to be added in the amount sent and it can have maximum 11 digits before the decimal and maximum 2 digits after the decimal for RTP transactions. ACH transactions can have maximum 8 digits before the decimal and maximum 2 digits after the decimal. The amount for an ACH prenote should be sent as zero. memo: type: string example: DIGITAL WALLET PAYMENT- text will be visible to the receiver description: Free-form information to be conveyed to the receiver. minLength: 1 maxLength: 140 paymentType: type: string example: RTP description: The type of transaction being initiated. Possible values are RTP - Real-time payments are payments made between bank accounts that are initiated, cleared and settled within seconds, at any time of the day or week, holidays and weekends included. ACH_CREDIT - Credit transfers done through the Automated Clearing House, a network that allows electronic money transfers between banks and credit unions. ACH_DEBIT - Direct debits done through the Automated Clearing House, a network that allows electronic money transfers between banks and credit unions. maxLength: 10 enum: - RTP - ACH_CREDIT - ACH_DEBIT rtpDetails: $ref: '#/components/schemas/RtpDetails' achDetails: $ref: '#/components/schemas/AchDetails' UltimateCreditor: type: object required: - name properties: name: type: string example: JOHN SMITH description: Name of the ultimate creditor party. maxLength: 140 id: type: string example: '210356' description: Id of the ultimate creditor party. maxLength: 35 postalAddress: $ref: '#/components/schemas/Address' description: Ultimate debtor (3rd party) details AchDetails: type: object required: - companyEntryDescription - companyIdentification - companyName - counterpartyInformation - effectiveEntryDate - standardEntryClassCode properties: standardEntryClassCode: type: string example: CCD description: Three-character code used to identify types of entries. Values of Standard Entry Class code should be PPD - An entry initiated by an organization to consumer account of the receiver where authorization is obtained in writing. WEB - A single, recurring or standing authorization for by an organization to a consumer for an ACH debit entry when the internet or mobile device is used to initiate the payment. CCD - A single or a recurring ACH credit or debit originated to a corporate account. CTX - A single or a recurring ACH credit or debit originated to a corporate account that supports up to 9,999 addenda records. enum: - PPD - WEB - CCD - CTX companyIdentification: type: string example: Achme1234 description: Used to identify the Originator. Assigned by the ODFI. companyName: type: string example: Achme description: Name of the Originator known and recognized by the Receiver. companyDescriptiveDate: type: string example: 93024 description: Allows originator to establish for descriptive purpose to identify the date. It may or may not be displayed to the receiver. effectiveEntryDate: type: string format: date example: '2024-09-30' description: This field will enable the originator to specify a banking day controlling the settlement of the entries in the batch. prenote: type: string example: 'NO' description: A prenote is a zero-dollar payment sent to a bank to verify a recipient's account and routing information before sending a live transaction. companyDiscretionaryData: type: string example: DIGIAL WALLET PAYOUT description: Allows the company to include information of significance only to you. maxLength: 20 companyEntryDescription: type: string example: PAYOUT description: Allows originator to insert a description of the entry's purpose. maxLength: 10 counterpartyInformation: $ref: '#/components/schemas/CounterpartyInformation' identificationNumber: type: string example: MCCSAP20190404B description: The number by which the receiver is known to the originator. It is included for further identification. If not provided in the request then the paymentId would be passed in this field. maxLength: 15 addenda: type: array example: - DIGITAL WALLET PAYMENT - INVOICE# 673425 description: A freeform text field that will travel with the payment instruction to the receiving financial institution. Multiple addenda records can be sent only for payments having CTX as the SEC code. items: type: string paymentTypeCode: type: string example: SINGLE description: Allows the consumer to include codes of significance to enable specialized handling of the entry. enum: - RECURRING - SINGLE - STANDING_AUTHORIZATION description: This object provides the list of request fields needed to originate an ACH credit/debit transfer. This section is driven by the paymentType. This object becomes mandatory for paymentType ACH. Debtor: type: object properties: name: type: string example: JOHN SMITH description: Originator or Debtor Account Holder's Name. maxLength: 140 postalAddress: $ref: '#/components/schemas/Address' CounterpartyAddressInformation: type: object required: - name properties: name: type: string example: JOHN SMITH description: Counteryparty account holder's name. maxLength: 140 id: type: string example: '187658' description: Id assigned to the creditor/counterparty. maxLength: 35 postalAddress: $ref: '#/components/schemas/Address' description: Counter Party Details. The address information becomes mandatory for RTP transactions with payment amount greater than or equal to $3000. Error_errorDetails: type: object required: - code - description properties: code: type: string example: REQ1001 description: This is the application error code returned by the API layer or the Implementation layer. A list of error codes will be provided in the user guide. maxLength: 7 description: type: string example: Request Id should not be more than 36 characters long. description: Description of the operation's status. It will have detailed error description in case of any error. maxLength: 250 messageDetail: type: string example: Invalid requestId description: Details about error including stack traces. This will not be populated for any handled error. maxLength: 250 AuthorizationHeader: type: string title: JWT Access Token CounterpartyInformation: type: object required: - counterpartyAccountType - counterpartyName properties: counterpartyAccountType: type: string example: SAVINGS description: 'Specifies the nature of the benificiary account. Values of Account type should be either CHECKING or SAVINGS. CHECKING - Current Account used to post credits. SAVINGS - Savings Account used to post credits.' enum: - CHECKING - SAVINGS counterpartyName: type: string example: JOHN SMITH description: Counterparty account holder's name. The maximum length of the counterparty name is 16 for transactions with CTX as the SEC code. The maximum length is 22 for other SEC codes. maxLength: 22 description: Counterparty is the crediting bank for RTP and ACH Credit; or debiting bank for ACH Debit. parameters: authorization: schema: $ref: '#/components/schemas/AuthorizationHeader' name: Authorization in: header description: OAuth 2.0 Authorization Bearer Token style: simple required: true example: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkhMMkQtYVdmaUxVS1BpUHQ5b2lweWNiYXo4WV9SUzI1NiIsInBpLmF0bSI6InphYXciLCJ0eXAiOiJKV1QifQ.eyJzY29wZSI6ImlyOnJlYWQiLCJjaWQiOiIyNzFmYTdkZDI3MDExMTA5Mzc4ZWE5MTU1YzA2ZTcxMSIsImlzcyI6Imh0dHBzOi8vcGYtZmFtLWRldi5pbnRlcm5hbC5jaXRpemVuc2JhbmsuY29tIiwiYXVkIjoiaW5mb3JtYXRpb25fcmVwb3J0aW5nIiwianRpIjoiOHpRMUJVSnlTT0xkWHZmQXJtb1pQSXVpZXBmdkF5WnJwdnc4NVlGY2dDVk1FbyIsInN1YmplY3QiOiJBQ01FLUFQSV9VQVRBTExfTU1HUFMiLCJjbmYiOnsieDV0IjoiOTlmN2Q3ZDQzOGMxZjViMWFiNzc4MDA1YmU3OGNkODY0NDU1YmYyYSJ9LCJleHAiOjE3NTczNTE2NzR9.c6y4ZcVxP8c8dZK8IwMPhVnKkrk7Kyf4h4cUo8GOPxrrR_AYq-59tcO9lzTkr4Kfa5-7q_HbxCV14wUnwz_N1JuehZ5N3wyuJ3wjc2jEfOnto8YwSEhY4qWbFm1TTdU8jqRZMp2KpvBpwa5BKNfjo3t0xAMqQ2til5-1JQHEZyint56OglKq13OzG265jW_RKOhmmmGuTlqDjiC4Mz2AQU-1VZY2i6LZTqKKTr7dvQVy5TKm9-akEkie8s-cXymaQ9Km54-PARdH8orezez8NuJc4LN550m46ulWJ2mNMDs4D9NnKQMr-stla2mQtovU__vNg3WDCvQ8Nrw1db5icA x-fapi-channel-id: schema: maxLength: 20 type: string name: x-fapi-channel-id in: header description: Identifier used to distinguish between different communication channels or data streams within a client system. style: simple required: false explode: false x-fapi-trace-id: schema: maxLength: 36 type: string name: x-fapi-trace-id in: header description: Unique request id for each request to make it traceable if needed. style: simple required: true securitySchemes: client-id: type: apiKey in: header name: X-IBM-Client-Id x-key-type: client_id OAuth2: type: oauth2 x-ibm-oauth-provider: externalpingfederate flows: clientCredentials: tokenUrl: https://pf-fam.internal.citizensbank.com/as/token.oauth2 scopes: ir:read: Access to read IR data externalDocs: description: API Documentation url: https://developer.citizensbank.com/content/qut/CitizensPaymentAPIUserGuide.pdf x-ibm-configuration: type: rest phase: realized enforced: true testable: true cors: enabled: true application-authentication: certificate: false x-ibm-endpoints: - url: https://apis.citizensbank.com/v3/payments