---
name: Yapily
description: Use when building payment acceptance, accessing financial data, enriching transactions, or verifying account ownership via open banking. Agents should reach for this skill when integrating bank-to-bank payments, retrieving account/transaction data with user consent, or implementing recurring payment mandates across 2000+ UK and European institutions.
metadata:
    mintlify-proj: yapily
    version: "1.0"
---

# Yapily Open Banking API

## Product summary

Yapily connects applications to 2000+ banks across the UK and 20+ European countries through a single open banking API. Use Yapily to accept bank-to-bank payments (single, bulk, scheduled, periodic, recurring), retrieve financial data (accounts, balances, transactions), enrich transaction data with merchant details and categorisation, and verify account ownership.

**Key files and endpoints:**
- API base: `https://api.yapily.com`
- Authentication: HTTP Basic Auth (Application ID + Application Secret)
- Console: `https://console.yapily.com/` (manage applications, institutions, credentials)
- Sandbox: Modelo Sandbox (preconfigured, no setup required)
- Primary docs: https://docs.yapily.com

**Two integration approaches:**
1. **Hosted Pages** (fastest): Pre-built UI for payments and data consent. Handles bank selection, SCA, redirects. Returns consent token for data retrieval.
2. **Direct API** (full control): Build your own UI. Supports all payment types, all countries, custom flows.

## When to use

Reach for this skill when:
- Building payment acceptance (single, bulk, scheduled, periodic, or recurring payments)
- Retrieving account data, balances, or transaction history with user consent
- Enriching transaction data with merchant details or spending categories
- Verifying account ownership or customer identity
- Integrating with UK or European banks (PSD2/PSRs compliance)
- Testing open banking flows in sandbox before going live
- Handling consent lifecycle, payment status monitoring, or webhook notifications
- Choosing between Hosted Pages (quick launch) vs Direct API (custom UX)

Do not use for: Card payments, non-bank payment methods, or institutions outside UK/Europe.

## Quick reference

### Authentication
```bash
# Basic Auth with Application ID and Secret
curl -u APPLICATION_ID:APPLICATION_SECRET https://api.yapily.com/institutions

# Or use in headers
Authorization: Basic base64(APPLICATION_ID:APPLICATION_SECRET)
```

### Core API endpoints

| Task | Endpoint | Method |
|------|----------|--------|
| List institutions | `/institutions` | GET |
| Create payment authorisation | `/payment-auth-requests` | POST |
| Create account data authorisation | `/account-auth-requests` | POST |
| Exchange auth code for consent token | `/consent-auth-code` | POST |
| Create single payment | `/payments` | POST |
| Get payment status | `/payments/{paymentId}/details` | GET |
| Get accounts | `/accounts` | GET |
| Get transactions | `/accounts/{accountId}/transactions` | GET |
| Create bulk payment | `/bulk-payments` | POST |
| Create VRP consent | `/variable-recurring-payments/sweeping/consents` | POST |

### Required headers for data/payment requests

| Header | Required | Example |
|--------|----------|---------|
| `consent` | Yes | Consent token from authorisation |
| `psu-id` | Conditional | User's bank login ID (check institution config) |
| `psu-corporate-id` | Conditional | Business account login ID |
| `psu-ip-address` | Conditional | User's IP address |

### Consent statuses (understand the lifecycle)

| Status | Meaning | Action |
|--------|---------|--------|
| `AWAITING_AUTHORIZATION` | Waiting for user approval | Redirect to `authorisationUrl` |
| `AUTHORIZED` | User approved, token valid | Use token for API calls |
| `REJECTED` | User declined at bank | Show error, offer retry |
| `EXPIRED` | Consent time limit reached | Request re-authorisation |
| `AWAITING_SCA_CODE` | Embedded flow: waiting for SCA code | Submit code via PUT endpoint |
| `AWAITING_SCA_METHOD` | Embedded flow: user selects SCA method | Present options, submit selection |
| `CONSUMED` | Payment executed (terminal) | No further action needed |

