@vulog/aima-payment

Payment method management, setup intents, and trip payments.

Installation

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

Usage

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

const client = getClient({ ... });

const paymentDetail = await getPaymentMethodDetailsForUser(client, 'user-uuid');

const tripPayment = await payATrip(client, 'trip-id', {
    amountValue: 1500,
    scope: 'RENTAL',
    amountType: 'FIXED',
});

API Reference

getPaymentMethodDetailsForUser

getPaymentMethodDetailsForUser(client: Client, id: string): Promise<PaymentDetail | undefined>

Returns the 'Single'-profile payment detail for the given user. id must be a valid UUID. Returns undefined if not found.

| Param | Type | Description | | -------- | -------- | ------------------------ | | client | Client | Authenticated AIMA client | | id | string | User UUID |

Returns: Promise<PaymentDetail | undefined>

getSetupIntent

getSetupIntent(client: Client, userId: string, entityId: string, returnURL: string, browserInfos: BrowserInfos): Promise<SetupIntent>

Initiates a PSP setup intent for saving a payment method. All parameters are validated with Zod.

| Param | Type | Description | | -------------- | -------------- | ------------------------- | | client | Client | Authenticated AIMA client | | userId | string | User identifier | | entityId | string | Entity identifier | | returnURL | string | Return URL after 3DS | | browserInfos | BrowserInfos | Browser metadata for 3DS |

Returns: Promise<SetupIntent>

getSynchronize

getSynchronize(client: Client, userId: string, entityId: string, setupIntent: string): Promise<SynchronizeResponse | undefined>

Synchronizes the setup intent status with the PSP. Returns undefined if no result.

| Param | Type | Description | | --------------- | -------- | ------------------------- | | client | Client | Authenticated AIMA client | | userId | string | User identifier | | entityId | string | Entity identifier | | setupIntent | string | Setup intent identifier |

Returns: Promise<SynchronizeResponse | undefined>

payATrip

payATrip(client: Client, tripId: string, body: {
    online?: boolean;
    scope?: 'RENTAL' | 'DEPOSIT';
    amountType?: 'FIXED' | 'PERCENTAGE';
    amountValue: number;
    useSystemCredit?: boolean;
}): Promise<TripPayment>

Triggers a payment for a completed trip.

| Param | Type | Description | | --------------------- | ----------------------------- | ------------------------------------ | | client | Client | Authenticated AIMA client | | tripId | string | Trip identifier | | body.amountValue | number | Amount to charge (required) | | body.online | boolean? | Whether to process online | | body.scope | 'RENTAL' \| 'DEPOSIT'? | Payment scope | | body.amountType | 'FIXED' \| 'PERCENTAGE'? | How amountValue is interpreted | | body.useSystemCredit| boolean? | Apply system credit |

Returns: Promise<TripPayment>

Types

SetupIntent

Setup intent object returned by the PSP.

BrowserInfos

Browser metadata required for 3DS authentication. Fields depend on PSP requirements.

PaymentDetail

Payment method detail object for the 'Single' profile.

SynchronizeResponse

{
    status: 'SUCCEEDED' | 'REQUIRES_CAPTURE' | 'FAILED';
    // ...additional PSP fields
}

TripPayment

Payment object containing payment intents and receipts for a trip.