CinchAPI React Native SDK

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

Installation

npm install @cinchapi/react-native-sdk

Quick Start

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

// Initialize the SDK (Recommended: Use dual keys for PCI compliance)
const cinchAPI = new CinchAPI({
  baseURL: 'https://your-api-domain.com',
  publicKey: 'cinch_pk_test_your_public_key',  // For tokenization
  secretKey: 'cinch_sk_test_your_secret_key',  // For other operations
  timeout: 30000
});

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

// PCI Compliant Tokenization (card data processed securely server-side)
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',
  source: tokenizedCard.token_id
});

API Methods

Customers

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

Payments

• tokenizeCard(data: TokenizeCardData): Promise<TokenizedCard> (PCI Compliant - Recommended)
• createCharge(data: ChargeData): Promise<Charge>
• getCharge(chargeId: string): Promise<Charge>
• capturePayment(data: { charge_id: string; amount?: number }): Promise<Charge>
• voidCharge(chargeId: string, data: VoidChargeData): Promise<VoidedCharge>
• cancelPayment(transactionId: string): Promise<any>
• refundPayment(data: RefundData): Promise<any>

Bank Accounts

• createBankAccount(data: BankAccountData): Promise<BankAccount>
• getBankAccount(bankAccountId: string): Promise<BankAccount>
• deleteBankAccount(bankAccountId: string): Promise<any>
• createACHCharge(data: ACHChargeData): Promise<any>

Plans

• createPlan(data: PlanData): Promise<Plan>
• getPlan(planId: string): 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>
• getSubscription(subscriptionId: string): Promise<Subscription>
• updateSubscription(subscriptionId: string, data: UpdateSubscriptionData): Promise<Subscription>
• cancelSubscription(subscriptionId: string): Promise<Subscription>
• getSubscriptions(params?: EventsQueryParams): Promise<{ subscriptions: Subscription[]; pagination: any }>

API Management

• getApiKeys(): Promise<{ test: { public: string; secret: string }; live: { public: string; secret: string } }>
• regenerateApiKey(environment: 'test' | 'live', keyType: 'public' | 'secret'): Promise<{ key: string }>
• getMerchantInfo(): Promise<{ merchantId: string; businessName: string; email: string; environment: string; gateway: string }>

Events & Monitoring

• 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>

🛡️ PCI Compliance

The tokenizeCard() method provides PCI compliant tokenization through CinchAPI's secure servers. Card data is processed safely and only tokens are returned.

// ✅ PCI Compliant - Server-side tokenization
const token = await cinchAPI.tokenizeCard({
  card_number: 4111111111111111,
  exp_month: '12',
  exp_year: '2025',
  cvv: '123'
});

Security Features:

• 🔒 Secure transmission through HTTPS/TLS
• 🔒 No card data storage or logging
• 🔒 Memory-only processing with automatic cleanup
• 🔒 PCI compliant infrastructure

Always use public keys for tokenization operations:

const cinchAPI = new CinchAPI({
  publicKey: 'cinch_pk_test_...',  // ✅ Safe for client-side
  secretKey: 'cinch_sk_test_...'   // ✅ Keep server-side only
});

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-native-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