> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/payments-integrations/yapily.md).

# Yapily

## Synchronisation scope

| Synchronisation            | Direction        | When it runs                                                          |
| -------------------------- | ---------------- | --------------------------------------------------------------------- |
| Bank accounts              | Yapily → Younium | When a bank is connected, and on demand from the integration settings |
| Incoming bank transactions | Yapily → Younium | On demand for a bank account, optionally from a chosen date           |
| Consent reconfirmation     | Younium → Yapily | On demand, for a connected bank                                       |

Not in scope: payment initiation, outgoing bank transactions, banks outside the United Kingdom.

***

## Overview

The Yapily integration connects Younium to UK banks through **Yapily** (open banking, account information). A customer connects a bank, Younium imports the incoming transactions for the bank accounts they choose, and the payment matching engine reconciles them against invoices, in the same way as for Aiia and the other bank imports.

Bank selection and consent happen on Yapily's hosted pages, outside Younium. Younium is registered with the FCA as an agent of Yapily Connect Ltd, so the journey opens with an agency disclosure inside Younium before the customer is sent to Yapily.

The integration is enabled per legal entity. A legal entity can hold several connected banks, one connection per bank.

***

## Authentication

An administrator connects a bank from the integration settings of a legal entity, choosing whether to connect to Yapily's sandbox or to production. Younium sends them to Yapily, where they choose their bank and approve access; Yapily returns them to Younium and the connection is live. Younium does not ask for bank credentials at any point.

Each connection is for one bank. Test and live connections stay separate, and a legal entity can hold a sandbox bank and a live bank at the same time.

If the customer does not finish the journey, Younium discards the unfinished attempt (after about 15 minutes, or when the next attempt starts). A connection that completed at Yapily but never returned to Younium can be resolved on demand from the integration settings.

> **Note on consent expiry:** A bank can withdraw or expire access. When it does, imports for that bank stop and the connection is shown as disconnected until it is reconnected. Younium reads access that the bank refuses as a request to reconnect, including when the actual cause is the application's scope at Yapily.

### Permissions

Viewing the integration needs the **View Yapily integration** permission. Connecting, importing, reconfirming and disconnecting need **Manage Yapily integration**.

### Settings

| Setting            | Description                                                                                         | Default                        |
| ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------ |
| Yapily environment | Sandbox or production, chosen when connecting a bank. Recorded only once Yapily accepts the request | None until a bank is connected |

***

## Sandbox vs. Production

Sandbox and production are separate Yapily environments with separate application credentials. The environment belongs to each bank connection rather than the legal entity, so moving from testing to live means connecting the bank again. In the sandbox, a single import can be capped to keep trial runs small; production imports are never capped.

***

## Activation

Connecting starts a Yapily hosted consent journey for the United Kingdom. Connecting imports nothing by itself. After a bank is connected, the customer fetches its bank accounts and assigns a Younium payment method to each account they want transactions imported for. An account without a payment method cannot be imported, and the payment method must have a financial account, because matching needs one.

Savings pots and similar sub-accounts are not offered, because payments are not reconciled against them. Only the last four digits of an account number (or the IBAN, where the bank gives nothing else) are stored.

***

## Reconfirmation and reconnecting

For UK banks, reconfirming consent keeps access alive for a further 90 days without the customer signing in at the bank again. Younium records the new date.

A bank whose consent has expired or been rejected can be reconnected. Younium withdraws the old consent first, then returns the customer to Yapily with the bank already selected so bank selection is skipped; if Yapily will not accept that bank, the customer picks it again from Yapily's list. Reconnecting never leaves two connections for the same bank.

***

## Connection health

The payments page shows one health indicator per bank account.

| Health          | When                                                                             |
| --------------- | -------------------------------------------------------------------------------- |
| Disconnected    | The consent has expired or been rejected, or the bank has asked for reconnection |
| Never imported  | No import has run for the account yet                                            |
| Healthy         | The last import was within the last day                                          |
| Needs attention | The last import is more than a day old, or reconfirmation is due within 14 days  |

