@venturialstd/capa

A comprehensive NestJS SDK for Capa Partner API v2, developed by Venturial, that provides full integration with Capa.fi's payment infrastructure. This module enables seamless fiat-to-crypto, crypto-to-fiat, and fiat-to-fiat transactions, along with complete KYC/KYB verification management.

Features

• Quotes Management: Get and create quotes for on-ramp, off-ramp, and cross-ramp transactions
• Transaction Processing: Create and manage on-ramp (fiat→crypto), off-ramp (crypto→fiat), and cross-ramp (fiat→fiat) transactions
• User Management: Create users, manage agreements, and handle document signatures
• KYC/KYB Verification: Complete KYC and KYB verification workflows with detailed status retrieval
• Receiver Management: Create, list, and manage payment receivers
• Transaction Tracking: List, filter, and cancel transactions with comprehensive status management
• Webhook Configuration: Configure webhooks for real-time transaction notifications
• Enhanced Error Handling: Detailed error messages with validation feedback and troubleshooting hints
• Type Safety: Full TypeScript support with comprehensive type definitions

Installation

npm install @venturialstd/capa
# or
yarn add @venturialstd/capa

Peer Dependencies

This package requires the following peer dependencies:

npm install @nestjs/common@^11.0.11 @nestjs/core@^11.0.5 @nestjs/axios@^4.0.0 @venturialstd/core@^1.0.16 rxjs@^7.8.1

Basic Usage

1. Import the Module

import { Module } from '@nestjs/common';
import { CapaModule } from '@venturialstd/capa';

@Module({
  imports: [
    CapaModule,
  ],
})
export class AppModule {}

2. Inject and Use Services

import { Injectable } from '@nestjs/common';
import {
  CapaQuotesService,
  CapaOnRampService,
  CapaUsersService,
  CapaKycService,
} from '@venturialstd/capa';

@Injectable()
export class PaymentService {
  constructor(
    private readonly quotesService: CapaQuotesService,
    private readonly onRampService: CapaOnRampService,
    private readonly usersService: CapaUsersService,
    private readonly kycService: CapaKycService,
  ) {}

  async processPayment(userId: string, amount: number) {
    // Get a quote
    const quote = await this.quotesService.getQuote({
      tokenSymbol: 'USDC',
      transactionType: 'ON_RAMP',
      blockchainSymbol: 'POL',
      fiatCurrency: 'MXN',
      fiatAmount: amount,
    });

    // Create on-ramp transaction
    const transaction = await this.onRampService.createOnRamp({
      userId,
      destinationWalletAddress: '0x...',
      fiatCurrency: 'MXN',
      blockchainSymbol: 'POL',
      tokenSymbol: 'USDC',
      fiatAmount: amount,
      quoteId: quote.quoteId,
    });

    return transaction;
  }

  async checkKycStatus(userId: string) {
    const kycDetails = await this.kycService.getVerificationDetails(userId);
    return kycDetails;
  }
}

3. Configuration

The module uses SettingsService from @venturialstd/core to retrieve credentials. Configure the following settings:

• CAPA_PARTNER_API_KEY: Your Capa partner API key
• CAPA_BASE_URL: Base URL for the API (optional, defaults based on environment)
• CAPA_ENVIRONMENT: Environment setting (staging or production)

Alternatively, you can pass configuration directly to service methods:

await this.quotesService.getQuote(query, {
  partnerApiKey: 'your-api-key',
  environment: 'staging',
});

API

CapaQuotesService

| Method | Endpoint | Description | |--------|----------|-------------| | getQuote(query: CapaGetQuoteQuery) | GET /api/partner/v2/quotes | Get quote rate using query parameters | | createQuote(request: CapaCreateQuoteRequest) | POST /api/partner/v2/quotes | Create a new quote |

CapaOnRampService

| Method | Endpoint | Description | |--------|----------|-------------| | createOnRamp(request: CapaCreateOnRampRequest) | POST /api/partner/v2/on-ramp | Create a fiat-to-crypto transaction |

CapaOffRampService

| Method | Endpoint | Description | |--------|----------|-------------| | createOffRamp(request: CapaCreateOffRampRequest) | POST /api/partner/v2/off-ramp | Create a crypto-to-fiat transaction |

CapaCrossRampService

