API Documentation

Build with TurraTech

Everything you need to integrate TurraTech into your application. SDKs in 8 languages, comprehensive docs, and a full-featured sandbox.

Open sandbox API reference

Node.js
const turratech = require('turratech')('sk_test_...');

const payment = await turratech.payments.create({
  amount: 2000,
  currency: 'usd',
  payment_method: 'pm_card_visa',
  confirm: true
});

console.log(payment.status); // 'succeeded'

Getting started

Quick start guide

Get up and running with TurraTech in under 10 minutes.

Create account

Install SDK

Install our SDK for your language using npm, pip, composer, or your package manager.

Integrate

Add TurraTech Checkout to your app or build a custom integration with our API.

Go live

Test with sandbox, then switch to live keys when you're ready to accept real payments.

Code examples

Common integrations

Copy-paste examples for the most common payment scenarios.

Create a payment

Charge a customer's card with a one-time payment.

Node.js
const payment = await turratech.payments.create({
  amount: 5000, // $50.00
  currency: 'usd',
  payment_method: 'pm_xxx',
  customer: 'cus_xxx',
  description: 'Order #1234',
  confirm: true
});

Create payment intent

Create a payment intent for client-side confirmation.

Node.js
const intent = await turratech.paymentIntents.create({
  amount: 2000,
  currency: 'eur',
  payment_method_types: ['card'],
  metadata: { order_id: '6735' }
});
// Send intent.client_secret to frontend

Capture authorized payment

Capture a previously authorized payment.

Node.js
const captured = await turratech.payments.capture(
  'pay_xxx',
  { amount_to_capture: 1500 } // Partial capture
);

List payments

Retrieve a list of payments with filters.

Node.js
const payments = await turratech.payments.list({
  customer: 'cus_xxx',
  created: { gte: 1704067200 },
  limit: 10
});

Create customer

Create a customer to save payment methods.

Node.js

const customer = await turratech.customers.create({
  email: 'hello@turratech.com',
  name: 'Jenny Rosen',
  metadata: { user_id: 'usr_123' }
});

Attach payment method

Save a card to a customer for future use.

Node.js
await turratech.paymentMethods.attach(
  'pm_xxx',
  { customer: 'cus_xxx' }
);

// Set as default
await turratech.customers.update('cus_xxx', {
  invoice_settings: {
    default_payment_method: 'pm_xxx'
  }
});

Update customer

Update customer details and metadata.

Node.js

const updated = await turratech.customers.update(
  'cus_xxx',
  {
    email: 'hello@turratech.com',
    metadata: { plan: 'pro' }
  }
);

List payment methods

Get all saved cards for a customer.

Node.js
const methods = await turratech.paymentMethods.list({
  customer: 'cus_xxx',
  type: 'card'
});

Create subscription

Start a recurring subscription for a customer.

Node.js
const subscription = await turratech.subscriptions.create({
  customer: 'cus_xxx',
  items: [{ price: 'price_monthly_pro' }],
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent']
});

Create metered subscription

Usage-based billing subscription.

Node.js
const sub = await turratech.subscriptions.create({
  customer: 'cus_xxx',
  items: [{
    price: 'price_api_calls' // metered price
  }]
});

// Report usage
await turratech.subscriptionItems.createUsageRecord(
  sub.items.data[0].id,
  { quantity: 1000, timestamp: 1704067200 }
);

Cancel subscription

Cancel immediately or at period end.

Node.js
// Cancel at period end
await turratech.subscriptions.update('sub_xxx', {
  cancel_at_period_end: true
});

// Cancel immediately
await turratech.subscriptions.cancel('sub_xxx');

Update subscription

Change plan or quantity mid-cycle.

Node.js
const updated = await turratech.subscriptions.update(
  'sub_xxx',
  {
    items: [{
      id: 'si_xxx',
      price: 'price_yearly_pro'
    }],
    proration_behavior: 'create_prorations'
  }
);

Full refund

Refund the entire payment amount.

Node.js
const refund = await turratech.refunds.create({
  payment: 'pay_xxx',
  reason: 'requested_by_customer'
});

Partial refund

Refund a specific amount.

Node.js
const refund = await turratech.refunds.create({
  payment: 'pay_xxx',
  amount: 500, // $5.00
  metadata: { ticket: '#4521' }
});

Verify webhook signature

Validate that webhooks are from TurraTech.

Node.js
const sig = req.headers['turratech-signature'];
const endpointSecret = 'whsec_xxx';

let event;
try {
  event = turratech.webhooks.constructEvent(
    req.body, sig, endpointSecret
  );
} catch (err) {
  return res.status(400).send(`Webhook Error`);
}

Handle webhook events

Process different event types.

Node.js
switch (event.type) {
  case 'payment.succeeded':
    const payment = event.data.object;
    fulfillOrder(payment);
    break;
  case 'payment.failed':
    notifyCustomer(event.data.object);
    break;
  case 'customer.subscription.deleted':
    handleCancellation(event.data.object);
    break;
}
res.json({ received: true });