Where the integration is not enabled for a legal entity, the status reports it as disabled rather than failing.

***

## Deactivation

Disconnecting a bank always withdraws the consent at Yapily and, where the bank supports it, at the bank, and then removes the connection and its bank accounts together with their payment method assignments. A consent the bank has already dropped counts as withdrawn, so an expired connection can still be removed. If Yapily or the bank refuses the withdrawal, the connection stays in place so the customer can retry. Payments already imported and matched are unaffected.

***

## Eligibility and scope

### Transaction import

| Rule                 | Behaviour                                                                                                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Direction            | Only incoming transactions (amount greater than zero) are imported                                                                                                                                                                                         |
| Pending transactions | Not imported. A bank can still change the amount, reference or date before settlement, and the booked transaction often reappears under a new identifier, which would let the same money settle an invoice twice. A transaction with no status is imported |
| Import window        | From 3 days before the previous import, to catch late bookings. The first import takes what the bank offers by default. A chosen start date overrides this                                                                                                 |
| Duplicates           | A transaction already imported is skipped, using the bank's transaction identifier, or Yapily's transaction hash where the bank sends none. A transaction returned twice in one fetch is imported once                                                     |
| Concurrency          | One import runs at a time per bank account                                                                                                                                                                                                                 |

> **Note on deleted payments:** Because imports overlap by 3 days, a payment deleted in Younium within that window is imported again.

The result of an import reports how many transactions were read, how many were booked incoming payments, and how many payments were imported.

***

## Field mapping

### Bank accounts

| Younium field            | Yapily field                       |
| ------------------------ | ---------------------------------- |
| **Name of bank account** | Account name                       |
| **Bank**                 | Institution                        |
| **Currency**             | Account currency                   |
| **Payment method**       | Chosen in Younium, not from Yapily |

### Incoming payment

| Younium field       | Yapily field                                                                              |
| ------------------- | ----------------------------------------------------------------------------------------- |
| Amount              | Transaction amount                                                                        |
| Currency            | Transaction currency, otherwise the bank account currency                                 |
| Payment reference   | Reference, otherwise description, otherwise transaction information                       |
| Payment description | Description                                                                               |
| Payer information   | Transaction information, otherwise description                                            |
| Payer name          | Payer name                                                                                |
| Payment date        | Booking date, otherwise value date, otherwise transaction date, otherwise the import time |
| External bank id    | Transaction id, otherwise Yapily's transaction hash                                       |

The matching engine matches on the payment reference, so a bank that sends no reference matches on its description. The bank's own exchange rate is not used; base currency amounts are calculated from the invoice. The full Yapily transaction is kept with the payment.

### Payment batch

| Younium field     | Value                                       |
| ----------------- | ------------------------------------------- |
| Batch description | `Transactions from {bank account name}`     |
| Source            | `Yapily import`                             |
| Payment method    | Payment method assigned to the bank account |
| Financial account | Taken from that payment method              |

### Batch log

| Younium field              | Source                  |
| -------------------------- | ----------------------- |
| **Batch number**           | Generated payment batch |
| **Bank account**           | Bank account name       |
| **Number of transactions** | Payments in the batch   |
| **Description**            | Batch description       |
| **Total batch amount**     | Batch total             |
| **Currency**               | Bank account currency   |
| **Imported to Younium**    | Time of import          |

***

## Events and jobs

| Trigger                                         | Behaviour                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| Manual action: connect a bank                   | Starts the Yapily hosted journey                                    |
| Manual action: fetch bank accounts              | Refreshes accounts for one bank, or for every authorised connection |
| Manual action: import transactions              | Imports for one bank account, optionally from a chosen date         |
| Manual action: reconfirm, reconnect, disconnect | As described above                                                  |

Younium has no scheduled import for Yapily; imports run when a user starts them.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/payments-integrations/yapily.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
