Akua SDK

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
• Installation
• Quick Start
• API Reference
  • Authentication
  • Creating an AkuaClient instance
  • Organizations
  • Merchants
  • Payment Instruments
  • Payments
  • Webhooks
• TypeScript Types
  • Available Types
  • Type Categories
  • Type Safety Example
• Error Handling
• License

✨ 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

📦 Installation

# Using npm
npm install akua-sdk

# Using yarn
yarn add akua-sdk

# Using pnpm
pnpm add akua-sdk

🚀 Quick Start

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: '[email protected]',
  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;

📋 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.

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.

const organization = await akuaClient.organizations.create({
  name: 'Acme Corp',
});

organizations.get(): Promise<ApiResponse<OrganizationDTO[]>>

Retrieves all organizations from the Akua system.

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.

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: '[email protected]',
  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.

const merchant = await akuaClient.merchants.getById('merch_123456789');

merchants.get(request: GetMerchantsRequest): Promise<ApiResponse<MerchantDTO[]>>

Lists all merchants for an organization with pagination support.

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.

const updatedMerchant = await akuaClient.merchants.update('merch_123456789', {
  name: 'Updated Store Name',
  email: '[email protected]',
  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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

const cancel = await akuaClient.payments.cancel('pay-d0v32ak2mts03heh7amg');

payments.refund(paymentId: string, data: RefundPaymentRequest): Promise<ApiResponse<RefundPaymentDTO>>

Refunds a payment transaction.

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.

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.

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.

const webhooks = await akuaClient.webhooks.get();

webhooks.getSecret(webhookId: string): Promise<ApiResponse<WebhookSecretDTO>>

Retrieves a webhook configuration's secret key by its ID.

const webhookSecret = await akuaClient.webhooks.getSecret('webhook_123');

📘 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

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

   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:

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
}

🛡️ Error Handling

The SDK provides built-in error handling with detailed error messages. All API responses are wrapped in an ApiResponse type:

interface ApiResponse<T> {
  data: T | null;
  success: boolean;
  error?: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
}

Example error handling:

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);
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.