Skip to main content
Version: v2alpha1

Enrichment with bank files using the API

Before you start​

  • The enrichment process add additional information to existing bank transactions from your bank account, refer to bank connectivity guide to connect your bank account to the getpaid's platform and start ingesting bank transactions.

Steps​

1. Upload bank transactions file​

Upload a bank transactions file by calling POST /bank_transactions/documents.

The upload of the file does not imply the import of the file, this step will provide the id of the document to start the import process in the next step facilitating additional metadata to improve the enrichment process.

In this scenario, the file uploaded is a AEB43 CSV file named AEB43_20240805.csv.

Request​

POST /bank_transactions/documents
POST /v2alpha1/bank_transactions/documents HTTP/1.1
Host: api.getpaid.io
Content-Length: 296
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="AEB43_20240805.csv"

Response​

201 Created
{
  "id": "doc_4wt0wrfqwz0vkatave0fkjg046"
}

2. Import bank transactions file​

Once the bank transactions file is uploaded to getpaid's solution, you can continue with the import process by calling POST /bank_transactions/imports endpoint.

The request can include additional information that can improve the enrichment process and making it more accurate:

  • The document.format skips the automatic detection of the format of the uploaded file when it is known.
  • The payment_instruments list narrows the bank accounts used to search for related bank transactions to enrich, indicating to which account and payment instrument the bank file is related to.

The usage of webhooks is recommended to receive real-time notifications about the changes on the import.

In this scenario:

  • The format is known so it will be indicated. It is an AEB43 file (aeb43).
  • The file is related to a payment instrument pai_1a6po0p7zqv1q2arfsyr9548q created for the account acc_44678r08jtm8zbt227tzhc4nw5.
  • The webhook URL is configured to receive the notifications.

Request​

POST /bank_transactions/imports
{
  "document": {
    "id": "doc_4wt0wrfqwz0vkatave0fkjg046",
    "format": "aeb43"
  },
  "payment_instruments": [
    {
      "account_id": "acc_44678r08jtm8zbt227tzhc4nw5",
      "id": "pai_1a6po0p7zqv1q2arfsyr9548q"
    }
  ],
  "urls": {
    "webhook": "https://webhooks.platform.io/getpaid/bank_transactions_imports"
  }
}

Response​

202 Accepted
{
  "id": "ipt_4nmd4fgtv79406k456c7k42sw4",
  "status": "pending",
  [...]
}

3. Notify about bank transactions import validated​

Bank files uploaded are validated as soon as they are accepted into the getpaid's solution to verify if the format is one of the support file formats and, if the format was not indicated in the import request, to infer the file format.

If the validation is successful, a bank_transactions_import_error webhook is sent to the configured webhook URL.

4. Enrich bank transactions​

After the file validation, getpaid parses the document uploaded to extract each of the bank transactions with additional information and searches for the related bank transaction in our system ingested via a bank connection.

Even if the file uploaded is in the correct format, the import can fail because of the imposibility of matching the file to your bank account or to find bank transactions in the getpaid's platform. These errors can be retried after connecting your bank account or waiting for the bank transactions ingestion.

5. Notify about bank transactions import completed​

If the enrichment can be completed, even if non transactions could be enriched, for example, because all transactions are not relevant for the receivables reconciliation, a bank_transactions_import_completed webhook is sent to the configured webhook URL with the enrichment summary.

6. Notify about bank transactions import error​

If the enrichment process cannot be completed, a bank_transactions_import_error webhook is sent to the configured webhook URL.

Errors that are related with the synchronization of the bank transactions can be solved retrying but file integrity, structure, and validation errors may require reviwing the file before uploading it again.

7. List bank transactions imports​

Bank transactions enrichment webhook notifications cover all the status updates for the bank files enrichment process but, if needed, the import history can be retrieved by calling GET /bank_transactions/imports endpoint.

8. Get bank transactions import details​

The details of each import is notified as soon as it changes via the bank transactions enrichment webhook notifications but, if needed, the details of each import can be retrieved by calling GET /bank_transactions/imports/{import_id} endpoint.