---
name: Yapily
description: Use when building open banking integrations for payments, financial data access, transaction enrichment, or account verification. Reach for this skill when implementing bank-to-bank payments, retrieving account data with user consent, enriching transactions with merchant details, or verifying account ownership across UK and European banks.
metadata:
    mintlify-proj: yapily
    version: "1.0"
---

# Yapily Skill

## Product Summary

Yapily is an open banking API that connects applications to 2000+ banks across the UK and Europe through a single integration. It enables bank-to-bank payments (single, scheduled, periodic, bulk, and variable recurring), financial data access (accounts, balances, transactions), transaction enrichment and categorisation, and account verification. The API uses HTTP Basic Authentication with Application ID and Secret. Key entry points: `https://api.yapily.com` for REST endpoints, Yapily Console at `https://console.yapily.com` for credential management and institution registration. Primary documentation: https://docs.yapily.com

## When to Use

Use Yapily when:
- Building payment acceptance flows (single payments, recurring payments, bulk payments)
- Retrieving customer financial data (accounts, balances, transactions) with consent
- Enriching transaction data with merchant details and spending categories
- Verifying account ownership or customer identity
- Operating in the UK or 20+ European countries
- Choosing between pre-built consent flows (Hosted Pages) or custom API integration

Do not use Yapily for: card payments, cryptocurrency, non-regulated payment services, or countries outside UK/Europe coverage.

## Quick Reference

### Authentication
All API requests require HTTP Basic Auth:
- Username: Application ID
- Password: Application Secret
- Store credentials in environment variables, never in code

### Core API Endpoints
| Endpoint | Purpose |
|----------|---------|
| `POST /account-auth-requests` | Create account data consent request |
| `POST /payment-auth-requests` | Create payment consent request |
| `POST /consent-auth-code` | Exchange OAuth2 code for consent token |
| `GET /accounts` | List user accounts (requires consent token) |
| `GET /accounts/{id}/transactions` | Get account transactions (requires consent token) |
| `POST /payments` | Initiate single payment (requires consent token) |
| `GET /payments/{id}/details` | Check payment status |
| `POST /webhook/events` | Register webhook for notifications |

### Required Headers
| Header | When Required | Example |
|--------|---------------|---------|
| `Authorization` | All requests | `Basic base64(appId:appSecret)` |
| `consent` | Data/payment API calls | `Bearer {consentToken}` |
| `psu-id` | Some institutions (conditional) | User's bank login ID |

### Consent Token Lifecycle
- **AWAITING_AUTHORIZATION**: User must authenticate at bank
- **AUTHORIZED**: Token valid, ready for API calls
- **EXPIRED**: Reauthorisation needed (90 days UK, 180 days EEA)
- **REVOKED**: User revoked at bank, create new consent
- **REJECTED/FAILED**: User declined or error occurred

### Payment Types
| Type | Use Case | Hosted Pages | Direct API |
|------|----------|:---:|:---:|
| Single | Immediate payment | ✓ | ✓ |
| Scheduled | Future-dated payment | ✗ | ✓ |
| Periodic | Standing order/recurring | ✗ | ✓ |
| Bulk | Multiple payments at once | ✗ | ✓ |
| VRP | Variable recurring (UK only) | ✓ | ✓ |
| International | Cross-border payment | ✗ | ✓ |

## Decision Guidance

### When to Use Hosted Pages vs Direct API

| Scenario | Recommendation | Reason |
|----------|---|---|
| Single payments in UK/Germany/France/Benelux/Spain/Austria/Portugal | Hosted Pages | Fastest integration, no frontend work |
| Data consent in supported countries | Hosted Pages for consent + API for retrieval | Pre-built consent flow, then use API for data |
| Bulk, scheduled, periodic, or international payments | Direct API | Hosted Pages doesn't support these types |
| Country not in Hosted Pages coverage | Direct API | Must build custom flow |
| Native mobile app | Direct API | Hosted Pages is web-only redirect |
| Custom UI/branding beyond logo/colours | Direct API | Full control required |
| MVP or quick launch | Hosted Pages | Lowest friction, fastest to market |

### When to Use Webhooks vs Polling

| Scenario | Recommendation |
|----------|---|
| Production payment monitoring | Webhooks (real-time, fewer API calls) |
| Testing or low-volume | Polling (simpler, no endpoint setup) |
| High-volume payments | Webhooks (cost-effective, immediate updates) |
| No public endpoint available | Polling (fallback) |

### When to Use Which Authorization Flow

| Flow | When to Use |
|------|-------------|
| Redirect (single-redirect) | Most common; user redirected to bank, then back to your app |
| Embedded | Custom UI; you handle SCA method selection and code submission |
| Decoupled | User approves on another device; you poll for status |
| Pre-authorisation | Two-step flow; authenticate first, then collect SCA code |

## Workflow