### Payment statuses

| Status | Meaning | Next step |
|--------|---------|-----------|
| `PENDING` | Submitted to bank, awaiting processing | Poll or wait for webhook |
| `COMPLETED` | Payment settled (terminal) | Confirm with user |
| `FAILED` | Payment rejected (terminal) | Show error, offer retry |
| `DECLINED` | Bank declined (terminal) | Check reason, retry if appropriate |

## Decision guidance

### When to use Hosted Pages vs Direct API

| Scenario | Recommendation | Why |
|----------|---|---|
| Single payments, quick launch | Hosted Pages | No frontend work, handles SCA/redirects |
| Data consent only | Hosted Pages for consent, API for retrieval | Hosted manages auth, you retrieve data |
| Bulk, scheduled, periodic, international payments | Direct API | Hosted doesn't support these yet |
| Custom payment UI required | Direct API | Full control over experience |
| Native mobile app | Direct API | Hosted is web redirect only |
| Country not in Hosted coverage | Direct API | Hosted limited to 9 countries |
| MVP or testing | Hosted Pages | Fastest to validate |

### When to use redirect vs embedded auth flow

| Condition | Flow | Reason |
|-----------|------|--------|
| Most institutions, standard UX | Redirect | Most common, banks handle auth |
| Custom in-app experience required | Embedded | You control SCA method selection and code entry |
| Mobile app | Redirect or Embedded | Depends on bank support |
| Check institution config | Either | Some banks support only one |

### Polling vs webhooks for payment status

| Approach | Use when | Pros | Cons |
|----------|----------|------|------|
| Webhooks | Real-time updates needed | Immediate, fewer API calls, better UX | Requires HTTPS endpoint, setup overhead |
| Polling | Simple integration, low volume | No infrastructure needed | Delays, higher API usage, rate limit risk |

## Workflow

### 1. Set up environment
1. Create Yapily Console account at https://console.yapily.com/
2. Create an Application (get Application ID and Secret)
3. Add Modelo Sandbox to test (preconfigured, no credentials needed)
4. Store credentials securely (environment variables, never in code)

### 2. Make a payment (Hosted Pages - fastest)
1. Create hosted payment request: `POST /hosted-payment-requests`
2. Receive `redirectUrl` in response
3. Redirect user to URL
4. User selects bank, authenticates, approves payment
5. User redirected back to your callback URL
6. Receive webhook notification when payment completes
7. Optionally poll `GET /hosted-payment-requests/{requestId}` for status

### 3. Make a payment (Direct API - full control)
1. Get list of institutions: `GET /institutions` (filter by `CREATE_DOMESTIC_SINGLE_PAYMENT` feature)
2. Create payment authorisation: `POST /payment-auth-requests` with institution ID, callback URL, payment details
3. Receive `authorisationUrl` in response
4. Redirect user to bank
5. User authenticates and approves
6. Bank redirects to your callback with `auth-code` and `auth-state`
7. Exchange code for consent token: `POST /consent-auth-code` with auth-code and auth-state
8. Create payment: `POST /payments` with consent token and payment details
9. Poll or wait for webhook: `GET /payments/{paymentId}/details`

### 4. Retrieve account data
1. Create account authorisation: `POST /account-auth-requests` with institution ID, callback URL, features (ACCOUNTS, ACCOUNT_TRANSACTIONS, etc.)
2. Redirect user to bank
3. User authenticates and approves
4. Exchange auth code for consent token: `POST /consent-auth-code`
5. Get accounts: `GET /accounts` with consent token header
6. Get transactions: `GET /accounts/{accountId}/transactions` with consent token header
7. Consent valid for 90 days (UK) or 180 days (EEA); request re-authorisation if expired

