TurraTech API Documentation

Introduction

The TurraTech API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the TurraTech API in test mode, which does not affect your live data or interact with banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

Request Format

The API accepts request data as JSON. Set the Content-Type header to application/json for all POST and PUT requests.

curl https://api.turratech.com/v1/payments \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "gbp",
    "payment_method": "pm_card_visa"
  }'

Response Format

All responses are returned as JSON objects. Successful responses include the requested resource. Error responses include an error object with details about what went wrong.

{
  "id": "pay_1NqQXYZ123456789",
  "object": "payment",
  "amount": 2000,
  "currency": "gbp",
  "status": "succeeded",
  "created": 1704067200,
  "livemode": false
}

Authentication

The TurraTech API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secure.

Authentication is performed via HTTP Bearer authentication. Provide your API key as the bearer token value.

API Key Types

curl https://api.turratech.com/v1/payments \
  -H "Authorization: Bearer sk_test_51ABC123DEF456..."

Test vs Live Mode

Use test mode keys (sk_test_) during development. Test mode transactions don't move real money and use test card numbers. Switch to live mode keys (sk_live_) when you're ready to accept real payments.

Errors

TurraTech uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success, codes in the 4xx range indicate an error from the provided information, and codes in the 5xx range indicate an error with TurraTech's servers.

HTTP Status Codes

Error Response Format

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": "payment_method",
    "decline_code": "insufficient_funds"
  }
}

Error Types

Pagination

All top-level API resources have support for bulk fetches via list API methods. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

Parameters

curl https://api.turratech.com/v1/payments?limit=25&starting_after=pay_abc123 \
  -H "Authorization: Bearer sk_test_..."

List Response Format

{
  "object": "list",
  "data": [
    { "id": "pay_xyz789", ... },
    { "id": "pay_xyz790", ... }
  ],
  "has_more": true,
  "url": "/v1/payments"
}

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.

To perform an idempotent request, provide an Idempotency-Key header with a unique value (we recommend a UUID v4).

curl https://api.turratech.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{"amount": 2000, "currency": "gbp"}'

Versioning

When backwards-incompatible changes are made to the API, a new dated version is released. The current version is 2024-01-01. You can set the API version in your Dashboard or on a per-request basis.

curl https://api.turratech.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "TurraTech-Version: 2024-01-01"

We recommend testing new versions in your development environment before upgrading your account's default version.

Payments

A Payment object represents a single attempt to move money into your TurraTech account. Payments can be made using cards, bank transfers, or alternative payment methods.

Create a Payment

const payment = await turratech.payments.create({
  amount: 2000,
  currency: 'gbp',
  payment_method: 'pm_card_visa',
  confirm: true,
  description: 'Order #12345',
  metadata: {
    order_id: '12345'
  }
});

Payment Object

{
  "id": "pay_1NqQXYZ123456789",
  "object": "payment",
  "amount": 2000,
  "amount_capturable": 0,
  "amount_received": 2000,
  "currency": "gbp",
  "customer": "cus_ABC123",
  "description": "Order #12345",
  "payment_method": "pm_card_visa",
  "status": "succeeded",
  "created": 1704067200,
  "livemode": false,
  "metadata": {
    "order_id": "12345"
  }
}

Customers

Customer objects allow you to perform recurring charges and track multiple payments associated with the same customer. The API allows you to create, delete, and update customers.

Create a Customer

const customer = await turratech.customers.create({
  email: 'hello@turratech.com',
  name: 'Jane Doe',
  address: {
    line1: '123 Main Street',
    city: 'London',
    postal_code: 'SW1A 1AA',
    country: 'GB'
  }
});

Payment Methods

PaymentMethod objects represent your customer's payment instruments. You can use them with Payments to collect payments or save them to a Customer to store instrument details for future payments.

Supported Payment Method Types

Refunds

Refund objects allow you to refund a payment that has previously been charged but not yet refunded. Funds will be refunded to the original payment method.

Create a Refund

const refund = await turratech.refunds.create({
  payment: 'pay_1NqQXYZ123456789',
  amount: 1000, // Partial refund
  reason: 'requested_by_customer'
});

Subscriptions

Subscriptions allow you to charge a customer on a recurring basis. A subscription ties a customer to a particular price.

Create a Subscription

const subscription = await turratech.subscriptions.create({
  customer: 'cus_ABC123',
  items: [{
    price: 'price_pro_monthly',
    quantity: 1
  }],
  trial_period_days: 14
});

Webhooks

Webhooks allow you to receive real-time notifications when events happen in your TurraTech account. Configure webhook endpoints to receive POST requests with event data.

Webhook Signature Verification

All webhook payloads are signed using your webhook signing secret. Always verify the signature before processing webhook data.

const signature = req.headers['turratech-signature'];
const payload = req.body;

try {
  const event = turratech.webhooks.constructEvent(
    payload,
    signature,
    webhookSecret
  );
  // Handle the event
  console.log(`Received event: ${event.type}`);
} catch (err) {
  console.error('Webhook signature verification failed');
  return res.status(400).send();
}

Common Event Types