### 1. Set Up Environment
- Create Yapily Console account at https://console.yapily.com
- Create an Application and download Application ID and Secret
- Store credentials in environment variables (never commit to version control)
- Register sandbox institution (e.g., Modelo Sandbox) for testing
- Test with cURL or Postman using Basic Auth

### 2. Choose Integration Path
- For single payments in supported countries: use Hosted Pages (fastest)
- For complex payments or custom UI: use Direct API
- For data access: use Hosted Pages for consent, then API for retrieval

### 3. Implement Authorization Flow
- Create authorization request: `POST /account-auth-requests` (data) or `POST /payment-auth-requests` (payment)
- Receive `authorisationUrl` and redirect user to bank
- User authenticates and approves at bank
- Bank redirects back to your callback URL with auth code
- Exchange code for consent token: `POST /consent-auth-code`
- Store consent token securely (valid 90 days UK, 180 days EEA)

### 4. Make API Calls with Consent Token
- Include consent token in `consent` header on all data/payment requests
- For data: call `GET /accounts`, `GET /accounts/{id}/transactions`, etc.
- For payments: call `POST /payments` with payment details
- Check institution-specific requirements (psu-id, address fields, etc.)

### 5. Monitor Status
- Set up webhooks: `POST /webhook/events` with callback URL and event categories
- Or poll payment status: `GET /payments/{id}/details` (not recommended for production)
- Handle payment statuses: PENDING → COMPLETED/FAILED
- For data, consent status: AUTHORIZED → EXPIRED (reauthorise if needed)

### 6. Handle Errors
- All errors include `tracingId` (save for support)
- Check `error.source` to identify if error is from USER, INSTITUTION, or YAPILY
- Review error code in `error.issues[].code` against error catalog
- Implement exponential backoff for retryable errors

## Common Gotchas

- **Credentials in code**: Never hardcode Application ID/Secret. Use environment variables. If exposed, revoke immediately in Console.
- **Consent token expiry**: Data consents expire after 90 days (UK) or 180 days (EEA). Implement reauthorisation flow or prompt user to reconnect.
- **Missing psu-id header**: Some institutions (especially Germany, France) require `psu-id` header. Check institution configuration before making requests.
- **Payment reference too long**: Payment reference limited to 18 characters. Truncate or reject longer values.
- **Bulk payment limits**: Max 50 payments per request; some banks have lower limits (e.g., Bankline: 3000-4000). Check institution constraints.
- **Polling instead of webhooks**: Polling increases API usage and delays status updates. Use webhooks for production.
- **Forgetting consent exchange**: After redirect, you must exchange auth code for consent token. Redirect alone does not give you access.
- **Using expired consent token**: Expired tokens return 401. Catch this and trigger reauthorisation flow.
- **Institution-specific field requirements**: IBAN required in Germany/France but not UK. Check `paymentFeatures` for each institution.
- **SCA exemptions not applied**: Some payments qualify for SCA exemption. If exemption not applied, user must complete SCA even for low-value payments.
- **Webhook signature verification skipped**: Always verify webhook signatures using the webhook secret. Unverified webhooks could be spoofed.

## Verification Checklist

Before submitting work with Yapily:

- [ ] Credentials stored in environment variables, not hardcoded
- [ ] Application ID and Secret downloaded and secured
- [ ] Sandbox institution registered (Modelo Sandbox or target bank)
- [ ] Authorization flow tested: consent request → redirect → callback → token exchange
- [ ] Consent token successfully obtained and stored
- [ ] API call made with consent token in header (data retrieval or payment initiation)
- [ ] Error handling implemented: check `tracingId`, `error.source`, and error codes
- [ ] Payment status monitored (webhooks preferred, or polling with exponential backoff)
- [ ] Consent expiry handled: reauthorisation flow or user reconnection prompt
- [ ] Institution-specific requirements checked (psu-id, address fields, payment limits)
- [ ] Webhook endpoint registered and signature verification implemented (if using webhooks)
- [ ] Tested with real institution in sandbox (not just Modelo)
- [ ] Error responses logged with `tracingId` for support troubleshooting

## Resources

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

**Critical documentation pages**:
1. [Getting Started](https://docs.yapily.com/getting-started/get-started) — Set up credentials and make first API call
2. [API Reference](https://docs.yapily.com/api-reference/introduction) — Complete endpoint documentation
3. [Hosted vs API Decision Guide](https://docs.yapily.com/concepts/hosted-vs-api) — Choose integration approach
4. [Consent Lifecycle](https://docs.yapily.com/concepts/consent-lifecycle) — Understand consent statuses and management
5. [Payment Status Monitoring](https://docs.yapily.com/payments/payment-resources/payment-status) — Track payment execution
6. [Error Handling](https://docs.yapily.com/resources/errors) — Error codes and troubleshooting
7. [Webhooks](https://docs.yapily.com/tools-and-services/webhooks/get-started) — Real-time event notifications

---

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