### 5. Set up webhooks for real-time updates
1. Set up HTTPS endpoint on your server (must return 200 OK within 1 second)
2. Register webhook: `POST /webhooks` with event type (e.g., `payment_status.completed.v1`)
3. Yapily sends POST to your endpoint when event occurs
4. Parse webhook payload, extract `event.paymentId` or `event.consentId`
5. Verify webhook signature if needed (check docs)
6. Respond with 200 OK

## Common gotchas

- **Missing consent header**: All data and payment requests require `consent` header with token. Omitting it returns 401.
- **Expired consent**: Consents expire (90 days UK, 180 days EEA). Expired consents return error. Request re-authorisation before expiry.
- **Wrong institution features**: Not all institutions support all features (e.g., bulk payments, VRP). Filter institutions by feature before offering to user.
- **PSU identifiers required for some banks**: Some institutions require `psu-id`, `psu-corporate-id`, or `psu-ip-address` headers. Check institution config; omitting required headers causes 400 errors.
- **Multiple consents from one auth**: Some banks (e.g., AMEX) return multiple consents for one authorisation. Use callback URL or polling to capture all consent IDs.
- **Payment status doesn't reach settlement**: EU banks often stop reporting at ACCP (accepted for clearing) not ACSC (settled). Use AIS (account data) to confirm settlement by checking balance/transactions.
- **Sandbox vs live**: Sandbox payments may complete instantly. Real banks take hours/days. Test with realistic timings.
- **Storing credentials**: Never commit Application Secret to version control. Use environment variables or secure vaults.
- **Callback URL must be HTTPS**: Redirect and callback flows require valid HTTPS URLs. Self-signed certificates not supported.
- **Hosted Pages limited coverage**: Hosted Pages only supports 9 countries and single payments. Use Direct API for bulk, scheduled, periodic, international, or unsupported countries.

## Verification checklist

Before submitting payment or data access work:

- [ ] Application ID and Secret stored securely (not in code)
- [ ] Correct institution selected (supports required feature)
- [ ] Consent token included in request headers
- [ ] Callback URL is valid HTTPS (not localhost, not self-signed)
- [ ] Payment/data request body matches API spec (required fields present)
- [ ] Account identifications correct (IBAN, sort code + account number, etc.)
- [ ] Payee/payer details complete (name, account, address if international)
- [ ] For international payments: payee address included
- [ ] For embedded flow: SCA method selection and code submission logic implemented
- [ ] Webhook endpoint returns 200 OK within 1 second
- [ ] Error handling covers consent rejection, expiry, and payment failure
- [ ] Tested in Modelo Sandbox before going live
- [ ] Payment status monitoring logic handles PENDING, COMPLETED, FAILED states
- [ ] Consent expiry handled (re-authorisation requested before 90/180 days)

## Resources

**Comprehensive navigation:** https://docs.yapily.com/llms.txt

**Critical documentation pages:**
- [Getting Started](https://docs.yapily.com/getting-started/overview) — Choose integration approach, set up environment
- [Open Banking 101](https://docs.yapily.com/concepts/open-banking-101) — Understand roles, consent, auth flows
- [Hosted vs API](https://docs.yapily.com/concepts/hosted-vs-api) — Decision guide for integration approach
- [API Reference](https://docs.yapily.com/api-reference/introduction) — Full endpoint documentation
- [Payment Status](https://docs.yapily.com/payments/payment-resources/payment-status) — Payment lifecycle and monitoring
- [Consent Lifecycle](https://docs.yapily.com/concepts/consent-lifecycle) — Consent statuses and management
- [Error Handling](https://docs.yapily.com/resources/errors) — Error codes and troubleshooting
- [Webhooks](https://docs.yapily.com/tools-and-services/webhooks/introduction) — Real-time event notifications
- [Sandbox](https://docs.yapily.com/resources/sandbox/overview) — Testing environment and credentials

---

> For additional documentation and navigation, see: https://docs.yapily.com/llms.txt