| Method | Endpoint | Description | |--------|----------|-------------| | getCrossRampQuote(query: CapaGetCrossRampQuoteQuery) | GET /api/partner/v2/cross-ramp/quotes | Get cross-ramp quote rate | | createCrossRampQuote(request: CapaCreateCrossRampQuoteRequest) | POST /api/partner/v2/cross-ramp/quotes | Create a cross-ramp quote | | createCrossRamp(request: CapaCreateCrossRampRequest) | POST /api/partner/v2/cross-ramp | Create a fiat-to-fiat transaction |

CapaUsersService

| Method | Endpoint | Description | |--------|----------|-------------| | createUser(request: CapaCreateUserRequest) | POST /api/partner/v2/users | Create a new user | | getUserAgreements(userId: string) | GET /api/partner/v2/users/{id}/agreements | Get user agreements | | requestDocumentSignature(userId: string, request: CapaDocumentSignRequest) | POST /api/partner/v2/users/{id}/documents/sign | Request document signature |

CapaKycService

| Method | Endpoint | Description | |--------|----------|-------------| | getVerificationDetails(userId: string) | GET /api/partner/v2/kyc/details?userId={userId} | Get KYC verification details including AML, face match, fraud insights, and ID information |

CapaKybService

| Method | Endpoint | Description | |--------|----------|-------------| | getUserKybDetails(userId: string) | GET /api/partner/v2/kyb/details?userId={userId} | Get KYB verification details including business info and beneficial owners |

CapaReceiversService

| Method | Endpoint | Description | |--------|----------|-------------| | createReceiver(request: CapaCreateReceiverRequest) | POST /api/partner/v2/receivers | Create a payment receiver | | listReceivers(query?: CapaListReceiversQuery) | GET /api/partner/v2/receivers | List receivers with optional filtering | | deleteReceiver(id: string, request: CapaDeleteReceiverRequest) | DELETE /api/partner/v2/receivers/{id} | Disable (soft-delete) a receiver |

CapaTransactionsService

| Method | Endpoint | Description | |--------|----------|-------------| | listTransactions(query?: CapaListTransactionsQuery) | GET /api/partner/v2/transactions | List transactions with filtering options | | cancelTransaction(transactionId: string) | PUT /api/partner/v2/transactions/{id}/cancel | Cancel a transaction | | getMockTestingGuide() | GET /api/partner/v2/transactions/mock-testing-guide | Get mock testing guide for staging environment |

CapaWebhookSettingsService

| Method | Endpoint | Description | |--------|----------|-------------| | updateWebhookSettings(request: CapaUpdateWebhookSettingsRequest) | PUT /api/partner/v2/webhook-settings | Update webhook notification URL |

Error Handling

The module includes enhanced error handling that provides detailed information about:

• HTTP Status Codes: Identifies error types (400, 401, 404, 422, 500, etc.)
• Error Messages: Shows specific error messages from Capa API
• Validation Errors: Lists fields that failed validation with specific messages
• Contextual Information: Includes endpoint, HTTP method, and response time
• Troubleshooting Hints: Provides suggestions on what might be missing or incorrect

Example Error Message

Capa API call failed: POST /quotes (HTTP 422) - Validation failed | Validation errors: fiatAmount: Required field, tokenSymbol: Invalid token symbol | Unprocessable Entity: Check request body validation

Error Object Properties

When an error is thrown, you can access:

try {
  await this.quotesService.createQuote(request);
} catch (error: any) {
  console.log(error.statusCode);      // HTTP status code
  console.log(error.responseData);   // Full response data
  console.log(error.endpoint);        // API endpoint
  console.log(error.method);         // HTTP method
  console.log(error.message);        // Detailed error message
}

Notes

• Environment Support: The module supports both staging and production environments. Defaults to staging if not specified.
• Type Safety: All request and response types are fully typed for better IDE support and compile-time error checking.
• Logging: All API calls are automatically logged with timing information using AppLogger from @venturialstd/core.
• Configuration Flexibility: You can configure credentials globally via settings or pass them per-request.
• Rate Limiting: Be aware of Capa's rate limits when making multiple API calls.
• Quote Expiration: Quotes have expiration times. Always check expiresAt before using a quote.
• KYC/KYB Requirements: Users must complete KYC/KYB verification before creating transactions.
• Webhook Security: Ensure your webhook endpoints are secured and validate webhook signatures from Capa.

License

MIT

Support

For issues, questions, or contributions, please contact the Venturial development team.