@vulog/aima-payment

Payment management module for the AIMA platform. This module provides functionality to handle payments, setup intents, payment methods, and trip payments.

Installation

``bash
npm install @vulog/aima-client @vulog/aima-core @vulog/aima-payment
`

Usage

$3

`javascript
import { getClient } from '@vulog/aima-client';
import {
getSetupIntent,
getPaymentMethodDetailsForUser,
getSynchronize,
payATrip
} from '@vulog/aima-payment';

const client = getClient({
apiKey: 'your-api-key',
baseUrl: 'https://your-api-base-url',
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
fleetId: 'your-fleet-id',
});
`

API Reference

$3

#### getSetupIntent

Create a setup intent for payment method configuration.

`javascript
const setupIntent = await getSetupIntent(client, 'user-uuid-here');
`

Parameters:
- client: AIMA client instance
- entityId: User UUID

Returns: Setup intent object for payment method configuration

#### getPaymentMethodDetailsForUser

Retrieve payment method details for a specific user.

`javascript
const paymentMethods = await getPaymentMethodDetailsForUser(client, 'user-uuid-here');
`

Parameters:
- client: AIMA client instance
- entityId: User UUID

Returns: Array of user's payment methods

$3

#### payATrip

Process payment for a trip.

`javascript
const paymentResult = await payATrip(client, {
tripId: 'trip-uuid-here',
paymentMethodId: 'payment-method-id-here',
amount: 25.50,
currency: 'EUR'
});
`

Parameters:
- client: AIMA client instance
- paymentData: Payment configuration object
- tripId: Trip identifier
- paymentMethodId: Payment method identifier
- amount: Payment amount
- currency: Currency code

Returns: Payment processing result

#### getSynchronize

Synchronize payment data.

`javascript
const syncResult = await getSynchronize(client, {
entityId: 'user-uuid-here',
lastSyncDate: '2024-01-01T00:00:00Z'
});
`

Parameters:
- client: AIMA client instance
- syncData: Synchronization configuration
- entityId: User UUID
- lastSyncDate: Last synchronization date

Returns: Synchronization result

Types

$3

`typescript
interface SetupIntent {
id: string;
clientSecret: string;
status: 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'succeeded' | 'canceled';
paymentMethodTypes: string[];
createdAt: string;
updatedAt: string;
}
`

$3

`typescript
interface PaymentMethod {
id: string;
type: 'card' | 'bank_account' | 'sepa_debit';
card?: {
brand: string;
last4: string;
expMonth: number;
expYear: number;
};
bankAccount?: {
bankName: string;
last4: string;
routingNumber: string;
};
isDefault: boolean;
createdAt: string;
updatedAt: string;
}
`

$3

`typescript
interface PaymentResult {
id: string;
status: 'succeeded' | 'failed' | 'pending' | 'canceled';
amount: number;
currency: string;
paymentMethodId: string;
tripId: string;
errorMessage?: string;
createdAt: string;
}
`

Error Handling

All functions include validation and will throw appropriate errors if:
- Required parameters are missing
- Invalid user or trip IDs are provided
- Payment processing fails
- Network errors occur

Examples

$3

`javascript
import { getClient } from '@vulog/aima-client';
import {
getSetupIntent,
getPaymentMethodDetailsForUser,
payATrip
} from '@vulog/aima-payment';

const client = getClient({
apiKey: 'your-api-key',
baseUrl: 'https://your-api-base-url',
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
fleetId: 'your-fleet-id',
});

async function paymentWorkflow() {
try {
const userId = 'user-uuid-here';

// Create setup intent for new payment method
const setupIntent = await getSetupIntent(client, userId);
console.log('Setup intent created:', setupIntent);

// Get user's existing payment methods
const paymentMethods = await getPaymentMethodDetailsForUser(client, userId);
console.log(User has ${paymentMethods.length} payment methods);

// Process trip payment
const paymentResult = await payATrip(client, {
tripId: 'trip-uuid-here',
paymentMethodId: paymentMethods[0].id,
amount: 25.50,
currency: 'EUR'
});

console.log('Payment processed:', paymentResult);

return { setupIntent, paymentMethods, paymentResult };
} catch (error) {
console.error('Payment workflow error:', error);
throw error;
}
}
`

$3

`javascript
async function managePaymentMethods(client, userId) {
try {
const paymentMethods = await getPaymentMethodDetailsForUser(client, userId);

const analysis = {
totalMethods: paymentMethods.length,
defaultMethod: paymentMethods.find(pm => pm.isDefault),
cardMethods: paymentMethods.filter(pm => pm.type === 'card'),
bankMethods: paymentMethods.filter(pm => pm.type === 'bank_account'),
sepaMethods: paymentMethods.filter(pm => pm.type === 'sepa_debit')
};

console.log('Payment Method Analysis:');
console.log(Total Methods: ${analysis.totalMethods});
console.log(Default Method: ${analysis.defaultMethod?.id || 'None'});
console.log(Card Methods: ${analysis.cardMethods.length});
console.log(Bank Methods: ${analysis.bankMethods.length});
console.log(SEPA Methods: ${analysis.sepaMethods.length});

return analysis;
} catch (error) {
console.error('Payment method management error:', error);
throw error;
}
}
`

$3

`javascript
async function processTripPayment(client, tripId, userId, amount, currency = 'EUR') {
try {
// Get user's payment methods
const paymentMethods = await getPaymentMethodDetailsForUser(client, userId);

if (paymentMethods.length === 0) {
throw new Error('No payment methods found for user');
}

// Use default payment method or first available
const paymentMethod = paymentMethods.find(pm => pm.isDefault) || paymentMethods[0];

// Process payment
const paymentResult = await payATrip(client, {
tripId,
paymentMethodId: paymentMethod.id,
amount,
currency
});

if (paymentResult.status === 'succeeded') {
console.log(Payment successful: ${amount} ${currency} for trip ${tripId});
} else {
console.log(Payment failed: ${paymentResult.errorMessage});
}

return paymentResult;
} catch (error) {
console.error('Trip payment processing error:', error);
throw error;
}
}
`

$3

`javascript
async function analyzePayments(client, userId) {
try {
// This would require additional API endpoints for payment history
// For now, we'll demonstrate with payment methods
const paymentMethods = await getPaymentMethodDetailsForUser(client, userId);

const analysis = {
userPaymentMethods: paymentMethods.length,
hasDefaultMethod: paymentMethods.some(pm => pm.isDefault),
supportedTypes: [...new Set(paymentMethods.map(pm => pm.type))],
cardBrands: paymentMethods
.filter(pm => pm.card)
.map(pm => pm.card.brand),
recentMethods: paymentMethods
.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
.slice(0, 3)
};

console.log('Payment Analysis:');
console.log(Payment Methods: ${analysis.userPaymentMethods});
console.log(Has Default: ${analysis.hasDefaultMethod});
console.log(Supported Types: ${analysis.supportedTypes.join(', ')});
console.log(Card Brands: ${analysis.cardBrands.join(', ')});
console.log('Recent Methods:', analysis.recentMethods);

return analysis;
} catch (error) {
console.error('Payment analysis error:', error);
throw error;
}
}
``