🚀 Akku Payment API Documentation

Base URL: https://pay.chargeakku.com/api/v1
Current Version: v1
Status: ✅ Server is running
Yapily Integration: ✅ Configured

📋 Quick Start

This API enables payment processing through multiple banks via Open Banking. The flow is:

  1. Initiate Payment → Get authorization URL
  2. User Authorization → User logs into their bank
  3. Execute Payment → Complete the payment
  4. Check Status → Monitor payment status

🔗 API Endpoints

GET /api/v1/institutions

List all available banks/institutions.

Response: 
{
  "success": true,
  "data": [
    {
      "id": "modelo-sandbox",
      "name": "Modelo Bank",
      "fullName": "Modelo Sandbox Bank",
      "countries": ["GB"],
      "media": [...]
    }
  ]
}

GET /api/v1/institutions/:institutionId

Get details for a specific institution.

Example: GET /api/v1/institutions/modelo-sandbox

POST /api/v1/payments/initiate Main

Initiate a new payment. Returns an authorization URL for the user.

Request Body: 
{
  "institutionId": "modelo-sandbox",
  "amount": 10.50,
  "currency": "GBP",
  "reference": "Test Payment",
  "callbackUrl": "myapp://payment-callback" // Optional
}
Response: 
{
  "success": true,
  "data": {
    "sessionId": "abc123...",
    "authorisationUrl": "https://auth.yapily.com/...",
    "consentId": "xyz789..."
  }
}
📱 Mobile App Flow:
1. Call this endpoint from your app
2. Open authorisationUrl in a browser/webview
3. User logs into their bank and authorizes
4. Bank redirects to your callbackUrl with consent token
5. Extract the consent parameter from callback

POST /api/v1/payments/execute Main

Execute the payment after user authorization.

Request Body: 
{
  "sessionId": "abc123...",
  "consentToken": "eyJhbGc..."
}
Response: 
{
  "success": true,
  "data": {
    "paymentId": "pay_123...",
    "status": "PENDING",
    "amount": 10.50,
    "currency": "GBP",
    "reference": "Test Payment",
    "institutionId": "modelo-sandbox",
    "createdAt": "2025-10-19T..."
  }
}

GET /api/v1/payments/:sessionId/status

Check payment status.

Example: GET /api/v1/payments/abc123/status Response: 
{
  "success": true,
  "data": {
    "sessionId": "abc123...",
    "paymentId": "pay_123...",
    "status": "COMPLETED",
    "amount": 10.50,
    "currency": "GBP",
    "reference": "Test Payment",
    "institutionId": "modelo-sandbox",
    "payee": {...},
    "payer": {...},
    "createdAt": "2025-10-19T...",
    "statusDetails": {...}
  }
}

GET /api/v1/sessions/:sessionId

Get session details (without querying Yapily).

🏦 Supported Banks

📱 Mobile Integration Example (React Native)

// 1. Initiate payment
const response = await fetch('https://pay.chargeakku.com/api/v1/payments/initiate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    institutionId: 'modelo-sandbox',
    amount: 10.50,
    currency: 'GBP',
    reference: 'App Payment',
    callbackUrl: 'myapp://payment-callback'
  })
});

const { data } = await response.json();
const { sessionId, authorisationUrl } = data;

// 2. Open bank authorization
Linking.openURL(authorisationUrl);

// 3. Handle callback (in your deep link handler)
const handleDeepLink = async (url) => {
  const params = new URL(url).searchParams;
  const consentToken = params.get('consent');
  
  // 4. Execute payment
  await fetch('https://pay.chargeakku.com/api/v1/payments/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ sessionId, consentToken })
  });
  
  // 5. Check status
  const status = await fetch(`https://pay.chargeakku.com/api/v1/payments/${sessionId}/status`);
  const { data: payment } = await status.json();
  console.log('Payment status:', payment.status);
};

⚠️ Error Handling

All errors return the following format:

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message",
  "details": {...} // Optional additional details
}

🔧 Configuration

Set these environment variables in your .env file:

YAPILY_APP_ID=your_app_id
YAPILY_APP_SECRET=your_secret
PORT=8765
BASE_URL=https://pay.chargeakku.com
CALLBACK_URL=https://pay.chargeakku.com/payment-callback

📚 Resources

⚠️ Production Considerations:
• Replace in-memory session storage with Redis/database
• Add authentication/API keys for your endpoints
• Implement rate limiting
• Use HTTPS for all communications
• Register your callback URL in Yapily Dashboard