akua-sdk
Version:
TypeScript SDK for Akua Acquiring Processor
774 lines (628 loc) ā¢ 21.2 kB
Markdown
# Akua SDK
[](https://www.npmjs.com/package/akua-sdk)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
A modern TypeScript SDK for integrating with the Akua Payment Gateway. This SDK provides a type-safe and developer-friendly way to interact with Akua's payment processing services.
ā ļø **This SDK is in BETA stage and it can sometimes have differences from the official Akua API.**
Access and usage are strictly limited to teams authorized by Akua.
## š Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Creating an AkuaClient instance](#creating-an-akuaclient-instance)
- [Organizations](#organizations)
- [Merchants](#merchants)
- [Payment Instruments](#payment-instruments)
- [Payments](#payments)
- [Webhooks](#webhooks)
- [TypeScript Types](#typescript-types)
- [Available Types](#available-types)
- [Type Categories](#type-categories)
- [Type Safety Example](#type-safety-example)
- [Error Handling](#error-handling)
- [License](#license)
<a id="features"></a>
## āØ Features
- š Full TypeScript support with comprehensive type definitions
- š SDK functionalities:
- Automatic token management (generation and refresh)
- Organization Management
- Create and manage organizations
- Group related business entities
- Merchant Management
- Create, update, and delete merchants
- Configure payment rails (VISA, Mastercard)
- Set up merchant profiles and settings
- Payment Instruments
- Tokenize and store payment methods
- Manage card information securely
- Support for multiple payment methods
- Payment Processing
- Authorization with PAN or token
- Automatic and manual capture modes
- Payment cancellation
- Refund processing
- Payment verification
- Installment support
- Webhook Management
- Configure webhook endpoints
- Set up event notifications
- Manage webhook secrets
- ā” Modern async/await API
- š”ļø Built-in error handling
- š Comprehensive documentation
- š Secure token management
- š Multi-currency support
- š¢ Multi-tenant architecture
<a id="installation"></a>
## š¦ Installation
```bash
# Using npm
npm install akua-sdk
# Using yarn
yarn add akua-sdk
# Using pnpm
pnpm add akua-sdk
```
<a id="quick-start"></a>
## š Quick Start
```typescript
import { AkuaClient, AkuaTypes } from 'akua-sdk';
// Create the AkuaClient instance with your credentials
// The client will automatically handle token management
const akuaClientConfig: AkuaTypes.ClientConfig = {
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
environment: AkuaTypes.Enums.Environment.SANDBOX, // or PRODUCTION
};
const akuaClient = new AkuaClient(akuaClientConfig);
// Now you can use the AkuaClient instance
const createOrganizationRequest: AkuaTypes.RequestTypes.CreateOrganizationRequest = {
name: 'My Organization',
};
const createOrganizationResponse: AkuaTypes.ApiResponse<AkuaTypes.ResponseTypes.OrganizationDTO> =
await akuaClient.organizations.create(createOrganizationRequest);
if (!createOrganizationResponse.success || !createOrganizationResponse.data) {
throw new Error('Create organization failed');
}
const organization: AkuaTypes.ResponseTypes.OrganizationDTO = createOrganizationResponse.data;
const createMerchantRequest: AkuaTypes.RequestTypes.CreateMerchantRequest = {
name: 'My Store',
organization_id: organization.id,
country: 'US',
city: 'New York',
state: 'NY',
billing_address: {
street: '123 Main St',
city: 'New York',
state: 'NY',
country: 'US',
postal_code: '10001',
},
location_address: {
street: '123 Main St',
city: 'New York',
state: 'NY',
country: 'US',
postal_code: '10001',
},
classification_mode: 'retail',
default_currency: 'USD',
supported_currencies: ['USD', 'EUR'],
activity: 'retail',
alias: 'my-store-ny',
email: 'store@example.com',
external_id: 'ext_123',
phone: '+1234567890',
tax_id: '123456789',
rails: {
VISA: {
category_code: '5411',
payfac_id: 'payfac_123',
},
MASTERCARD: {
category_code: '5411',
payfac_id: 'payfac_123',
},
},
};
const createMerchantResponse: AkuaTypes.ApiResponse<AkuaTypes.ResponseTypes.MerchantDTO> =
await akuaClient.merchants.create(createMerchantRequest);
if (!createMerchantResponse.success || !createMerchantResponse.data) {
throw new Error('Create merchant failed');
}
const merchant: AkuaTypes.ResponseTypes.MerchantDTO = createMerchantResponse.data;
const createInstrumentRequest: AkuaTypes.RequestTypes.CreateInstrumentRequest = {
type: 'CARD',
card: {
number: '4242424242424242',
expiration_month: '12',
expiration_year: '2030',
first_name: 'John',
last_name: 'Doe',
cvv: '123',
},
user_data: {
billing_address: {
street: '123 Main St',
number: 'Apt 4B',
city: 'New York',
state: 'NY',
zip_code: '10001',
country: 'US',
},
},
};
const createInstrumentResponse: AkuaTypes.ApiResponse<AkuaTypes.ResponseTypes.InstrumentDTO> =
await akuaClient.instruments.create(createInstrumentRequest);
if (!createInstrumentResponse.success || !createInstrumentResponse.data) {
throw new Error('Create instrument failed');
}
const instrument: AkuaTypes.ResponseTypes.InstrumentDTO = createInstrumentResponse.data;
```
<a id="api-reference"></a>
## š API Reference
### Authentication
The SDK handles authentication automatically. When you create an `AkuaClient` instance with your client credentials, it will:
1. Generate an initial token using your credentials
2. Automatically refresh the token before it expires (with a 5-minute buffer)
3. Handle token reuse across all requests
4. Manage concurrent token refresh requests
5. Handle authentication errors gracefully
### Creating an AkuaClient instance
The `AkuaClient` is the main entry point for interacting with the Akua API. It requires your client credentials and an environment configuration.
```typescript
import { AkuaClient, AkuaTypes } from 'akua-sdk';
const clientConfig: AkuaTypes.ClientConfig = {
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
environment: AkuaTypes.Enums.Environment.SANDBOX, // or PRODUCTION
};
const akuaClient = new AkuaClient(clientConfig);
```
### Organizations
#### `organizations.create(data: CreateOrganizationRequest): Promise<ApiResponse<OrganizationDTO>>`
Creates a new organization in the Akua system. Organizations can have multiple merchants and are used to group related business entities.
```typescript
const organization = await akuaClient.organizations.create({
name: 'Acme Corp',
});
```
#### `organizations.get(): Promise<ApiResponse<OrganizationDTO[]>>`
Retrieves all organizations from the Akua system.
```typescript
const organizations = await akuaClient.organizations.get();
```
### Merchants
#### `merchants.create(data: CreateMerchantRequest): Promise<ApiResponse<MerchantDTO>>`
Creates a new merchant in the Akua system. This is the first step in setting up a new merchant account. The merchant will be associated with the specified organization and will be configured with the provided payment rails and settings.
```typescript
const merchant = await akuaClient.merchants.create({
name: 'My Store',
organization_id: 'org_123',
country: AkuaTypes.Enums.Country.UNITED_STATES,
city: 'New York',
state: 'NY',
billing_address: {
street: '123 Main St',
city: 'New York',
state: 'NY',
country: AkuaTypes.Enums.Country.UNITED_STATES,
postal_code: '10001',
},
location_address: {
street: '123 Main St',
city: 'New York',
state: 'NY',
country: AkuaTypes.Enums.Country.UNITED_STATES,
postal_code: '10001',
},
classification_mode: 'retail',
default_currency: AkuaTypes.Enums.Currency.USD,
supported_currencies: [AkuaTypes.Enums.Currency.USD, AkuaTypes.Enums.Currency.EUR],
activity: 'retail',
alias: 'my-store-ny',
email: 'store@example.com',
external_id: 'ext_123',
phone: '+1234567890',
tax_id: '123456789',
rails: {
[AkuaTypes.Enums.Rail.VISA]: {
category_code: '5411',
payfac_id: 'payfac_123',
},
[AkuaTypes.Enums.Rail.MASTERCARD]: {
category_code: '5411',
payfac_id: 'payfac_123',
},
},
});
```
#### `merchants.getById(merchantId: string): Promise<ApiResponse<MerchantDTO>>`
Retrieves a merchant's information by its unique identifier.
```typescript
const merchant = await akuaClient.merchants.getById('merch_123456789');
```
#### `merchants.get(request: GetMerchantsRequest): Promise<ApiResponse<MerchantDTO[]>>`
Lists all merchants for an organization with pagination support.
```typescript
const merchants = await akuaClient.merchants.get({
organization_id: 'org-d0j35vc4t5u70r4eso70',
page: 1,
page_size: 20,
sort: 'created_at:desc',
});
```
#### `merchants.update(merchantId: string, data: UpdateMerchantRequest): Promise<ApiResponse<MerchantDTO>>`
Updates an existing merchant's information.
```typescript
const updatedMerchant = await akuaClient.merchants.update('merch_123456789', {
name: 'Updated Store Name',
email: 'updated@example.com',
phone: '+1987654321',
billing_address: {
street: '456 New St',
city: 'Los Angeles',
state: 'CA',
country: AkuaTypes.Enums.Country.UNITED_STATES,
postal_code: '90001',
},
});
```
#### `merchants.updateRails(merchantId: string, data: UpdateMerchantRailsRequest): Promise<ApiResponse<MerchantDTO>>`
Updates the rails configuration for a merchant.
```typescript
const updatedMerchant = await akuaClient.merchants.updateRails('merch_123456789', {
[AkuaTypes.Enums.Rail.VISA]: {
category_code: '1234',
payfac_id: 'pfc-123',
external_id: 'mer-ext-123',
classification: 'micro-merchant',
annual_volume: [
{
currency: AkuaTypes.Enums.Currency.COP,
value: 10000000,
},
],
products: {
[AkuaTypes.Enums.Product.DEBIT]: {
network_merchant_id: 'VISA-123',
enabled: true,
},
[AkuaTypes.Enums.Product.CREDIT]: {
network_merchant_id: 'VISA-123',
enabled: true,
},
},
},
});
```
#### `merchants.delete(merchantId: string): Promise<ApiResponse<void>>`
Deletes a merchant from the Akua system.
```typescript
await akuaClient.merchants.delete('merch_123456789');
```
### Payment Instruments
#### `instruments.create(data: CreateInstrumentRequest): Promise<ApiResponse<InstrumentDTO>>`
Creates a new payment instrument. The instrument is tokenized and stored securely in the Akua system.
```typescript
const card = await akuaClient.instruments.create({
type: 'CARD',
card: {
number: '4242424242424242',
expiration_month: '12',
expiration_year: '2025',
first_name: 'John',
last_name: 'Doe',
cvv: '123',
},
user_data: {
billing_address: {
street: '123 Main St',
number: 'Apt 4B',
city: 'New York',
state: 'NY',
zip_code: '10001',
country: AkuaTypes.Enums.Country.UNITED_STATES,
},
},
});
```
#### `instruments.get(): Promise<ApiResponse<InstrumentDTO[]>>`
Retrieves all payment instruments associated with the merchant. This includes both active and inactive instruments, with their current status and details.
```typescript
const instruments = await akuaClient.instruments.get();
```
#### `instruments.getById(id: string): Promise<ApiResponse<InstrumentDTO>>`
Retrieves detailed information about a specific payment instrument, including its type and status.
```typescript
const instrument = await akuaClient.instruments.getById('instr_123');
```
#### `instruments.update(id: string, data: UpdateInstrumentRequest): Promise<ApiResponse<InstrumentDTO>>`
Updates an existing payment instrument's information. This can be used to update expiration dates, cardholder information, or other instrument details.
```typescript
const updatedInstrument = await akuaClient.instruments.update('instr_123', {
card: {
expiration_month: '12',
expiration_year: '2026',
first_name: 'John',
last_name: 'Smith',
},
});
```
#### `instruments.delete(id: string): Promise<ApiResponse<void>>`
Permanently deletes a payment instrument from the system. This operation cannot be undone and will invalidate the instrument for future use.
```typescript
await client.instruments.delete('instr_123');
```
### Payments
#### `payments.authorizeWithPan(data: AuthorizeWithPanRequest): Promise<ApiResponse<AuthorizePaymentDTO>>`
Authorizes a payment transaction using PAN (Primary Account Number). This is used for direct card payments.
```typescript
const payment = await akuaClient.payments.authorizeWithPan({
amount: {
value: 25.25,
currency: AkuaTypes.Enums.Currency.USD,
},
intent: AkuaTypes.Enums.PaymentIntent.AUTHORIZATION,
trace_id: 'any-format-34324366',
entry_mode: AkuaTypes.Enums.PaymentEntryMode.MANUAL,
capture: {
mode: AkuaTypes.Enums.CaptureMode.AUTOMATIC,
},
merchant_id: 'mer-d0r0b17npsai542l2400',
installments: {
quantity: 2,
type: '03',
},
instrument: {
type: 'CARD',
card: {
number: '4024007108904086',
expiration_month: '12',
expiration_year: '25',
holder_name: 'John Doe',
cvv: '123',
},
user_data: {
billing_address: {
street: '123 Main St',
number: 'Apt 4B',
city: 'New York',
state: 'NY',
zip_code: '10001',
country: AkuaTypes.Enums.Country.UNITED_STATES,
phone_number: '+1234567890',
},
},
},
});
```
#### `payments.authorizeWithToken(data: AuthorizeWithTokenRequest): Promise<ApiResponse<AuthorizePaymentDTO>>`
Authorizes a payment transaction using a previously tokenized instrument.
```typescript
const payment = await akuaClient.payments.authorizeWithToken({
amount: {
value: 25.25,
currency: AkuaTypes.Enums.Currency.USD,
},
intent: AkuaTypes.Enums.PaymentIntent.AUTHORIZATION,
trace_id: 'any-format-34324366',
entry_mode: AkuaTypes.Enums.PaymentEntryMode.MANUAL,
capture: {
mode: AkuaTypes.Enums.CaptureMode.AUTOMATIC,
},
merchant_id: 'mer-d0r0b17npsai542l2400',
installments: {
quantity: 2,
type: '03',
},
instrument: {
id: 'instr_123456789',
},
});
```
#### `payments.capture(paymentId: string, data: CapturePaymentRequest): Promise<ApiResponse<CapturePaymentDTO>>`
Captures a previously authorized payment. Only payments created with capture_manual mode can be captured.
```typescript
const capture = await akuaClient.payments.capture('pay_123', {
amount: {
value: 25.25,
currency: AkuaTypes.Enums.Currency.USD,
},
});
```
#### `payments.cancel(paymentId: string): Promise<ApiResponse<CancelPaymentDTO>>`
Cancels a payment transaction.
```typescript
const cancel = await akuaClient.payments.cancel('pay-d0v32ak2mts03heh7amg');
```
#### `payments.refund(paymentId: string, data: RefundPaymentRequest): Promise<ApiResponse<RefundPaymentDTO>>`
Refunds a payment transaction.
```typescript
const refund = await akuaClient.payments.refund('pay-d0v32ak2mts03heh7amg', {
amount: {
value: 25.25,
currency: AkuaTypes.Enums.Currency.USD,
},
});
```
#### `payments.verify(data: VerifyPaymentRequest): Promise<ApiResponse<AuthorizePaymentDTO>>`
Verifies a payment instrument (card) status.
```typescript
const verify = await akuaClient.payments.verify({
intent: AkuaTypes.Enums.PaymentIntent.AUTHORIZATION,
merchant_id: 'mer-d0r0b17npsai542l2400',
trace_id: 'any-format-34324366',
instrument: {
type: 'CARD',
card: {
number: '4024007108904086',
expiration_month: '12',
expiration_year: '25',
holder_name: 'John Doe',
cvv: '123',
},
user_data: {
billing_address: {
street: '123 Main St',
number: 'Apt 4B',
city: 'New York',
state: 'NY',
zip_code: '10001',
country: AkuaTypes.Enums.Country.UNITED_STATES,
phone_number: '+1234567890',
},
},
},
});
```
### Webhooks
#### `webhooks.create(data: CreateWebhookRequest): Promise<ApiResponse<WebhookDTO>>`
Creates a new webhook configuration.
```typescript
const webhook = await akuaClient.webhooks.create({
url: 'https://example.com/webhook',
events: [AkuaTypes.Enums.EventType.PAYMENT_AUTHORIZATION_PROCESSED],
description: 'Webhook for payment events',
rate_limit: 1,
});
```
#### `webhooks.get(): Promise<ApiResponse<WebhookDTO[]>>`
Retrieves all webhook configurations.
```typescript
const webhooks = await akuaClient.webhooks.get();
```
#### `webhooks.getSecret(webhookId: string): Promise<ApiResponse<WebhookSecretDTO>>`
Retrieves a webhook configuration's secret key by its ID.
```typescript
const webhookSecret = await akuaClient.webhooks.getSecret('webhook_123');
```
<a id="typescript-types"></a>
## š TypeScript Types
The SDK provides comprehensive TypeScript types that can be imported from the `AkuaTypes` namespace. This allows you to have full type safety and autocompletion when working with the SDK.
### Available Types
```typescript
import { AkuaTypes } from 'akua-sdk';
// Enums
const environment = AkuaTypes.Enums.Environment.SANDBOX;
const country = AkuaTypes.Enums.Country.USA;
const rail = AkuaTypes.Enums.Rail.VISA;
// Request Types
const createMerchantRequest: AkuaTypes.RequestTypes.CreateMerchantRequest = {
name: 'My Store',
organization_id: 'org_123',
// ... other merchant fields
};
const createInstrumentRequest: AkuaTypes.RequestTypes.CreateInstrumentRequest = {
type: 'CARD',
card: {
number: '4242424242424242',
expiration_month: '12',
expiration_year: '2025',
first_name: 'John',
last_name: 'Doe',
cvv: '123',
},
};
// Response Types
const merchantResponse: AkuaTypes.ResponseTypes.MerchantDTO = {
id: 'merch_123',
name: 'My Store',
// ... other merchant fields
};
const instrumentResponse: AkuaTypes.ResponseTypes.InstrumentDTO = {
id: 'instr_123',
type: 'CARD',
// ... other instrument fields
};
```
### Type Categories
The SDK's types are organized into several categories:
1. **Enums**: Constants and enumerations used throughout the SDK
2. **Request Types**: Types for API request payloads
3. **Response Types**: Types for API response data
4. **API Response**: Generic wrapper type for all API responses
```typescript
interface ApiResponse<T> {
data: T | null;
success: boolean;
error?: {
code: string;
message: string;
details?: Record<string, unknown>;
};
}
```
### Type Safety Example
Here's an example of how the types help catch errors at compile time:
```typescript
import { AkuaClient, AkuaTypes } from 'akua-sdk';
const client = new AkuaClient({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
environment: AkuaTypes.Enums.Environment.SANDBOX,
});
// TypeScript will show an error if required fields are missing
const merchant = await client.merchants.create({
name: 'My Store',
// Error: missing required field 'organization_id'
});
// TypeScript will show an error if field types don't match
const instrument = await client.instruments.create({
type: 'CARD',
card: {
number: 4242424242424242, // Error: number should be a string
expiration_month: 12, // Error: should be a string
expiration_year: 2025, // Error: should be a string
first_name: 'John',
last_name: 'Doe',
},
});
// TypeScript will provide autocompletion for response fields
const response = await client.instruments.getById('ins_123');
if (response.success && response.data) {
console.log(response.data.status); // Autocomplete available
console.log(response.data.type); // Autocomplete available
console.log(response.data.invalid_field); // Error: field doesn't exist
}
```
<a id="error-handling"></a>
## š”ļø Error Handling
The SDK provides built-in error handling with detailed error messages. All API responses are wrapped in an `ApiResponse` type:
```typescript
interface ApiResponse<T> {
data: T | null;
success: boolean;
error?: {
code: string;
message: string;
details?: Record<string, unknown>;
};
}
```
Example error handling:
```typescript
try {
const result = await akuaClient.organizations.create({
name: 'Acme Corp',
});
if (!result.success) {
console.error(`Error ${result.error?.code}: ${result.error?.message}`);
if (result.error?.details) {
console.error('Details:', result.error.details);
}
return;
}
// Use result.data safely here
console.log('Organization created:', result.data);
} catch (error) {
// Handle unexpected errors
console.error('Unexpected error:', error);
}
```
<a id="license"></a>
## š License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.