openapi: 3.2.0 info: title: Citi Authentication API version: 1.0.0 x-refined-note: - x-ibm-name differs across the merged source definitions and was not carried description: 'Operations tagged Authentication across 2 of this provider''s published API definitions: DigitalPaymentsCollectionsv12.yaml, ukraine_open_banking_authentication_api.yaml. Each path carries the servers of the definition it was published in.' servers: - url: https://tts.apib2b.citi.com/citiconnect/prod description: production gateway URL - url: https://tts.sandbox.apib2b.citi.com/citiconnect/sb description: sbox URL - url: https://tts.sit.apib2b.citi.com/citiconnect/uat description: uat URL - url: https://b2b.tts.icgservices.citi.com/citiconnect/openbanking/ukr/authenticationservices/v1 description: production gateway url - url: https://sanbox.tts.icgservices.citi.com/citiconnect/openbanking/ukr/authenticationservices/v1 description: sbox url tags: - name: Authentication paths: /digitalpayments/v1/payment-acceptance/authentication: post: tags: - Authentication summary: Create a authentication request description: This endpoint validates your request and synchronously responds with HTTP status 200 (OK) after successful validation. If validation fails, the endpoint synchronously responds with error (HTTP status 4XX / 5XX and any applicable reason code), indicating Citi couldn't accept your authentication creation request. operationId: authentication parameters: - $ref: '#/components/parameters/Client-Id' - $ref: '#/components/parameters/Idempotency-Id' - $ref: '#/components/parameters/Merchant-Token-Id' - $ref: '#/components/parameters/Post-Authentication-Operation' - $ref: '#/components/parameters/Post-Country-Code' requestBody: description: Create authentication request required: true content: application/json: schema: $ref: '#/components/schemas/Authentication-Request' examples: Authentication_Initiate_Request: $ref: '#/components/examples/Authentication-Request-Example' security: - clientCredentials: [] responses: '200': description: OK headers: apim-guid: schema: type: string description: Citi's unique identification for your request Merchant-Id: schema: type: string description: The unique identifier issued to you by your payment provider content: application/json: schema: $ref: '#/components/schemas/Authentication-Response' examples: Authentication_Initiate_Response: $ref: '#/components/examples/Authentication-Response-Example' '400': $ref: '#/components/responses/Bad-Request' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '405': $ref: '#/components/responses/Method-Not-Allowed' '409': $ref: '#/components/responses/Conflict' '415': $ref: '#/components/responses/Unsupported-Media-Type' '429': $ref: '#/components/responses/Rate-Limit-Exceeded' '500': $ref: '#/components/responses/Internal-Server-Error' '504': $ref: '#/components/responses/Gateway-Timeout' default: $ref: '#/components/responses/Internal-Server-Error' servers: - url: https://tts.apib2b.citi.com/citiconnect/prod description: production gateway URL - url: https://tts.sandbox.apib2b.citi.com/citiconnect/sb description: sbox URL - url: https://tts.sit.apib2b.citi.com/citiconnect/uat description: uat URL /digitalpayments/v1/payment-acceptance/authentication/{id}: patch: tags: - Authentication summary: Payer Authentication Request description: This endpoint validates your request and synchronously responds with HTTP status 202 (accepted) after successful validation. If validation fails, the endpoint synchronously responds with error (HTTP status 4XX / 5XX and any applicable reason code), indicating Citi couldn't accept your tokenization update request. operationId: updateAuthentication parameters: - $ref: '#/components/parameters/Idempotency-Id' - $ref: '#/components/parameters/Client-Id' - $ref: '#/components/parameters/Id' - $ref: '#/components/parameters/Merchant-Token-Id' - $ref: '#/components/parameters/Patch-Authentication-Operation' requestBody: description: Payer Authentication Request. required: true content: application/json: schema: $ref: '#/components/schemas/Authentication-Payer-Request' examples: Authentication_Payer_Request: $ref: '#/components/examples/Authentication-Payer-Request-Example' security: - clientCredentials: [] responses: '200': description: OK headers: apim-guid: schema: type: string description: Citi's unique identification for your request Merchant-Id: schema: type: string description: The unique identifier issued to you by your payment provider content: application/json: schema: $ref: '#/components/schemas/Authentication-Payer-Response' examples: Authentication_Payer_Response: $ref: '#/components/examples/Authentication-Payer-Response-Example' '400': $ref: '#/components/responses/Bad-Request' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/Not-Found' '405': $ref: '#/components/responses/Method-Not-Allowed' '409': $ref: '#/components/responses/Conflict' '415': $ref: '#/components/responses/Unsupported-Media-Type' '429': $ref: '#/components/responses/Rate-Limit-Exceeded' '500': $ref: '#/components/responses/Internal-Server-Error' '504': $ref: '#/components/responses/Gateway-Timeout' servers: - url: https://tts.apib2b.citi.com/citiconnect/prod description: production gateway URL - url: https://tts.sandbox.apib2b.citi.com/citiconnect/sb description: sbox URL - url: https://tts.sit.apib2b.citi.com/citiconnect/uat description: uat URL /oauth/token: post: tags: - Authentication summary: Request Access Token description: The OAuth token request authenticates your API message sent in either JSON formats and responds with an access token. In compliance with RFC 6749, requests to this endpoint MUST use the HTTP POST method and the request body MUST be URL-encoded (application/x-www-form-urlencoded). operationId: postOauthToken parameters: - name: Authorization in: header description: "The authorization will include \"Basic\" followed by a single space, followed by the Base64 encoded value of the APIm `client_id` & `secret key`. \n\nIn the above example, the `client_id` is *1234a5b6-cde7-8f90-12gh-345ij6789012* & secret key is *abcdefghijklmnop*. \n\nThe Base64 value after appending by adding “:” in between will be “MTIzNGE1YjYtY2RlNy04ZjkwLTEyZ2gtMzQ1aWo2Nzg5MDEyOmFiY2RlZmdoaWprbG1ub3A=”. \n" required: true schema: type: string format: byte requestBody: description: Request body for the OAuth Token. content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Request' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Response' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/error_message' example: httpMessage: Bad Request httpCode: '400' moreInformation: please provide valid value for request '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/error_message' example: httpMessage: UNAUTHORIZED httpCode: '401' moreInformation: The server could not verify that you are authorized to access the URL '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/error_message' example: httpMessage: NOT FOUND httpCode: '404' moreInformation: No resources match requested URI '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/error_message' example: httpMessage: METHOD NOT ALLOWED httpCode: '405' moreInformation: The method is not allowed for the requested URL '415': description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/error_message' example: httpMessage: UNSUPPORTED MEDIA TYPE httpCode: '415' moreInformation: Unsupported Content-Type application/octet-stream '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/error_message' example: httpMessage: Internal Server Error httpCode: '500' moreInformation: Internal Server Error deprecated: false security: - BasicAuthentication: [] x-codegen-request-body-name: body x-operation-id-source: normalized x-operation-id-original: authentication servers: - url: https://b2b.tts.icgservices.citi.com/citiconnect/openbanking/ukr/authenticationservices/v1 description: production gateway url - url: https://sanbox.tts.icgservices.citi.com/citiconnect/openbanking/ukr/authenticationservices/v1 description: sbox url components: examples: Method-Not-Allowed-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - issue: HTTP method is not supported action: Provide valid HTTP method code: CC00001 Unauthorized-Gateway-Error-Example: value: httpCode: '401' httpMessage: Unauthorized moreInformation: This server could not verify that you are authorized to access the URL Un-Supported-Media-Type-Gateway-Error-Example: value: httpCode: '415' httpMessage: Unsupported Media Type moreInformation: Unsupported Content-Type Authentication-Payer-Request-Example: value: transaction: id: CITI202402040111 authentication: sdk: application_id: '567890432' encrypted_data: tyrwewe public_key: 568877989dsdsds reference_number: rtyudsds transaction_id: wertyuiopa1234567890qwertyuiop order: currency_code: USD avs_action: NO_ACTION avs_response: ADDRESS_MATCH charge_type: SURCHARGE Not-Found-Gateway-Error-Example: value: httpCode: '404' httpMessage: Not Found moreInformation: No resources match requested URI Authentication-Response-Example: value: authentication: method_completed: true method_supported: SUPPORTED requestor_id: REQ123456 requestor_name: SWDFGTHJ order: currency_code: USD status: AUTHORIZED total_auth_amount: 100 total_captured_amount: 0 total_refunded_amount: 0 id: TX0250117002 creation_time: '2025-01-17T13:10:23.973Z' update_time: '2025-01-17T13:10:24.351Z' transaction: id: ORD_20250117_002 amount: 100 currency_code: USD status: SUCCESS description: APPROVED creation_date_time: '2025-01-17T13:10:24.019Z' update_time: '2025-01-17T13:10:24.351Z' method: CARD: number: 401200xxxxxx0026 expiry_month: '1' expiry_year: '39' fundingMethod: CREDIT Bad-Request-Gateway-Error-Example: value: httpCode: '400' httpMessage: Bad Request moreInformation: please provide valid value for property emailAddress Not-Found-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627702 error_details: - issue: Resource that you are searching is not found action: Please use valid resource details code: CC00006 Unauthorized-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - issue: User not authorized for this functionality action: please use valid credentials to access this functionality code: CC00007 Authentication-Request-Example: value: authentication: channel: MERCHANT_REQUESTED order: id: '123456789' currency_code: USD method: type: CARD id_type: CARD_NUMBER card: expiry_month: 09 expiry_year: '25' transaction: id: TRANS1234567 currency_code: USD country_code: US Method-Not-Allowed-Gateway-Error-Example: value: httpCode: '405' httpMessage: Method Not Allowed moreInformation: The method is not allowed for the requested URL Unsupported-Media-Type-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - issue: Media type not supported action: please use valid content-type in header code: CC00002 Internal-Server-Gateway-Error-Example: value: httpCode: '500' httpMessage: Internal Server Error moreInformation: unable to serve your request at this moment Idempotency-Id-Conflict-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - issue: Idempotency-Id provided is currently being used in another request action: please do not repeat the same request again code: VC00016 Authentication-Payer-Response-Example: value: transaction: id: CITI202402040111 authentication: sdk: application_id: '567890432' encrypted_data: tyrwewe public_key: 568877989dsdsds reference_number: rtyudsds transaction_id: wertyuiopa1234567890qwertyuiop order: currency_code: USD avs_action: NO_ACTION avs_response: ADDRESS_MATCH charge_type: SURCHARGE Gateway-Timeout-Gateway-Error-Example: value: httpCode: '504' httpMessage: GATEWAY_TIMEOUT moreInformation: 'Response took longer than timeout: PT50S' Rate-Limit-Exceeded-Gateway-Error-Example: value: httpCode: '429' httpMessage: Too Many Requests moreInformation: Rate Limit exceeded Bad-Request-Example: value: ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab error_details: - issue: property method.type is mandatory and it cannot be empty action: please provide valid value for property method.type code: VC00010 Internal-Server-Error-Example: value: ref_id: ec689822-9864-4c4d-9d68-222467627902 error_details: - issue: unable to serve your request at this moment action: Please refer to documentation provided or contact support team code: CC00004 schemas: Device-Specific-Response: title: Device description: Device Specific Response properties: number: description: The payer's account number associated with a digital payment method. example: PA123456789 maximum: 19 minimum: 9 type: number title: number expiry_month: description: Two-digit month in which the device specific expires. example: '01' type: string pattern: ^(0?[1-9]|1[0-2])$ title: expiry_month expiry_year: description: Year from the expiry date of the device specific account number. type: string pattern: ^[0-9]{2,2}$ example: '25' title: expiry_year Authentication-Transaction-Request: title: Transaction required: - id properties: additional_info: type: array items: $ref: '#/components/schemas/Additional-Info' id: description: Unique Transaction identification provided by the merchant during transaction creation example: pay02052023456r maxLength: 128 minLength: 1 type: string title: id Authentication-Transaction: title: ' Authentication Transaction' required: - id - currency_code - country_code properties: currency_code: description: "ISO 4217 Currency Code for instance USD/GBP/EUR \n- transaction.currency_code parameter is mandatory for all transaction type creation" enum: - USD example: USD type: string title: currency_code reference: description: Value provided by the merchant for internal tracking/referencing. example: REPAY maxLength: 250 minLength: 1 type: string title: reference country_code: description: The transaction country enum: - US example: US type: string title: country_code id: description: Unique Transaction identification provided by the merchant during transaction creation example: pay02052023456r maxLength: 128 minLength: 1 type: string title: id type: object Sdk: title: sdk description: sdk payer authentication properties: application_id: description: A unique identifier for the app on the payer's device (EMVCo fieldsdkAppID). example: PA123456789 maxLength: 36 minLength: 36 type: string title: application_id encrypted_data: description: Information about the payer's device collected and encrypted by the SDK (EMVCo fieldsdkEncData). example: PA123456789 maxLength: 646000 minLength: 1 type: string title: encrypted_data public_key: description: A public key generated by the SDK for a secure session (EMVCo fieldsdkEphemPubKey). example: PA123456789 maxLength: 256 minLength: 1 type: string title: public_key device_interface: description: The UI formats the payer's device supports for challenges (EMVCosdkInterface). example: PA123456789 maxLength: 256 minLength: 1 type: string title: device_interface reference_number: description: Identifier of the vendor and version of the 3DS SDK assigned by EMVCo (EMVCosdkReferenceNumber). example: PA123456789 maxLength: 32 minLength: 1 type: string title: reference_number time_out: description: 'The duration (in seconds) available to the payer to authenticate (Default: 900, range 300-900).' example: PA123456789 maximum: 900 minimum: 300 type: number title: time_out transaction_id: description: A unique identifier for the app on the payer's device (EMVCo fieldsdkAppID). example: PA123456789 maxLength: 36 minLength: 36 type: string title: transaction_id ui_type: type: array items: type: string description: The UI types the SDK supports for displaying challenges within the app (EMVCosdkUiType). title: ui_type Name: title: name type: object properties: first_name: description: "The payer's first name. \n - For Brazil QR and UK PAYBYBANK creation, name.first_name parameter is mandatory. \n- For US RFP this parameter is mandatory and full name has to be passed in this parameter \n- For US ACH Direct Debit, cutomer.name.first_name parameter is optional with max length 22" example: JOHN maxLength: 140 minLength: 1 type: string title: first_name last_name: description: "The payer's last name. \n - For Brazil QR and UK PAYBYBANK creation, name.last_name parameter is mandatory." example: PETER maxLength: 50 minLength: 1 type: string title: last_name company_name: description: The name of the company associated with this address. example: COMPANY NAME maxLength: 100 minLength: 1 type: string title: company_name Authentication-Customer-Device: title: Authentication Customer Device description: Customer-Device. properties: ani: description: The telephone number captured by ANI (Automatic Number Identification) when the customer calls to place the order. example: M1234567890 maxLength: 10 minLength: 1 type: string title: ani ani_call_type: description: The 2 digit ANI information identifier provided by the telephone company to indicate the call type, for example, cellular (61-63), toll free (24,25), etc. example: '63' maxLength: 2 minLength: 1 type: string title: ani_call_type browser: description: The User-Agent header of the browser the customer used to place the order. example: '63' maxLength: 2048 minLength: 1 type: string title: browser browser_accept_window_size: description: Dimensions of the 3DS challenge window in pixels (e.g., 250x400). enum: - 250_X_400 - 390_X_400 - 500_X_600 - 600_X_400 - FULL_SCREEN example: FULL_SCREEN type: string title: browser_accept_window_size fingerprint: description: Information collected about a remote computing device for the purpose of providing a unique identifier for the device. example: '63' maxLength: 4000 minLength: 1 type: string title: fingerprint hostname: description: The name of the server to which the customer is connected. example: '63' maxLength: 60 minLength: 1 type: string title: hostname ip_address: description: The name of the server to which the customer is connected. example: '63' maxLength: 45 minLength: 7 type: string title: ip_address mobile_phone_model: description: The name of the server to which the customer is connected. example: '63' maxLength: 255 minLength: 1 type: string title: mobile_phone_model browser_accept_headers: description: The content of the Accept request-header field sent from the browser. example: '63' maxLength: 2048 minLength: 1 type: string title: browser_accept_headers browser_color_depth: description: The bit depth of the color palette for images (1-48 bits per pixel). example: '63' maximum: 48 minimum: 1 type: number title: browser_accept_headers browser_java_enabled: description: Indicates if the browser supports Java (true/false). type: boolean example: false title: browser_java_enabled browser_java_script_enabled: description: Indicates if the browser supports JavaScript (true/false). type: boolean example: false title: browser_java_script_enabled browser_language: description: The language supported by the browser as defined in IETF BCP47. example: '63' maxLength: 8 minLength: 1 type: string title: browser_language browser_screen_height: description: The total height of the browser screen in pixels (1-999999). example: '63' maximum: 999999 minimum: 1 type: number title: browser_screen_height browser_screen_width: description: The total width of the browser screen in pixels (1-999999). example: '63' maximum: 999999 minimum: 1 type: number title: browser_screen_width browser_timezone: type: string description: Time difference between UTC time and local time, in minutes (-840 to +840). pattern: ^([-+]?(?:[1-9][0-9]?|[1-7][0-9]{2}|8[0-3][0-9]|840)|0)$ example: '+840' title: browser_timezone Authentication-Payer-Card: title: Authentication Payer Card description: Card informations properties: number: description: The customer’s payment card number, also known as the Primary Account Number (PAN). type: string minLength: 9 maxLength: 23 example: '4012000033330026' title: number expiry_month: description: Two-digit month in which the payment card expires. example: '01' type: string pattern: ^(0?[1-9]|1[0-2])$ title: expiry_month expiry_year: description: Two-digit year in which the payment card expires. type: string pattern: ^[0-9]{2,2}$ example: '25' title: expiry_year cvv: description: Card verification code (CVV/CVC/etc.). example: '123' maxLength: 4 minLength: 3 type: string title: cvv device_payment: $ref: '#/components/schemas/Authentication-Device-Payment' Authentication-Payer-Method-Response: type: object title: Authentication Payer Method Response required: - type properties: card: $ref: '#/components/schemas/Authentication-Payer-Card-Response' holder_name: $ref: '#/components/schemas/Holder-Name' type: description: "Method specified by the customer for the transaction \n- Provide CARD for CARD transactions" type: string enum: - CARD - GOOGLEPAY - APPLEPAY example: CARD title: type token_id: description: Session identification number type: string minLength: 1 maxLength: 50 example: SES1234567890123456789012345678 title: token_id token_type: description: Token type. enum: - ALT_TOKEN - NETWORK_TOKEN - ISSUER_TOKEN - CITI_TOKEN example: ISSUER_TOKEN type: string title: token_type Authentication-Address: type: object description: Authentication Address title: Authentication Address properties: city: maxLength: 100 minLength: 1 type: string description: City. example: Abis Brasil title: city postal_code: maxLength: 16 minLength: 1 type: string description: Postal code. example: 69935-000 title: postal_code state: maxLength: 50 minLength: 1 type: string description: State. example: san francisco title: state country_code: type: string pattern: ^[A-Z]{2,2}$ description: Country. example: BR title: country_code province_code: description: The three character ISO 3166-2 country subdivision code for the state or province of the address example: IN maxLength: 3 minLength: 1 type: string title: province_code lines: type: array minItems: 1 maxItems: 7 items: $ref: '#/components/schemas/Lines' title: lines Lines: type: string maxLength: 100 minLength: 1 description: "Address Lines \n- For US RFP only one(1) line of 70 characters is allowed \n- For US ACH Direct Debit payment, unstructured address_lines is mandatory when structured address parameters are not provided and allowed three instances with each line max length of 35 characters. Address Line 1 should have Building info followed by asterik, Street Address ends with a single backslash. Address Line2 should have City followed by asterik, State ends with a single backslash. Address Line 3 should have Zip Code followed by asterik, Country Code ends with a single backslash. For example Zip code*US\\." title: lines Authentication-Card: title: card description: Card informations properties: number: description: The customer’s payment card number, also known as the Primary Account Number (PAN). type: string minLength: 9 maxLength: 23 example: '4012000033330026' title: number expiry_month: description: Two-digit month in which the payment card expires. example: '01' type: string pattern: ^(0?[1-9]|1[0-2])$ title: expiry_month expiry_year: description: Two-digit year in which the payment card expires. type: string pattern: ^[0-9]{2,2}$ example: '25' title: expiry_year device_payment: $ref: '#/components/schemas/Authentication-Device-Payment' Authentication-Payer-Initiate-Request: title: ' Payer Authentication Request' required: - channel properties: sdk: $ref: '#/components/schemas/Sdk' challenge_preference: description: Indicates if you want the payer to be presented with an authentication challenge (Default:NO_PREFERENCE). enum: - CHALLENGE_MANDATED - CHALLENGE_PREFERRED - NO_CHALLENGE - NO_PREFERENCE - REQUEST_TRUSTED_MERCHANT_LISTING example: REQUEST_TRUSTED_MERCHANT_LISTING type: string title: challenge_preference product_info: description: Description of the goods being purchased, displayed on the authentication UI. example: CART123456 maxLength: 30 minLength: 1 type: string title: product_info payment_exemption: description: Indicates why this payment qualifies for an SCA exemption. enum: - AUTO - LOW_RISK - LOW_VALUE_PAYMENT - TRUSTED_MERCHANT - MERCHANT_INITIATED_TRANSACTION - RECURRING_PAYMENT - SECURE_CORPORATE_PAYMENT example: TRUSTED_MERCHANT type: string title: payment_exemption redirect_url: type: string maxLength: 500 description: The URL to which you want to redirect the payer after completing the payer authentication process.This will be a URL on your website, with the URL encoded as defined in RFC3986. This means special characters such spaces, hyphens, etc must be encoded. example: https://greenzone-api.uat.nam.nsroot.net/api/notification title: redirect_url Authentication-Payer-Request: type: object title: Authentication-Payer-Request required: - order - transaction properties: authentication: $ref: '#/components/schemas/Authentication-Payer-Initiate-Request' customer: $ref: '#/components/schemas/Customer-Authentication-Request' method: $ref: '#/components/schemas/Authentication-Payer-Method' transaction: $ref: '#/components/schemas/Authentication-Transaction-Request' order: $ref: '#/components/schemas/Authentication-Payer-Order' mandate: $ref: '#/components/schemas/Authentication-Mandate' shipping: $ref: '#/components/schemas/Authentication-Payer-Shipping' additionalProperties: false description: Payment Request Error-Response: type: object title: Error Response properties: ref_id: type: string maxLength: 60 description: Unique ID for the Transaction title: ref_id error_details: type: array uniqueItems: true items: $ref: '#/components/schemas/Error-Detail' Authentication-Payer-Order-Response: title: Authentication Payer Order required: - id - amount - currency_code - creation_date_time - update_time - charge_amount - charge_type - total_auth_amount - total_captured_amount - total_refunded_amount - avs_action - avs_response properties: id: description: A unique identifier for this order. example: ORD123456 maxLength: 40 minLength: 1 type: string title: id amount: description: The total amount for the order. This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.The value of this parameter in the response is zero if payer funds are not transferred. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: amount authentication_status: description: Indicates the result of payer authentication. enum: - AUTHENTICATION_ATTEMPTED - AUTHENTICATION_AVAILABLE - AUTHENTICATION_EXEMPT - AUTHENTICATION_FAILED - AUTHENTICATION_NOT_IN_EFFECT - AUTHENTICATION_NOT_SUPPORTED - AUTHENTICATION_PENDING - AUTHENTICATION_REJECTED - AUTHENTICATION_REQUIRED - AUTHENTICATION_SUCCESSFUL - AUTHENTICATION_UNAVAILABLE example: AUTHENTICATION_EXEMPT type: string title: authentication_status creation_date_time: type: string format: date-time description: The date and time the gateway considers the order to have been created. GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) example: '2022-09-13T08:23:49.114Z' title: creation_date_time currency_code: description: The currency of the order expressed as an ISO 4217 alpha code, e.g. USD. enum: - USD example: USD type: string title: currency_code charge_amount: description: The amount of the additional fee that you are charging the payer. example: '20.0' maximum: 1000000000000000000 minimum: 0.01 type: number title: charge_amount update_time: type: string format: date-time description: The date and time the gateway considers the order to have last been updated. GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) example: '2022-09-13T08:23:49.114Z' title: update_time mcc: description: The invoice number you issued for this order example: '1234' maxLength: 4 minLength: 4 type: string title: mcc charge_type: description: The type of the additional fee that you are charging the payer. enum: - SURCHARGE example: SURCHARGE type: string title: charge_type net_amount: description: The total item amount for the order. example: 150 maximum: 1000000000000000000 minimum: 0.01 type: number title: net_amount reference: description: An optional identifier for the order (e.g., shopping cart or invoice number). example: ORD123456 maxLength: 200 minLength: 1 type: string title: reference shipping_and_handling_amount: description: The total shipping and handling amount for the order, including taxes on the shipping and/or handling example: 20 maximum: 1000000000000000000 minimum: 0.01 type: number title: shipping_and_handling_amount shipping_and_handling_tax_amount: description: The tax amount levied on the shipping and handling amount for the order. example: 20 maximum: 1000000000000000000 minimum: 0.01 type: number title: shipping_and_handling_tax_amount shipping_and_handling_tax_rate: description: The tax rate applied to the shipping and handling amount for the order to determine the shipping and handling tax amount. example: 20 maximum: 1000000000000000000 minimum: 0.01 type: number title: shipping_and_handling_tax_rate discount_amount: description: The total amount of the discount you have applied to the order example: 300 maximum: 1000000000000000000 minimum: 0.01 type: number title: discount_amount tax_registration_id: description: Your tax registration identifier provided by the Federal/National tax authority (for example, federal tax identification number, ABN).If you are a Canadian merchant, use this parameter to provide your Tax Registration ID for paying Harmonized Sales Tax (HST) or Goods and Services Tax (GST) collected by the Canada Revenue Agency. example: 300 maxLength: 30 minLength: 1 type: string title: tax_registration_id total_auth_amount: description: The amount that has been successfully authorized for this order. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: total_auth_amount total_captured_amount: description: The amount that has been successfully captured for this order. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: total_captured_amount total_refunded_amount: description: The amount that has been successfully captured for this order. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: total_refunded_amount certainty: description: Indicates if you expect to capture the full order amount for which you are requesting authorization.If you do not provide a value for order.certainty the default configured for you by your payment service provider will be used. The value provided in the response shows the value the gateway sent to the acquirer. enum: - ESTIMATED - FINAL example: FINAL type: string title: certainty date: description: The date the payer placed the order. example: '1988-02-15' format: date type: string title: date description: description: Short textual description of the contents of the order. example: LAPTOP PURCHASE maxLength: 127 minLength: 1 type: string title: description discount_code: description: The code you use to identify the reason for the discount. example: DISC001 maxLength: 40 minLength: 1 type: string title: discount_code discount_description: description: A description of your reason for the discount. example: CARD DISCOUNT maxLength: 127 minLength: 1 type: string title: discount_description duty_amount: description: The duty amount (also known as customs tax, tariff or dues) for the order. example: 150 maximum: 1000000000000000000 minimum: 0.01 type: number title: duty_amount entity: description: Your identifier for the part of your organization that is responsible for the order.You might provide this data when you want to track the accountability for the order. For example, store number, sales region, branch, or profit center. example: INDENTITY1 maxLength: 40 minLength: 1 type: string title: entity status: description: The current progression of this order through the payment process. enum: - AUTHENTICATED - AUTHENTICATION_INITIATED - AUTHENTICATION_NOT_NEEDED - AUTHENTICATION_UNSUCCESSFUL - AUTHORIZED - CANCELLED - CAPTURED - CHARGEBACK_PROCESSED - DISBURSED - DISPUTED - EXCESSIVELY_REFUNDED - FAILED - FUNDING - INITIATED - PARTIALLY_CAPTURED - PARTIALLY_REFUNDED - REFUNDE - REFUND_REQUESTED - VERIFIED example: VERIFIED type: string title: status tax_amount: description: The total tax amount for the order. If you do not provide this value but provide line item data, then this amount is calculated as the sum of the item.quantity times the item.unitTaxAmount for all the line items (total tax amount).If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount. example: 150 maximum: 1000000000000000000 minimum: 0.01 type: number title: tax_amount retailer_location: description: Provide information about the location of the retailers for goods or services included in this order. Where a retailer is located in a country different from your country, they are considered a foreign retailer, otherwise they are considered a domestic retailer. enum: - DOMESTIC_ONLY - FOREIGN_AND_DOMESTIC - FOREIGN_ONLY example: FOREIGN_ONLY type: string title: retailer_location avs_action: description: The action to be performed for the Address Verification Service (AVS) Response Code. enum: - NO_ACTION - REJECT - REVIEW example: REVIEW type: string title: avs_action avs_response: description: The Address Verification Service (AVS) Response Code for which you are defining the rule. enum: - ADDRESS_MATCH - ADDRESS_ZIP_MATCH - NAME_ADDRESS_MATCH - NAME_MATCH - NAME_ZIP_MATCH - NOT_AVAILABLE - NOT_REQUESTED - NOT_VERIFIED - NO_MATCH - SERVICE_NOT_AVAILABLE_RETRY - SERVICE_NOT_SUPPORTED - ZIP_MATCH example: ADDRESS_MATCH type: string title: avs_response invoice_number: description: The invoice number you issued for this order example: INV123456 maxLength: 25 minLength: 1 type: string title: invoice_number type: object Authentication-Order: title: Authentication Order required: - currency_code - id properties: id: description: A unique identifier for this order to distinguish it from any other order you create. example: OR123456789 maxLength: 40 minLength: 1 type: string title: id currency_code: description: The currency of the order expressed as an ISO 4217 alpha code, e.g. USD. enum: - USD example: USD type: string title: currency_code reference: description: An optional identifier for the order For example, a shopping cart number, an order number, or an invoice number. example: CART123456 maxLength: 250 minLength: 1 type: string title: reference mcc: description: The invoice number you issued for this order example: '1234' maxLength: 4 minLength: 4 type: string title: mcc type: object Authentication-Payer-Method: type: object title: Authentication Payer Method properties: card: $ref: '#/components/schemas/Authentication-Payer-Card' holder_name: $ref: '#/components/schemas/Holder-Name' session_id: description: Session identification number type: string minLength: 36 maxLength: 37 example: SES1234567890123456789012345678 title: session_id type: description: "Method specified by the customer for the transaction \n- Provide CARD for CARD transactions" type: string enum: - CARD - GOOGLEPAY - APPLEPAY example: CARD title: type token_id: description: Token_number. example: PA123456789 maxLength: 50 minLength: 1 type: string title: token_number token_type: description: Token type. enum: - ALT_TOKEN - NETWORK_TOKEN - ISSUER_TOKEN - CITI_TOKEN example: ISSUER_TOKEN type: string title: token_type Authentication-Customer-Payer-Response: title: Authentication Customer Payer Response description: Authentication-Customer-Payer-Response properties: action: description: Behaviour relating to the association between the customer account and their card. enum: - AUTHENTICATION - REGISTRATION example: REGISTRATION type: string title: action status: description: Status of the card association functionality. enum: - FAILED - NOT_SUPPORTED - SUCCESSFUL - SUPPORTED example: FAILED type: string title: status method: description: The method used to authenticate the payer. enum: - CUSTOMER_ACCOUNT_LOGIN - FEDERATED_IDENTITY_LOGIN - FIDO_AUTHENTICATION - ISSUER_ACCOUNT_LOGIN - NONE - THIRD_PARTY_ACCOUNT_LOGIN example: NONE type: string title: method time: type: string format: date-time description: Date and time the payer was authenticated (YYYY-MM-DDThh:mm:ss.SSSZ). example: '2022-09-13T08:23:49.114Z' title: update_time Authentication-Customer-History-Payer-Request: title: Authentication Customer History Payer Request description: Authentication-Customer-Payer-Request properties: attempts: description: Number of attempts to add/change a card in the last 24 hours (0-99). example: '99' maximum: 99 minimum: 1 type: number title: attempts annual_activity: description: Number of transactions (successful/abandoned) in the last year (0-999). example: '99' maximum: 999 minimum: 1 type: number title: annual_activity creation_date: type: string format: date description: The date the payer created an account (yyyy-mm-dd). example: '2022-09-13' title: creation_date issuer_acs_id: description: The unique transaction identifier used by the issuer's ACS. example: PA123456789 maxLength: 36 minLength: 1 type: string title: issuer_acs_id authentication_token: description: The authentication token obtained from a previous request. example: PA123456789 maxLength: 32 minLength: 28 type: string title: authentication_token directory_server_id: description: A unique transaction identifier assigned by the scheme Directory Server. example: PA123456789 maxLength: 50 minLength: 1 type: string title: directory_server_id authentication_time: type: string format: date-time description: The date and time the payer was authenticated for the prior transaction (YYYY-MM-DDThh:mm:ss.SSSZ). example: '2022-09-13T08:23:49.114Z' title: authentication_time authentication_id: description: The gateway transaction ID of a previous Authenticate Payer request to reuse authentication data. example: PA123456789 maxLength: 50 minLength: 1 type: string title: authentication_id authentication_type: description: The method used to authenticate the payer for a prior transaction. enum: - 3DS_FRICTIONLESS - 3DS_CHALLENGE - ADDRESS_VERIFICATION - OTHER example: OTHER type: string title: authentication_type last_updated_date: type: string format: date description: The date the payer's account with you was last updated (yyyy-mm-dd). example: '2022-09-13' title: last_updated_date password_last_changed_date: type: string format: date description: The date the payer's account with you was last updated (yyyy-mm-dd). example: '2022-09-13' title: password_last_changed_date transaction_activity: description: Number of transactions (successful/abandoned) in the last 24 hours (0-99). example: '99' maximum: 99 minimum: 1 type: number title: transaction_activity shipping_address_date: type: string format: date description: The date you first shipped goods to the provided shipping address (yyyy-mm-dd). example: '2022-09-13' title: shipping_address_date suspicious_activity: description: Have you experienced suspicious activity on the account in the past (true/false). type: boolean example: false title: suspicious_activity Additional-Info: title: Additional-Info /n- For Brazil and CARD transactions allowed maxmium of 50 lines /n- For India CARD transactions allowed maxmium of 10 lines properties: name: maxLength: 100 minLength: 1 type: string description: Specifies a character string with a maximum length of 50 characters. If transaction.Additional-Info.name is provided by merchant then transaction.Additional-Info.value is mandatory. example: request_to_payer title: name value: maxLength: 500 minLength: 1 type: string description: Specifies a character string with a maximum length of 200 characters. if transaction.Additional-Info.value is provided by merchant then transaction.Additional-Info.name is mandatory. example: this is for purchase order 4567 title: value Gateway-Error-Response: type: object title: GatewayErrorResponse properties: httpCode: type: string maxLength: 3 description: Numeric HTTP Staus code title: httpCode httpMessage: type: string maxLength: 128 description: HTTP error message title: httpMessage moreInformation: type: string maxLength: 128 description: HTTP error message title: httpMessage Shipping-Address: title: Shipping-Address type: object description: Address properties: lines: type: array maxItems: 7 items: $ref: '#/components/schemas/Lines' title: lines street_name: maxLength: 70 minLength: 1 type: string description: Customer Street Name. example: Federal Street title: street_name city: maxLength: 100 minLength: 1 type: string description: Customer city. example: Abis Brasil title: city postal_code: maxLength: 16 minLength: 1 type: string description: Customer postal code. example: 69935-000 title: postal_code state: maxLength: 50 minLength: 1 type: string description: Customer state. example: san francisco title: state country_code: type: string pattern: ^[A-Z]{2,2}$ description: Customer country. example: US title: country_code Authentication-Device-Payment-Response: title: Authentication Device Payment Response type: object description: Device properties: cryptogram_format: description: The format of the cryptogram provided for the digital payment. enum: - 3DSECURE - EMV example: EMV type: string title: cryptogram_format Authentication-Payer-Card-Response: title: Authentication Payer Card Response description: Card informations properties: account_type: description: Savings/checking option for some cards (e.g., Maestro). enum: - CHECKING - SAVINGS example: SAVINGS type: string title: account_type brand: description: The brand name used to describe the card that is recognized and accepted globally. For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see card.localBrand).You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances. enum: - AMEX - CHINA_UNIONPA - DINERS_CLUB - DISCOVER - JCB - LOCAL_BRAND_ONLY - MAESTRO - MASTERCARD - RUPAY - UATP - UNKNOWN - VISA example: AMEX type: string title: brand scheme: description: The organization that owns a card brand and defines operating regulations for its use. The card scheme also controls authorization and settlement of card transactions among issuers and acquirers. enum: - AMEX - CHINA_UNIONPA - DINERS_CLUB - DISCOVER - JCB - LOCAL_BRAND_ONLY - MAESTRO - MASTERCARD - RUPAY - UATP - UNKNOWN - VISA example: AMEX type: string title: scheme number: description: The customer’s payment card number, also known as the Primary Account Number (PAN). example: '4321123456789345' maxLength: 23 minLength: 9 type: string title: number issuer: description: The issuer of the card, if known. example: '123' maxLength: 255 minLength: 1 type: string title: cvv funding_method: description: The method used by the payer to provide the funds (Charge, Credit, Debit). enum: - CHARGE - CREDIT - DEBIT - UNKNOWN example: CHARGE type: string title: funding_method expiry_month: description: Two-digit month in which the payment card expires. example: '01' type: string pattern: ^(0?[1-9]|1[0-2])$ title: expiry_month expiry_year: description: Two-digit year in which the payment card expires. type: string pattern: ^[0-9]{2,2}$ example: '25' title: expiry_year encryption: description: The encryption framework used for the payment details received by the gateway. enum: - DEVICE - DIGITAL_WALLET - DUKPT example: DEVICE type: string title: encryption device_payment: $ref: '#/components/schemas/Authentication-Device-Payment-Response' device_specific: $ref: '#/components/schemas/Device-Specific-Response' Authentication-Customer-Payer-Request: title: Authentication Customer Payer Request description: Authentication-Customer-Payer-Request properties: action: description: Behaviour relating to the association between the customer account and their card. enum: - AUTHENTICATION - REGISTRATION example: REGISTRATION type: string title: action data: description: Data returned by an authentication service used when the customer logged in (e.g., FIDO token). example: PA123456789 maxLength: 20000 minLength: 1 type: string title: data method: description: The method used to authenticate the payer. enum: - CUSTOMER_ACCOUNT_LOGIN - FEDERATED_IDENTITY_LOGIN - FIDO_AUTHENTICATION - ISSUER_ACCOUNT_LOGIN - NONE - THIRD_PARTY_ACCOUNT_LOGIN example: NONE type: string title: method time: type: string format: date-time description: Date and time the payer was authenticated (YYYY-MM-DDThh:mm:ss.SSSZ). example: '2022-09-13T08:23:49.114Z' title: update_time Customer-Authentication-Request: title: Customer Authentication Request properties: account: title: customer account authentication request description: Account Details properties: number: description: Your identifier for the payer's account with you (immutable ID). example: 1234abcjki maxLength: 40 minLength: 1 type: string title: number authentication: $ref: '#/components/schemas/Authentication-Customer-Payer-Request' history: $ref: '#/components/schemas/Authentication-Customer-History-Payer-Request' number: description: Your identifier for the payer's account with you (immutable ID). example: 1234abcjki maxLength: 40 minLength: 1 type: string title: number name: $ref: '#/components/schemas/Name' tax_id: description: Customer's payer identification (e.g., email address) example: 234.453.678-21 maxLength: 100 minLength: 1 type: string title: tax_id email: description: Customer email example: customer.raj2024@gmail.com type: string pattern: '[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,4}$' title: email phone: description: Customer phone. example: '+919962125789' pattern: \+[0-9]{1,3}[-\ ][0-9()+\-]{1,30} type: string title: phone mobile_phone: description: Customer phone. example: '+919962125789' pattern: \+[0-9]{1,3}[-\ ][0-9()+\-]{1,30} type: string title: mobile_phone device: $ref: '#/components/schemas/Authentication-Customer-Device' address: $ref: '#/components/schemas/Authentication-Address' Authentication-Request: type: object title: Authentication Request required: - authentication - order - method - transaction properties: authentication: $ref: '#/components/schemas/Initiate-Authentication' method: $ref: '#/components/schemas/Authentication-Method' transaction: $ref: '#/components/schemas/Authentication-Transaction' order: $ref: '#/components/schemas/Authentication-Order' additionalProperties: false description: Authentication Request Authentication-Card-Response: title: Authentication Card Response description: Card informations properties: number: description: The customer’s payment card number, also known as the Primary Account Number (PAN). example: '4321123456789345' maximum: 23 minimum: 9 type: string title: number issuer: description: The issuer of the card, if known. example: VISA maximum: 255 minimum: 1 type: string title: issuer expiry_month: description: Two-digit month in which the payment card expires. example: '01' type: string pattern: ^(0?[1-9]|1[0-2])$ title: expiry_month expiry_year: description: Two-digit year in which the payment card expires. type: string pattern: ^[0-9]{2,2}$ example: '25' title: expiry_year encryption: description: The encryption framework used for the payment details received by the gateway. enum: - DEVICE - DIGITAL_WALLET - DUKPT example: DEVICE type: string title: encryption funding_method: description: The method used by the payer to provide the funds (Charge, Credit, Debit). enum: - CHARGE - CREDIT - DEBIT - UNKNOWN example: CHARGE type: string title: funding_method brand: description: The brand name used to describe the card that is recognized and accepted globally. For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see card.localBrand).You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances. enum: - AMEX - CHINA_UNIONPA - DINERS_CLUB - DISCOVER - JCB - LOCAL_BRAND_ONLY - MAESTRO - MASTERCARD - RUPAY - UATP - UNKNOWN - VISA example: AMEX type: string title: brand scheme: description: The organization that owns a card brand and defines operating regulations for its use. The card scheme also controls authorization and settlement of card transactions among issuers and acquirers. enum: - AMEX - CHINA_UNIONPA - DINERS_CLUB - DISCOVER - JCB - LOCAL_BRAND_ONLY - MAESTRO - MASTERCARD - RUPAY - UATP - UNKNOWN - VISA example: AMEX type: string title: scheme device_payment: $ref: '#/components/schemas/Authentication-Device-Payment-Response' device_specific: $ref: '#/components/schemas/Device-Specific-Response' Authentication-Method: type: object title: Authentication Method required: - type properties: type: description: "Method specified by the customer for the transaction \n- Provide CARD for CARD transactions" type: string enum: - CARD - GOOGLEPAY - APPLEPAY example: CARD title: type card: $ref: '#/components/schemas/Authentication-Card' token_id: description: Token_number. example: PA123456789 maxLength: 50 minLength: 1 type: string title: token_number token_type: description: Token type. enum: - ALT_TOKEN - NETWORK_TOKEN - ISSUER_TOKEN - CITI_TOKEN example: ISSUER_TOKEN type: string title: token_type session_id: description: Session identification number type: string minLength: 36 maxLength: 37 example: SES1234567890123456789012345678 title: session_id Authentication-Mandate: title: Mandate properties: amount_variability: description: Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments. The parameter must be provided for recurring payment agreements. enum: - FIXED - VARIABLE example: VARIABLE type: string title: amount_variability custom_data: description: Additional information requested for the agreement which cannot be passed using other available data parameters. This parameter must not contain sensitive data. example: '7788' maxLength: 2048 minLength: 1 type: string title: custom_data expiry_date: description: Date at which your agreement with the payer to process payments expires. example: '2024-02-15' format: date type: string title: expiry_date id: description: "Your identifier for the agreement you have with the payer to process payments.When you collect cards from your payers and store them for later use, you must provide an agreement ID when you use the stored values for: Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions. Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments. Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking. When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type. \n- For Brazil PIX Initiation, this parameter is mandatory with max length 29 in format RR33479023yyyyMMddBRkkkkkkkkk and this should be same id received as part of push notification while creating the mandate" example: RR123456789 maxLength: 100 minLength: 1 type: string title: id maximum_amount: description: The maximum amount for a single payment in the series as agreed with the payer under your agreement with them. The amount must be provided in the currency of the order. example: '200' maxLength: 14 minLength: 1 type: string title: maximum_amount minimum_amount: description: The minimum amount for a single payment in the series as agreed with the payer under your agreement with them. The amount must be provided in the currency of the order. example: '200' maxLength: 14 minLength: 1 type: string title: minimum_amount minimum_days: description: The minimum number of days between payments agreed with the payer under your agreement with them. example: 7788 maximum: 9999 minimum: 1 type: number title: minimum_days number_of_payments: description: The number of merchant-initiated payments within the recurring payment agreement. example: 778 maximum: 999 minimum: 1 type: number title: number_of_payments frequency: description: The frequency of the payments within the series as agreed with the payer under your agreement with them. enum: - AD_HOC - DAILY - FORTNIGHTLY - MONTHLY - OTHER - QUARTERLY - TWICE_YEARLY - WEEKLY - YEARLY example: YEARLY type: string title: frequency type: description: The type of commercial agreement that the payer has with you.Specify the agreement type when you have provided a value for agreement.id and this payment is the first in a series of payments. The default value is OTHER. enum: - INSTALLMENT - OTHER - RECURRING - UNSCHEDULED example: UNSCHEDULED type: string title: frequency start_date: description: This is the effective start date for the payment agreement. example: '2024-02-15' format: date type: string title: start_date type: object Authentication-Payer-Response: type: object title: Authentication Payer Response required: - authentication - customer - order - transaction properties: authentication: $ref: '#/components/schemas/Authentication-Payer-Initiate-Response' customer: $ref: '#/components/schemas/Customer-Authentication-Response' method: $ref: '#/components/schemas/Authentication-Payer-Method-Response' transaction: $ref: '#/components/schemas/Authentication-Transaction-Response' order: $ref: '#/components/schemas/Authentication-Payer-Order-Response' mandate: $ref: '#/components/schemas/Authentication-Mandate' shipping: $ref: '#/components/schemas/Authentication-Payer-Shipping' additionalProperties: false description: Payment Request Authentication-Device-Payment: title: device type: object description: Device properties: eci_indicator: description: The Electronic Commerce Indicator generated for device payments. example: '12' maxLength: 2 minLength: 1 type: string title: eci_indicator online_payment_cryptogram: description: A cryptogram used to authenticate the transaction (from decrypted token). example: '56789' maxLength: 200 minLength: 1 type: string title: online payment cryptogram cryptogram_format: description: The format of the cryptogram provided for the digital payment. enum: - 3DSECURE - EMV example: EMV type: string title: cryptogram_format token: description: The payment token received from the device's payment SDK (e.g., Apple Pay). example: '56789' maxLength: 16384 minLength: 1 type: string title: token Authentication-Customer-Device-Response: title: Authentication Customer Device Response description: Customer-Device. required: - ciphertext - nonce - tag properties: ani: description: The telephone number captured by ANI (Automatic Number Identification) when the customer calls to place the order. example: M1234567890 maxLength: 10 minLength: 1 type: string title: ani ani_call_type: description: The 2 digit ANI information identifier provided by the telephone company to indicate the call type, for example, cellular (61-63), toll free (24,25), etc. example: '63' maxLength: 2 minLength: 1 type: string title: ani_call_type browser: description: The User-Agent header of the browser the customer used to place the order. example: '63' maxLength: 2048 minLength: 1 type: string title: browser hostname: description: The name of the server to which the customer is connected. example: '63' maxLength: 60 minLength: 1 type: string title: hostname ip_address: description: The name of the server to which the customer is connected. example: '63' maxLength: 15 minLength: 7 type: string title: ip_address mobile_phone_model: description: The name of the server to which the customer is connected. example: '63' maxLength: 255 minLength: 1 type: string title: mobile_phone_model ciphertext: description: Base64 encoded ciphertext. example: '63' maxLength: 10000 minLength: 1 type: string title: ciphertext nonce: description: Base64 encoded GCM nonce. example: '63' maxLength: 16 minLength: 16 type: string title: nonce tag: description: Base64 encoded GCM tag. example: '63' maxLength: 24 minLength: 24 type: string title: tag Authentication-Payer-Initiate-Response: title: ' Payer Authentication Response' required: - method_completed - method_supported - requestor_id - requestor_name - payer_interaction properties: acs_eci: description: Electronic Commerce Indicator (ECI) value provided by the issuer's ACS. example: '56' maxLength: 2 minLength: 1 type: string title: acs_eci token: description: The base64 encoded value generated by the issuer (CAVV/AAV/AEVV/Authentication Value). example: '56' maxLength: 32 minLength: 28 type: string title: token 3ds_transaction_id: description: A unique identifier for the 3-D Secure authentication transaction (XID for v1, DS ID for v2). example: '56' maxLength: 50 minLength: 1 type: string title: 3ds_transaction_id server_transaction_id: description: Unique identifier assigned by the 3DS Server (threeDSServerTransID). example: '56' maxLength: 50 minLength: 1 type: string title: server_transaction_id acs_transaction_id: description: A unique transaction identifier assigned by the Access Control Server (ACS). example: '56' maxLength: 36 minLength: 36 type: string title: acs_transaction_id scheme: description: The EMV 3DS authentication scheme used (e.g., MADA, MASTERCARD, VISA). example: '56' maxLength: 50 minLength: 2 type: string title: scheme custom: description: Additional information returned by the scheme or issuer in the authentication response. example: '56' maxLength: 4000 minLength: 1 type: string title: custom directory_server_id: description: Additional information returned by the scheme or issuer in the authentication response. example: '56' maxLength: 10 minLength: 10 type: string title: directory_server_id directory_server_reference: description: Reference number assigned to the Directory Server (DS) by EMV Co. example: '56' maxLength: 32 minLength: 1 type: string title: directory_server_reference directory_transaction_id: description: A unique transaction identifier assigned by the scheme Directory Server. example: '56' maxLength: 50 minLength: 1 type: string title: directory_transaction_id method_completed: description: Indicates if the issuer's ACS completed the method call to obtain browser info. type: boolean example: true title: method_completed method_supported: description: Indicates if the issuer's ACS supports the method call protocol. enum: - NOT_SUPPORTED - SUPPORTED example: NOT_SUPPORTED type: string title: method_supported protocol_version: description: The version of the EMV 3-D Secure protocol used (e.g., 2.1.0). example: CART123456 maxLength: 20 minLength: 1 type: string title: protocol_version requestor_id: description: The unique identifier assigned to the merchant by the card scheme directory server for 3DS2. example: CART123456 maxLength: 20 minLength: 1 type: string title: requestor_id requestor_name: description: The unique name assigned to the merchant by the card scheme directory server for 3DS2. example: CART123456 maxLength: 40 minLength: 1 type: string title: requestor_name sdk: $ref: '#/components/schemas/Sdk-Payer-Authentication-Response' status_reason_code: description: A code indicating the reason for the transaction status (EMVCo specification). example: '56' maxLength: 2 minLength: 2 type: string title: status_reason_code status: description: Indicates the result of payer authentication with the issuer (e.g., Y, N, U, A, R). example: Y maxLength: 1 minLength: 1 type: string title: status acs_reference: description: Reference number assigned to the issuer's ACS by EMV Co. example: AFT123456 maxLength: 32 minLength: 1 type: string title: acs_reference signed_content: description: A JSON Web Signature (JWS) object returned by the issuer's ACS (acsSignedContent). example: AFT123456 maxLength: 13684 minLength: 1 type: string title: signed_content amount: description: Product amount example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: amount method: description: The method that the issuer will use to authenticate the payer. enum: - DYNAMIC - OUT_OF_BAND - STATIC example: STATIC type: string title: method payer_interaction: description: Indicates if payer interaction was used to complete the authentication process. enum: - NOT_POSSIBLE - NOT_REQUIRED - REQUIRED example: NOT_REQUIRED type: string title: payer_interaction payment_exemption: description: Indicates why this payment qualifies for an SCA exemption. enum: - AUTO - LOW_RISK - LOW_VALUE_PAYMENT - TRUSTED_MERCHANT - MERCHANT_INITIATED_TRANSACTION - RECURRING_PAYMENT - SECURE_CORPORATE_PAYMENT - TRUSTED_MERCHANT example: TRUSTED_MERCHANT type: string title: payment_exemption trusted_merchant_status: description: Indicates if the payer has added you to their list of trusted merchants for this card. enum: - NOT_ON_LIST - ON_LIST example: ON_LIST type: string title: trusted_merchant_status redirect_acs_url: type: string maxLength: 500 minLength: 1 description: The URL of the issuer's ACS to be used for the challenge flow (valid RFC 1738 URL). example: https://greenzone-api.uat.nam.nsroot.net/api/notification title: redirect_acs_url redirect_c_req: type: string maxLength: 4000 minLength: 1 description: The Base64 URL encoded CReq message to be used for the challenge flow. example: https://greenzone-api.uat.nam.nsroot.net/api/notification title: redirect_c_req redirect_html: type: string maxLength: 40960 minLength: 1 description: The Base64 URL encoded CReq message to be used for the challenge flow. example: https://greenzone-api.uat.nam.nsroot.net/api/notification title: redirect_html redirect_domain_name: type: string maxLength: 253 minLength: 1 description: The domain name of the site where payer authentication was performed (e.g., ACS domain name). example: https://greenzone-api.uat.nam.nsroot.net/api/notification title: redirect_domain_name status_code: type: string maxLength: 100 minLength: 1 description: Indicates the status of payer authentication with the issuer (e.g., NPCI BEPG status code). example: '500' title: status_code status_description: type: string maxLength: 1024 minLength: 1 description: Indicates the status of payer authentication with the issuer (e.g., NPCI BEPG status code). example: '500' title: status_description line_of_business: type: string maxLength: 100 minLength: 1 description: Identifier for different lines of business configured in the merchant profile. example: '500' title: line_of_business time: type: string format: date-time description: Date and time of the payer authentication being performed (YYYY-MM-DDThh:mm:ss.SSSZ). example: '2022-09-13T08:23:49.114Z' title: time version: description: The form of payer authentication selected or available for use by the gateway. enum: - 3DS2 - RUPAY - PASSKEY - NONE example: 3DS2 type: string title: version Holder-Name: title: Holder-Name description: The name of the bank account holder for the payer's bank account. properties: first_name: description: "first_name. \n - For ACH Pay and verify transaction method.holder.first_name parameter is mandatory \n - For India Card transactions, method.holder.first_name parameter is mandatory" example: PETER maxLength: 50 minLength: 1 type: string title: first_name last_name: description: "last_name. \n - For ACH Pay and verify transaction method.holder.last_name parameter is mandatory \n - For India Card transactions, method.holder.last_name parameter is mandatory" example: A maxLength: 50 minLength: 1 type: string title: last_name Customer-Authentication-Response: title: Customer Authentication Response properties: account: title: customer account authentication response description: Account Details properties: number: description: Your identifier for the payer's account with you (immutable ID). example: 1234abcjki maxLength: 40 minLength: 1 type: string title: number authentication: $ref: '#/components/schemas/Authentication-Customer-Payer-Response' history: $ref: '#/components/schemas/Authentication-Customer-History-Payer-Request' name: $ref: '#/components/schemas/Name' tax_id: description: Customer's payer identification (e.g., email address) example: 234.453.678-21 maxLength: 100 minLength: 1 type: string title: tax_id email: description: Customer email example: customer.raj2024@gmail.com type: string pattern: '[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,4}$' title: email phone: description: Customer phone. example: '+919962125789' pattern: \+[0-9]{1,3}[-\ ][0-9()+\-]{1,30} type: string title: phone mobile_phone: description: Customer phone. example: '+919962125789' pattern: \+[0-9]{1,3}[-\ ][0-9()+\-]{1,30} type: string title: mobile_phone device: $ref: '#/components/schemas/Authentication-Customer-Device-Response' address: $ref: '#/components/schemas/Authentication-Address' Recipient-Name: title: recipient name type: object description: Recipient Name properties: first_name: description: The first name of the person to whom the order is being shipped. example: JOHN maxLength: 50 minLength: 1 type: string title: first_name last_name: description: The last name or surname of the person to whom the order is being shipped. example: PETER maxLength: 50 minLength: 1 type: string title: last_name company_name: description: The name of the company associated with this address. example: COMPANY NAME maxLength: 100 minLength: 1 type: string title: company_name Error-Detail: type: object title: Error Detail properties: issue: type: string maxLength: 150 description: more details about the issue title: issue action: type: string maxLength: 150 description: corrective action to be taken to resolve above issue title: action code: type: string maxLength: 10 description: unique code representing the issue title: code Initiate-Authentication: title: ' Intiate Authentication' required: - channel properties: channel: description: Indicates the channel in which the authentication request is initiated. enum: - MERCHANT_REQUESTED - PAYER_APP - PAYER_BROWSER example: MERCHANT_REQUESTED type: string title: channel purpose: description: Indicates the context in which payer authentication is requested. enum: - ADD_CARD - AGREEMENT_CANCELLATION - MAINTAIN_CARD - PAYMENT_TRANSACTION - REFRESH_AUTHENTICATION example: ADD_CARD type: string title: purpose type: type: array items: type: string description: "A comma separated list of accepted payer authentication forms. \n- Accepted values are 3DS1,3DS2,PASSKEY" title: type line_of_business: description: Identifier for different lines of business configured in the merchant profile. example: CART123456 maxLength: 100 minLength: 1 type: string title: line_of_business Sdk-Payer-Authentication-Response: title: sdk payer authentication description: sdk payer authentication response properties: callback_url: description: URL to call after a 3DS challenge has been completed (valid RFC 1738 URL). example: PA123456789 maxLength: 500 minLength: 1 type: string title: callback_url device_interface: description: The UI formats the payer's device supports for challenges (EMVCosdkInterface). example: PA123456789 maxLength: 256 minLength: 1 type: string title: device_interface redirect_url: description: Indicates if the application should expect a Redirect URL in CRes to redirect the payer to their issuer's mobile banking app (true/false). type: boolean example: false title: redirect_url time_out: description: 'The duration (in seconds) available to the payer to authenticate (Default: 900, range 300-900).' example: PA123456789 maximum: 900 minimum: 300 type: number title: time_out ui_type: type: array items: type: string description: The UI types the SDK supports for displaying challenges within the app (EMVCosdkUiType). title: ui_type Authentication-Transaction-Response: title: Transaction required: - id - amount - status - description properties: additional_info: type: array items: $ref: '#/components/schemas/Additional-Info' id: description: Unique Transaction identification provided by the merchant during transaction creation example: pay02052023456r maxLength: 128 minLength: 1 type: string title: id creation_date_time: type: string format: date-time readOnly: true description: Date and time at which request was received in UTC timezone example: '2022-09-13T08:23:49.114Z' title: creation_date_time update_time: type: string format: date-time readOnly: true description: Date and time at which request was received in UTC timezone example: '2022-09-13T08:23:49.114Z' title: update_time amount: description: Transaction amount example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: amount gateway_recommendation: description: Provides a recommendation for your next action based on the outcome of the transaction. enum: - DO_NOT_PROCEED - DO_NOT_PROCEED_ABANDON_ORDER - PROCEED - RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS example: DO_NOT_PROCEED type: string title: gateway_recommendation status: type: string enum: - FAILED - PENDING - SUCCESS - UNKNOWN description: A system-generated high level overall result of the transaction/operation.Value must be a member of the following list. The values are case sensitive. title: status description: description: Transaction status description example: ABORTED maxLength: 250 minLength: 1 type: string title: description authentication_status: description: Indicates the result of payer authentication. enum: - AUTHENTICATION_ATTEMPTED - AUTHENTICATION_AVAILABLE - AUTHENTICATION_EXEMPT - AUTHENTICATION_FAILED - AUTHENTICATION_NOT_IN_EFFECT - AUTHENTICATION_NOT_SUPPORTED - AUTHENTICATION_PENDING - AUTHENTICATION_REJECTED - AUTHENTICATION_REQUIRED - AUTHENTICATION_SUCCESSFUL - AUTHENTICATION_UNAVAILABLE example: AUTHENTICATION_REQUIRED type: string title: authentication_status currency_code: description: ISO 4217 Currency Code for instance USD/GBP/EUR enum: - USD example: USD type: string title: currency_code type: description: Indicates the result of payer authentication. enum: - AUTHENTICATION - AUTHORIZATION - AUTHORIZATION_UPDATE - CAPTURE - CHARGEBACK - DISBURSEMENT - FUNDING - PAYMENT - REFUND - REFUND_REQUEST - VERIFICATION - VOID_AUTHORIZATION - VOID_CAPTURE - VOID_PAYMENT - VOID_REFUND example: VOID_REFUND type: string title: type Authentication-Payer-Shipping: type: object title: Authentication Payer Shipping properties: address_same_as_billing: description: Indicates whether the shipping address provided is the same as the payer's billing address. enum: - SAME - DIFFERENT - UNKNOWN example: UNKNOWN type: string title: address_same_as_billing recipient_name: $ref: '#/components/schemas/Recipient-Name' phone: pattern: \+[0-9]{1,3}[-\ ][0-9()+\-]{1,30} type: string description: The contact person's phone number in ITU-T E123 format. example: +1 607 1234 456 title: phone type: description: The type of shipping method used. enum: - ELECTRONIC - GROUND - NOT_SHIPPED - OVERNIGHT - PICKUP - PRIORITY - SAME_DAY example: SAME_DAY type: string title: type email: pattern: '[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,4}$' type: string description: The contact person's email address.The parameter format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses. example: xyjfg@gmail.com title: email origin: maxLength: 10 minLength: 1 type: string description: The post code or zip code of the address the order is shipped from. example: '120567' title: origin source: description: The type of shipping method used. enum: - ADDRESS_ON_FILE - NEW_ADDRESS example: NEW_ADDRESS type: string title: source address: $ref: '#/components/schemas/Shipping-Address' Authentication-Response: type: object title: Authentication Response required: - method - transaction - order - authentication properties: transaction: type: object title: Authentication transaction response required: - amount - id - currency_code - country_code - type - status - description properties: id: description: Unique Transaction identification provided by the merchant during transaction creation example: pay02052023456r maxLength: 128 minLength: 1 type: string title: id amount: description: Transaction amount example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: amount country_code: description: Country code enum: - US example: US type: string title: country_code currency_code: description: ISO 4217 Currency Code for instance USD/GBP/EUR enum: - USD example: USD type: string title: currency_code gateway_recommendation: description: Provides a recommendation for your next action based on the outcome of the transaction. enum: - DO_NOT_PROCEED - DO_NOT_PROCEED_ABANDON_ORDER - PROCEED - RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS example: DO_NOT_PROCEED type: string title: gateway_recommendation status: type: string maxLength: 20 minLength: 1 description: "Transaction Status, following status you will receive in response \n- PENDING - Transaction pending action from customer \n- FAILED - Transaction failed for invalid payload \n- UNKNOWN - The result of the operation is unknown \n- SUCCESS - The operation was successfully processed" example: SUCCESS title: status description: type: string maxLength: 256 minLength: 1 description: "Transaction Status, following status you will receive in response \n- PENDING - Transaction pending action from customer \n- FAILED - Transaction failed for invalid payload \n- UNKNOWN - The result of the operation is unknown \n- SUCCESS - The operation was successfully processed" example: The operation was successfully processed title: description creation_date_time: type: string format: date-time description: "GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) \n- Instant Payment (Debit) - Date time, generated by CitiConnect API, when CitiConnect API accepted a payment initiation after validation" example: '2022-09-13T08:23:49.114Z' title: creation_date_time update_time: type: string format: date-time description: Indicates the date and time the gateway considers the order to have last been updated GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) example: '2022-09-13T08:23:49.114Z' title: update_time type: description: Indicates the type of action performed on the order. enum: - AUTHENTICATION - AUTHORIZATION - AUTHORIZATION_UPDATE - CAPTURE - CHARGEBACK - DISBURSEMENT - FUNDING - PAYMENT - REFUND - REFUND_REQUEST - VERIFICATION - VOID_AUTHORIZATION - VOID_CAPTURE - VOID_PAYMENT - VOID_REFUND example: VERIFICATION type: string title: type reference: description: An optional identifier for this transaction example: REPAY789541 maxLength: 250 minLength: 1 type: string title: reference authentication_status: description: Indicates the result of payer authentication. enum: - AUTHENTICATION_ATTEMPTED - AUTHENTICATION_AVAILABLE - AUTHENTICATION_EXEMPT - AUTHENTICATION_FAILED - AUTHENTICATION_NOT_IN_EFFECT - AUTHENTICATION_NOT_SUPPORTED - AUTHENTICATION_PENDING - AUTHENTICATION_REJECTED - AUTHENTICATION_REQUIRED - AUTHENTICATION_SUCCESSFUL - AUTHENTICATION_UNAVAILABLE example: AUTHENTICATION_UNAVAILABLE type: string title: authorization_status method: type: object title: Authentication Method Response required: - type properties: type: description: "Method specified by the customer for the transaction \n- Provide CARD for CARD transactions" type: string enum: - CARD - GOOGLEPAY - APPLEPAY example: CARD title: type card: $ref: '#/components/schemas/Authentication-Card-Response' holder_name: $ref: '#/components/schemas/Holder-Name' token_id: description: Token_number. example: PA123456789 maxLength: 50 minLength: 1 type: string title: token_number token_type: description: Token type. enum: - ALT_TOKEN - NETWORK_TOKEN - ISSUER_TOKEN - CITI_TOKEN example: ISSUER_TOKEN type: string title: token_type order: type: object title: Authentication Order Response required: - creation_date_time - currency_code - id - update_time - total_auth_amount - total_captured_amount - total_refunded_amount properties: id: description: A unique identifier for this order to distinguish it from any other order you create. example: OR123456789 maxLength: 40 minLength: 1 type: string title: id creation_date_time: type: string format: date-time description: GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) example: '2022-09-13T08:23:49.114Z' title: creation_date_time update_time: type: string format: date-time description: Indicates the date and time the gateway considers the order to have last been updated GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) example: '2022-09-13T08:23:49.114Z' title: update_time reference: description: An optional identifier for the orderFor example, a shopping cart number, an order number, or an invoice number. example: REPAY789541 maxLength: 200 minLength: 1 type: string title: reference currency_code: description: ISO 4217 Currency Code for instance USD/GBP/EUR enum: - USD example: USD type: string title: currency_code status: type: string maxLength: 30 minLength: 1 description: "Order Status, following status you will receive in response \n- AUTHENTICATED - The payer was successfully authenticated. \n- AUTHENTICATION_INITIATED - Payer authentication has been initiated but not completed. \n- AUTHENTICATION_NOT_NEEDED - Payer authentication was not performed as it was not needed. \n- AUTHENTICATION_UNSUCCESSFUL - Payer authentication was not able to be successfully completed. \n- AUTHORIZED - The payment has been authorized successfully but the authorized amount has not yet been captured, in part, full, or excess. \n- CANCELLED - The initial transaction for this order has been voided successfully. \n- CAPTURED - The authorized amount for this order, in full or excess, has been captured successfully. \n- CHARGEBACK_PROCESSED - A Chargeback has been processed against this order. \n- DISPUTED - The payment has been disputed and is under investigation. A request for information has been received or a chargeback is pending. \n- EXCESSIVELY_REFUNDED - The payment has been captured in part, full, or excess, but the captured amount in excess has been refunded successfully. \n- FAILED - The payment has not been successful. \n- FUNDING - The order transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from the payment service provider. \n- INITIATED - A browser payment that has successfully been initiated for this order. No payment has yet been made. \n- PARTIALLY_CAPTURED - The authorized amount for this order, in part, has been captured successfully. \n- PARTIALLY_REFUNDED - The payment has been captured in part, full, or excess, but the captured amount in part has been refunded successfully. \n- REFUNDED - The payment has been captured in part, full, or excess, but the captured amount in full has been refunded successfully. \n- REFUND_REQUESTED - A refund against captured amounts on this order has been requested but not executed. Requires further action to approve the refund. \n- VERIFIED - The card details for this order have successfully been verified. No payment has yet been initiated or made. \n- DISBURSED - The order amount has successfully been disbursed to the payer." example: AUTHENTICATED title: status total_auth_amount: description: The amount that has been successfully authorized for this order. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: total_auth_amount total_captured_amount: description: The amount that has been successfully captured for this order. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: total_captured_amount total_refunded_amount: description: The amount that has been successfully captured for this order. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: total_refunded_amount authentication_status: description: Indicates the result of payer authentication. enum: - AUTHENTICATION_ATTEMPTED - AUTHENTICATION_AVAILABLE - AUTHENTICATION_EXEMPT - AUTHENTICATION_FAILED - AUTHENTICATION_NOT_IN_EFFECT - AUTHENTICATION_NOT_SUPPORTED - AUTHENTICATION_PENDING - AUTHENTICATION_REJECTED - AUTHENTICATION_REQUIRED - AUTHENTICATION_SUCCESSFUL - AUTHENTICATION_UNAVAILABLE example: AUTHENTICATION_UNAVAILABLE type: string title: authorization_status authentication: title: ' Authentication Sub Response' required: - channel - method_completed - method_supported - requestor_id - requestor_name - accept_versions - version properties: scheme: description: The EMV 3DS authentication scheme used (e.g., MADA, MASTERCARD, VISA) for externally authenticated transactions. example: CART123456 maxLength: 50 minLength: 2 type: string title: scheme directory_server_id: description: Unique identifier for the Directory Server (RID) for in-app authentication. example: CART123456 maxLength: 10 minLength: 10 type: string title: directory_server_id method_completed: description: Indicates if the issuer's ACS completed the method call to obtain browser info. type: boolean example: true title: method_completed method_supported: description: Indicates if the issuer's ACS supports the method call protocol. enum: - NOT_SUPPORTED - SUPPORTED example: NOT_SUPPORTED type: string title: method_supported protocol_version: description: The version of the EMV 3-D Secure protocol used (e.g., 2.1.0). example: CART123456 maxLength: 20 minLength: 1 type: string title: protocol_version requestor_id: description: The unique identifier assigned to the merchant by the card scheme directory server for 3DS2. example: CART123456 maxLength: 20 minLength: 1 type: string title: requestor_id requestor_name: description: The unique name assigned to the merchant by the card scheme directory server for 3DS2. example: CART123456 maxLength: 40 minLength: 1 type: string title: requestor_name accept_versions: type: array items: type: string description: A comma separated list of the forms of payer authentication that you will accept. title: accept_versions channel: description: Indicates the channel in which the authentication request is initiated. enum: - MERCHANT_REQUESTED - PAYER_APP - PAYER_BROWSER example: MERCHANT_REQUESTED type: string title: channel method: description: The method that the issuer will use to authenticate the payer. enum: - DYNAMIC - OUT_OF_BAND - STATIC example: STATIC type: string title: method purpose: description: Indicates the context in which payer authentication is requested. enum: - ADD_CARD - AGREEMENT_CANCELLATION - MAINTAIN_CARD - PAYMENT_TRANSACTION - REFRESH_AUTHENTICATION example: ADD_CARD type: string title: purpose method_post_data: description: Base64 URL encoded frame contents to be posted to the method URL for risk assessment. example: https://greenzone-api.uat.nam.nsroot.net/api/notification maxLength: 100 minLength: 1 type: string title: method_post_data method_url: type: string maxLength: 500 minLength: 1 description: The URL provided by the issuer to which the method post data must be sent. example: https://greenzone-api.uat.nam.nsroot.net/api/notification title: method_url redirect_html: type: string maxLength: 40960 minLength: 1 description: The URL provided by the issuer to which the method post data must be sent. example: https://greenzone-api.uat.nam.nsroot.net/api/notification title: redirect_html version: description: Indicates the available payer authentication method or NONE if unavailable. enum: - 3DS2 - RUPAY - PASSKEY - NONE example: RUPAY type: string title: version line_of_business: description: Identifier for different lines of business configured in the merchant profile. example: CART123456 maxLength: 100 minLength: 1 type: string title: line_of_business Authentication-Payer-Order: title: Authentication Payer Order required: - id - currency_code - avs_action - avs_response - charge_type properties: id: description: A unique identifier for this order to distinguish it from any other order you create. example: OR123456789 maxLength: 50 minLength: 1 type: string title: id currency_code: description: The currency of the order expressed as an ISO 4217 alpha code, e.g. USD. enum: - USD example: USD type: string title: currency_code amount: description: The total amount for the order. This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.The value of this parameter in the response is zero if payer funds are not transferred. example: 200 maximum: 1000000000000000000 minimum: 0.01 type: number title: amount charge_amount: description: The amount of the additional fee that you are charging the payer. example: '20.0' maximum: 1000000000000000000 minimum: 0.01 type: number title: charge_amount charge_type: description: The type of the additional fee that you are charging the payer. enum: - SURCHARGE example: SURCHARGE type: string title: charge_type net_amount: description: The total item amount for the order. example: 150 maximum: 1000000000000000000 minimum: 0.01 type: number title: net_amount shipping_and_handling_amount: description: The total shipping and handling amount for the order, including taxes on the shipping and/or handling example: 20 maximum: 1000000000000000000 minimum: 0.01 type: number title: shipping_and_handling_amount shipping_and_handling_tax_amount: description: The tax amount levied on the shipping and handling amount for the order. example: 20 maximum: 1000000000000000000 minimum: 0.01 type: number title: shipping_and_handling_tax_amount shipping_and_handling_tax_rate: description: The tax rate applied to the shipping and handling amount for the order to determine the shipping and handling tax amount. example: 20 maximum: 1000000000000000000 minimum: 0.01 type: number title: shipping_and_handling_tax_rate discount_amount: description: The total amount of the discount you have applied to the order example: 300 maximum: 1000000000000000000 minimum: 0.01 type: number title: discount_amount tax_registration_id: description: Your tax registration identifier provided by the Federal/National tax authority (for example, federal tax identification number, ABN).If you are a Canadian merchant, use this parameter to provide your Tax Registration ID for paying Harmonized Sales Tax (HST) or Goods and Services Tax (GST) collected by the Canada Revenue Agency. example: 300 maxLength: 30 minLength: 1 type: string title: tax_registration_id gratuity_amount: description: The gratuity amount (also known as customs tax, tariff or dues) for the order. example: 150 maximum: 1000000000000000000 minimum: 0.01 type: number title: gratuity_amount certainty: description: Indicates if you expect to capture the full order amount for which you are requesting authorization.If you do not provide a value for order.certainty the default configured for you by your payment service provider will be used. The value provided in the response shows the value the gateway sent to the acquirer. enum: - ESTIMATED - FINAL example: FINAL type: string title: certainty date: description: The date the payer placed the order. example: '1988-02-15' format: date type: string title: date description: description: Short textual description of the contents of the order. example: LAPTOP PURCHASE maxLength: 127 minLength: 1 type: string title: description discount_code: description: The code you use to identify the reason for the discount. example: DISC001 maxLength: 40 minLength: 1 type: string title: discount_code discount_description: description: A description of your reason for the discount. example: CARD DISCOUNT maxLength: 127 minLength: 1 type: string title: discount_description duty_amount: description: The duty amount (also known as customs tax, tariff or dues) for the order. example: 150 maximum: 1000000000000000000 minimum: 0.01 type: number title: duty_amount entity: description: Your identifier for the part of your organization that is responsible for the order.You might provide this data when you want to track the accountability for the order. For example, store number, sales region, branch, or profit center. example: INDENTITY1 maxLength: 40 minLength: 1 type: string title: entity purchase_type: description: 'Indicates the purchase of specific types of goods or services You must provide a value if your Merchant Category Code (MCC) is one of the following: 6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY. 6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES. 6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT. If the transaction pulls money from an account for the purpose of crediting another account you must set purchase type to ACCOUNT_FUNDING. You may set purchase type to OTHER for any other type of payment.' enum: - ACCOUNT_FUNDING - CRYPTOCURRENCY - DEBT_REPAYMENT - HIGH_RISK_SECURITIES - OTHER example: ACCOUNT_FUNDING type: string title: purchase_type tax_amount: description: The total tax amount for the order. If you do not provide this value but provide line item data, then this amount is calculated as the sum of the item.quantity times the item.unitTaxAmount for all the line items (total tax amount).If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount. example: 150 maximum: 1000000000000000000 minimum: 0.01 type: number title: tax_amount retailer_location: description: Provide information about the location of the retailers for goods or services included in this order. Where a retailer is located in a country different from your country, they are considered a foreign retailer, otherwise they are considered a domestic retailer. enum: - DOMESTIC_ONLY - FOREIGN_AND_DOMESTIC - FOREIGN_ONLY example: FOREIGN_ONLY type: string title: retailer_location avs_action: description: The action to be performed for the Address Verification Service (AVS) Response Code. enum: - NO_ACTION - REJECT - REVIEW example: REVIEW type: string title: avs_action avs_response: description: The Address Verification Service (AVS) Response Code for which you are defining the rule. enum: - ADDRESS_MATCH - ADDRESS_ZIP_MATCH - NAME_ADDRESS_MATCH - NAME_MATCH - NAME_ZIP_MATCH - NOT_AVAILABLE - NOT_REQUESTED - NOT_VERIFIED - NO_MATCH - SERVICE_NOT_AVAILABLE_RETRY - SERVICE_NOT_SUPPORTED - ZIP_MATCH example: ADDRESS_MATCH type: string title: avs_response invoice_number: description: The invoice number you issued for this order example: INV123456 maxLength: 25 minLength: 1 type: string title: invoice_number type: object Response: required: - access_token - expires_in - token_type type: object description: Successful token response returned to the TPP, containing the bearer token and its validity details. title: Response properties: token_type: type: string description: Token type issued by the authorization server; value is "Bearer". title: token_type enum: - Bearer access_token: type: string description: OAuth access token to be presented by the TPP in the Authorization header for subsequent API requests. title: access_token expires_in: type: integer description: Lifetime of the access token in seconds from the time of issuance. title: expires_in scope: type: string title: scope description: Scope associated with the issued access token. error_message: description: Error payload returned to the TPP when the token request cannot be processed or authorized. required: - httpCode title: ErrorMessage properties: httpCode: type: string maxLength: 3 description: Numeric HTTP Staus code title: httpCode httpMessage: type: string maxLength: 128 description: HTTP error message title: httpMessage example: Bad Request moreInformation: type: string maxLength: 128 description: HTTP error message title: moreInformation example: please provide valid value for request Request: type: object description: Form-encoded token request body sent by the TPP to obtain an OAuth access token using client credentials. required: - grant_type - scope title: Request properties: grant_type: type: string title: grantType description: You must always pass 'client_credentials' in this field because Citi only provides credentials-based authentication for API users. enum: - client_credentials scope: type: string title: scope description: This is the version scope of the authentication call. responses: Gateway-Timeout: description: Gateway Timeout headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' examples: Gateway-Timeout-Gateway-Error-Example: $ref: '#/components/examples/Gateway-Timeout-Gateway-Error-Example' Unsupported-Media-Type: description: Unsupported Media Type headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' - $ref: '#/components/schemas/Error-Response' examples: Unsupported-Media-Type-Service-Error-Example: $ref: '#/components/examples/Unsupported-Media-Type-Example' Unsupported-Media-Type-Gateway-Error-Example: $ref: '#/components/examples/Un-Supported-Media-Type-Gateway-Error-Example' Rate-Limit-Exceeded: description: Rate Limit Exceeded headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' examples: Rate-Limit-Exceeded-Gateway-Error-Example: $ref: '#/components/examples/Rate-Limit-Exceeded-Gateway-Error-Example' Not-Found: description: Not Found headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' - $ref: '#/components/schemas/Error-Response' examples: Not-Found-Service-Error-Example: $ref: '#/components/examples/Not-Found-Example' Not-Found-Gateway-Error-Example: $ref: '#/components/examples/Not-Found-Gateway-Error-Example' Conflict: description: Conflict headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error-Response' examples: Idempotency-Id-Conflict-Example: $ref: '#/components/examples/Idempotency-Id-Conflict-Example' Internal-Server-Error: description: Internal Server Error headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' - $ref: '#/components/schemas/Error-Response' examples: Internal-Server-Error-Example: $ref: '#/components/examples/Internal-Server-Error-Example' Internal-Server-Gateway-Error-Example: $ref: '#/components/examples/Internal-Server-Gateway-Error-Example' Method-Not-Allowed: description: Method Not Allowed headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' - $ref: '#/components/schemas/Error-Response' examples: Method-Not-Allowed-Service-Error-Example: $ref: '#/components/examples/Method-Not-Allowed-Example' Method-Not-Allowed-Gateway-Error-Example: $ref: '#/components/examples/Method-Not-Allowed-Gateway-Error-Example' Bad-Request: description: Bad Request headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' - $ref: '#/components/schemas/Error-Response' examples: Bad-Request-Service-Error-Example: $ref: '#/components/examples/Bad-Request-Example' Bad-Request-Gateway-Error-Example: $ref: '#/components/examples/Bad-Request-Gateway-Error-Example' Unauthorized: description: Unauthorized headers: apim-guid: $ref: '#/components/headers/Request-Id' content: application/json: schema: oneOf: - $ref: '#/components/schemas/Gateway-Error-Response' - $ref: '#/components/schemas/Error-Response' examples: Unauthorized-Service-Error-Example: $ref: '#/components/examples/Unauthorized-Example' Unauthorized-Gateway-Error-Example: $ref: '#/components/examples/Unauthorized-Gateway-Error-Example' parameters: Id: name: id in: path required: true description: Your unique End To End identification schema: type: string maxLength: 128 minLength: 1 description: Your unique End To End identification example: abc-pay-123 Idempotency-Id: name: Idempotency-Id in: header required: true description: "Your unique identification for a POST request \n - Maximum length is 128. \n- CitiConnect API responds with an error (HTTP status 4XX) if your POST request idempotency identification value is a duplicate across a recent history of idempotency identifications in Citi's database." schema: type: string maxLength: 128 description: "Your unique identification for a POST request \n - Maximum length is 128. \n- CitiConnect API responds with an error (HTTP status 4XX) if your POST request idempotency identification value is a duplicate across a recent history of idempotency identifications in Citi's database. \n- If you don't receive any response (HTTP status 2XX, 4XX or 5XX) from Citi to your POST request and you wish to retry, reinitiate your request with the same idempotency identification to prevent accidental duplicate payment." example: a44cbb60-6de4-4edb-9a7a-123414bba3bb Merchant-Token-Id: name: Merchant-Id in: header required: true description: Your unique Merchant Identification number schema: type: string maxLength: 40 minLength: 1 description: Your unique Merchant Identification number example: M123456987 Patch-Authentication-Operation: in: header name: Operation required: false description: API operation schema: type: string enum: - AUTHENTICATE_PAYER description: API operation example: AUTHENTICATE_PAYER Post-Authentication-Operation: in: header name: Operation required: false description: API operation schema: type: string enum: - INITIATE_AUTHENTICATION description: API operation example: INITIATE_AUTHENTICATION Post-Country-Code: name: Country-Code in: header schema: type: string maxLength: 2 minLength: 2 description: Country Code example: IN Client-Id: in: query name: client_id required: true description: Your unique identification, same as the identification you use for OAuth token generation, Citi shared with you during your CitiConnect API onboarding schema: type: string description: Your unique identification, same as the identification you use for OAuth token generation, Citi shared with you during your CitiConnect API onboarding example: 9a10a5d6-63d4-4885-b6bd-19e79629496d headers: Request-Id: schema: type: string description: Citi's unique identification for your request securitySchemes: clientCredentials: 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. ' oAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: /authenticationservices/v3/oauth/token tokenUrl: /authenticationservices/v3/oauth/token scopes: authenticationservices/v1: Grant read-only access to payment initation service BasicAuthentication: type: http description: Username is the application's client_id and password is the client_secret. scheme: basic clientIdHeader: type: apiKey name: X-IBM-Client-Id in: header clientSecretHeader: type: apiKey name: X-IBM-Client-Secret in: header x-refined-from: - DigitalPaymentsCollectionsv12.yaml - ukraine_open_banking_authentication_api.yaml