/
Citibank API Integration Documentation

Citibank API Integration Documentation

Owned by Vladimir Nemec
Last updated: Jan 08, 2025 by Barbora Golasowská
6 min read

Work with payments in the Payment Journals

When you manually create a payment line in the journal, or when you create lines using the Suggest Payments action, a Payment Type is assigned to the line according to the specification in the Citibank Payment Types table.

The payment type distinguishes between different payment types according to the format specification within the Citibank API.

For each payment type, you can set whether Business Central will communicate directly with Citibank's API or will export a payment file that will need to be manually imported into your online banking.

image-20250106-084249.png

New fields the Citibank API Integration adds to the Payment Journals

  • Citi Payment Type: predefined payment type, by creating a line the most probable payment type is automatically suggested. If there are more options for the line, it can be changed. If you switch to a payment type that is incompatible with the parameters of the line, it switches back to the appropriate valid option.

  • Payment EndToEndId: unique identifier of the payment in Citibank.

  • Exported to Payment Status: this column corresponds to the payment status. If Business Central is connected to Citibank's API, the status of this line is verified in the background after the payment is sent. Alternatively it can be verified manually by clicking on the Check Payment Status action found in the Related menu, Payments tab and CitiBank sub-tab of the Payment Journal page.

image-20250106-142909.png

  • Exported to Payment Batch No.: if the payments are sent via the API, the bank requires that each payment be sent separately, in which case there is no need to fill in this field. However, if the payments are exported to a manual import file, all the lines sent will contain the same batch number. This way, the batch can be re-exported if the bank does not accept the batch in the online banking due to an error. The detailed procedure is described below.

How to send a payment?

Sending a payment using the API is done with the option Payment Request or Export to Payment File.

The corresponding option works only with the corresponding lines (the Citi Payment Types table frame defines which payment types can be exported and which can be sent using the API).

Payment lines approval

Citibank API Integration integrates with the standard line approval in the Payment Journals. If a payment approval is set in the integration settings, it is not possible to send payments without the journal line being approved (ApprovalEntry.Status::Approved). To enable approvals, you need to set up a standard approval workflow.             

Changes in sent payments

If a line has a status of Sent Request or Processed it cannot be changed.

Citibank API Integration Settings

  • Citi Settings:

In this table, you need to create a Citi Integration Settings Mode No. and set the URLs for API calls. Here you can also enable/disable the approval workflow.

  • Company Information:

In this table, you need to select a valid Citi Integration Settings Mode No.

  • Citibank Payment Types for a given country, including Citi Payment Type Definition:

Here you import the prescribed parameters through configuration packages.

  • Data Exchange Definitions:

Here you import the prescribed parameters for loading bank statements.

  • Bank Export/Import Setup:

Here you specify the codeunites and data exchange definitions for exporting and importing payments.

  • Bank Account Settings, on each corresponding bank account card, you need to set the following fields:

    • Payment Export Format

    • Bank Statement Import Format

    • Citi Bank Account toggle button needs to be turned on

    • Bank Branch No.

    • Bank Account No.

    • Last Statement Date

    • Bank Statement Nos.

    • Citi Payment Nos., ideally based on Calendar - to avoid downloading statements on weekends and holidays

  • If approval of payment lines is required:

Check the Payment Approval Required checkbox in Citi Settings.

  • User Setup:

This is where you set up payment access for individual users using a PIN. Check the Check Send Bank Payments checkbox and define the Send Bank Payments PIN.

By checking the Allow Change Payment Status, you allow the user to change the status of payment lines in the payment journal, which is necessary if you need to re-export a payment order.

Export payments

  • Prepare your payment lines in the Payment Journal. Posting Date must not be in the past.

  • If necessary filter out the lines to be sent, ideally using the Document No. The filter can include payments already sent or processed, the system will skip them (it only processes Exported to Payment Status = '' or 'Error').

  • You must check that all lines have Citi Payment Type filled in, otherwise the system will report an error and the export will have to be re-run.

There are two methods of sending payments:

  1. Export to a file

Export to file is done using the Bank/Export Payments File option, which requires a user PIN and export confirmation. The payment file is then downloaded to the browser and the unique payment identifier endtoendid and the status of the payment ( Exported or Processed depending on the settings) are added to the lines.

  1. Sending through API

Sending through the API is done using the Payment Request action, which also requires a PIN and confirmation. After sending, the status of the payment is changed to Sent Request. This status indicates that the bank has accepted the payment, but validations are ongoing.

Both payment methods are the same, including the checks of what should be filled in the basic fields. There are additional checks performed by Citibank.

Payment Status:

  • Payments sent through the API are verified by the system in the background, attempting to download the payment status.

  • If you need to request the status download manually, you can do so by selecting the appropriate action called Check Payment Status from the Related drop-down menu, Payments and CitiBank.

How to re-export payment file in case of error

When the payment file is exported, a check is performed on the Citibank side when the payment file is imported into the bank.

It may happen that the bank's system finds an error in some of the fields of the order. It is not possible to check all the consistencies at the bank level, Citibank does not even publish them all. Therefore, you may need to edit and re-export the payment file from Business Central.

Import bank statements

There are two methods of importing bank statements:

  1. Import of a file

If the API is not available, you can import the file using the standard General Journal option (depending on the Business Central localization). For this step, you need to set up a Data Exchange Definition for Citibank bank statement processing.

  1. Importing through API

If an API connection is available, the download will be done automatically each day via the appropriate Job Queue Entry. If statements need to be downloaded manually, this can be done on the Bank Account Card.