CinchAPI React TypeScript SDK

A simple and clean React TypeScript SDK for integrating with the CinchAPI payment processing platform.

Installation

npm install @cinchapi/react-sdk

Quick Start

import CinchAPI from '@cinchapi/react-sdk';

// Initialize the SDK
const cinchAPI = new CinchAPI({
  baseURL: 'https://your-api-domain.com',
  apiKey: 'your-api-key',
  timeout: 30000 // optional, defaults to 30 seconds
});

// Create a customer
const customer = await cinchAPI.createCustomer({
  email: '[email protected]',
  name: 'John Doe'
});

// Tokenize a card
const tokenizedCard = await cinchAPI.tokenizeCard({
  card_number: 4111111111111111,
  exp_month: '12',
  exp_year: '2025',
  cvv: '123'
});

// Create a charge
const charge = await cinchAPI.createCharge({
  amount: 1000, // $10.00 in cents
  currency: 'USD',
  token_id: tokenizedCard.token_id
});

API Methods

Customers

• createCustomer(data: CustomerData): Promise<Customer>
• getCustomer(customerId: string): Promise<Customer>

Payments

• tokenizeCard(data: TokenizeCardData): Promise<TokenizedCard>
• createCharge(data: ChargeData): Promise<Charge>
• voidCharge(chargeId: string, data: VoidChargeData): Promise<VoidedCharge>
• capturePayment(data: PaymentData): Promise<any>
• cancelPayment(transactionId: string): Promise<any>
• refundPayment(data: RefundData): Promise<any>

Bank Accounts

• createBankAccount(data: BankAccountData): Promise<BankAccount>
• createACHCharge(data: ACHChargeData): Promise<any>

Plans

• createPlan(data: PlanData): Promise<Plan>
• updatePlan(planId: string, data: UpdatePlanData): Promise<Plan>
• deletePlan(planId: string): Promise<any>
• getPlans(params?: EventsQueryParams): Promise<{ plans: Plan[]; pagination: any }>

Subscriptions

• createSubscription(data: SubscriptionData): Promise<Subscription>
• updateSubscription(subscriptionId: string, data: UpdateSubscriptionData): Promise<Subscription>
• cancelSubscription(subscriptionId: string): Promise<Subscription>
• getSubscriptions(params?: EventsQueryParams): Promise<{ subscriptions: Subscription[]; pagination: any }>

Events

• getEvents(params?: EventsQueryParams): Promise<EventsResponse>

Response Codes

• interpretResponseCode(code: string): Promise<InterpretedResponse>
• getResponseCodeInfo(code: string): Promise<ResponseCodeInfo>
• getAllResponseCodes(): Promise<ResponseCodeInfo[]>
• getResponseCodesByCategory(category: string): Promise<ResponseCodeInfo[]>

Health Check

• healthCheck(): Promise<any>

Error Handling

The SDK throws CinchAPIError for various error conditions:

try {
  const customer = await cinchAPI.createCustomer({
    email: '[email protected]'
  });
} catch (error) {
  if (error instanceof CinchAPIError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Customer Message:', error.customerMessage);
    console.error('Merchant Message:', error.merchantMessage);
  }
}

Types

All TypeScript types are exported from the SDK:

import {
  CinchAPIConfig,
  CustomerData,
  Customer,
  TokenizeCardData,
  TokenizedCard,
  ChargeData,
  Charge,
  PlanData,
  Plan,
  SubscriptionData,
  Subscription,
  CinchAPIError
} from '@cinchapi/react-sdk';

Examples

Creating a Subscription

// First create a plan
const plan = await cinchAPI.createPlan({
  amount: 2999, // $29.99
  plan_type: 'digital',
  name: 'Premium Plan',
  interval: 'month',
  statement_descriptor: 'PREMIUM PLAN'
});

// Then create a subscription
const subscription = await cinchAPI.createSubscription({
  customer_id: customer.id,
  plan_id: plan.plan_id
});

Processing a Payment

// Tokenize the card
const tokenizedCard = await cinchAPI.tokenizeCard({
  card_number: 4111111111111111,
  exp_month: '12',
  exp_year: '2025',
  cvv: '123',
  card_holder_name: 'John Doe'
});

// Create a charge
const charge = await cinchAPI.createCharge({
  amount: 2500, // $25.00
  currency: 'USD',
  token_id: tokenizedCard.token_id,
  statement_description: 'Purchase'
});

License

MIT