Payment API Integration: Developer's Complete Guide

API Integration

Payment API Integration: Developer's Complete Guide

August 1, 2024 15 min read TIB Finance Team

REST API Basics for Payments
Authentication
Creating Payment Sessions
Processing Transactions
Handling Responses
Error Codes Reference
Webhooks
SDKs: .NET, PHP, Python, JavaScript
Going Live Checklist

Integrating a payment API is one of the most consequential technical decisions in any application that accepts money. Done well, it provides a seamless customer experience, bulletproof security, and a foundation that scales with your business. Done poorly, it creates security vulnerabilities, payment failures, and a compliance nightmare.

This guide walks through every stage of a payment API integration with the TIB Finance API — from initial authentication through production deployment. All API endpoints are documented in detail in the TIB Finance Developer Documentation. Use the TIB Finance sandbox environment to test everything before going live.

REST API Basics for Payments

The TIB Finance API is a RESTful API that communicates over HTTPS. REST (Representational State Transfer) APIs use standard HTTP methods and return responses in JSON format. Before diving into payment-specific concepts, make sure you are comfortable with:

HTTP methods: POST (create), GET (retrieve), PUT/PATCH (update), DELETE (remove)
Status codes: 200/201 (success), 400 (bad request), 401 (unauthorized), 404 (not found), 422 (validation error), 500 (server error)
Request headers: Content-Type, Authorization, and payment-specific headers
JSON request/response bodies
Idempotency: Critical for payments — the ability to safely retry a request without creating duplicate charges

All API requests must be made over HTTPS. HTTP requests will be rejected. The base URL for production is https://api.tib.finance/v1 and for the sandbox is https://sandbox-api.tib.finance/v1.

Authentication

The TIB Finance API uses API key authentication. Every request must include your API key in the Authorization header using Bearer token format. You will have two types of keys:

Secret API Key: Used for server-side requests. This key has full API access. Never expose this in client-side JavaScript, mobile apps, or public repositories.
Publishable Key: Used in client-side code to initialize payment fields. Has limited scope — can only be used to tokenize card data, not to charge or retrieve sensitive information.

# All server-side API requests
curl https://api.tib.finance/v1/transactions \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
                        

Rotate your API keys immediately if you suspect they have been compromised. Keys can be rotated from your TIB Finance merchant dashboard. Never hardcode API keys in source code — use environment variables or a secrets management service.

Creating Payment Sessions

For integrations using TIB Finance's hosted payment fields, the flow begins on your server by creating a payment session. A session represents the intent to collect payment for a specific amount and returns a client-side token that your front-end uses to initialize the payment fields.

POST /v1/sessions

// Request body
{
  "amount": 4999,          // Amount in cents (e.g., $49.99)
  "currency": "USD",
  "reference": "ORDER-20240801-001",  // Your internal order ID
  "customer": {
    "email": "[email protected]",
    "name": "Jane Smith"
  },
  "capture_method": "automatic",  // or "manual" for auth-only
  "idempotency_key": "ide_ORDER-20240801-001"
}

// Response
{
  "session_id": "ses_7Xb3nP9mQrL2vK8w",
  "client_secret": "ses_7Xb3nP9mQrL2vK8w_secret_...",
  "expires_at": "2024-08-01T13:30:00Z",
  "status": "pending"
}
                        

The client_secret is passed to your front-end and used to initialize the TIB Finance payment fields JavaScript library. The actual card data is collected directly in those hosted fields and never passes through your servers.

Processing Transactions

Once the customer has entered their card details in the hosted payment fields and submitted, the TIB Finance JavaScript library handles tokenization and calls back to your server with a payment method token. Your server then uses this token to confirm the payment session or create a transaction directly.

Confirm a Session (Recommended Flow)

POST /v1/sessions/{session_id}/confirm

// Request
{
  "payment_method": "pm_3Kd9fN7mQpJ2vH4x"  // Token from hosted fields
}

// Successful response (HTTP 200)
{
  "transaction_id": "txn_9Yc4oQ8nRsM3wL5z",
  "status": "succeeded",
  "amount": 4999,
  "currency": "USD",
  "reference": "ORDER-20240801-001",
  "payment_method": {
    "token": "pm_3Kd9fN7mQpJ2vH4x",
    "last4": "1111",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2027
  },
  "created_at": "2024-08-01T12:34:56Z"
}
                        

Charging a Saved Payment Method

For returning customers with a saved payment method token, you can create a transaction directly without a hosted fields session:

POST /v1/transactions

{
  "amount": 4999,
  "currency": "USD",
  "payment_method": "pm_3Kd9fN7mQpJ2vH4x",
  "reference": "SUBSCRIPTION-202408",
  "idempotency_key": "sub_SUBSCRIPTION-202408"
}
                        

Handling Responses

Every API response includes a status field. For transactions, the possible statuses are:

succeeded: The transaction was approved and funds will be captured (or have been captured).
pending: The transaction is being processed. Expect a webhook event when it resolves.
requires_action: 3DS authentication is required. Follow the next_action instructions in the response.
failed: The transaction was declined or failed. Check the error object for details.
refunded / partially_refunded: A full or partial refund has been processed.

Always check the status field rather than relying solely on the HTTP status code. A 200 response with status: "failed" means the HTTP request succeeded but the payment was declined.

Error Codes Reference

The TIB Finance API returns structured error objects for all failure cases. The error object contains a machine-readable code and a human-readable message:

Error Code	HTTP Status	Meaning
card_declined	402	The card was declined by the issuing bank. Do not retry automatically.
insufficient_funds	402	The card has insufficient funds. Show user a message to use a different card.
expired_card	402	The card's expiration date has passed.
incorrect_cvc	402	The CVV provided does not match the card.
authentication_required	402	3DS authentication is needed. Follow next_action.
invalid_card_number	400	The card number format is invalid.
rate_limit_exceeded	429	Too many requests. Implement exponential backoff.
api_key_invalid	401	The provided API key is invalid or has been revoked.
idempotency_conflict	409	A request with this idempotency key already exists with different parameters.
server_error	500	A TIB Finance server error. Safe to retry with exponential backoff.

Webhooks

Webhooks allow TIB Finance to push real-time event notifications to your server rather than requiring you to poll the API for status updates. This is critical for handling asynchronous events like delayed payment confirmations, dispute creation, and subscription renewals. For a deep dive, see our guide to handling webhook events.

Configure your webhook endpoint URL in the TIB Finance merchant dashboard. Your endpoint must be publicly accessible, accept POST requests, and respond with HTTP 200 within 10 seconds. All webhook payloads are signed with your webhook secret — always verify the signature before processing.

SDKs: .NET, PHP, Python, JavaScript

TIB Finance provides official client libraries for the most common server-side languages, abstracting the HTTP layer and providing native error handling:

.NET (C#)

// Install via NuGet
// dotnet add package TibFinance.NET

using TibFinance;

var client = new TibFinanceClient("sk_live_YOUR_SECRET_KEY");
var transaction = await client.Transactions.CreateAsync(new TransactionCreateOptions {
    Amount = 4999,
    Currency = "USD",
    PaymentMethod = "pm_3Kd9fN7mQpJ2vH4x",
    Reference = "ORDER-001"
});
                        

PHP

// Install via Composer
// composer require tib-finance/php-sdk

require_once 'vendor/autoload.php';
\TibFinance\TibFinance::setApiKey('sk_live_YOUR_SECRET_KEY');

$transaction = \TibFinance\Transaction::create([
    'amount' => 4999,
    'currency' => 'USD',
    'payment_method' => 'pm_3Kd9fN7mQpJ2vH4x',
    'reference' => 'ORDER-001'
]);
                        

Python

# Install via pip
# pip install tibfinance

import tibfinance
tibfinance.api_key = "sk_live_YOUR_SECRET_KEY"

transaction = tibfinance.Transaction.create(
    amount=4999,
    currency="USD",
    payment_method="pm_3Kd9fN7mQpJ2vH4x",
    reference="ORDER-001"
)
                        

JavaScript / Node.js

// Install via npm
// npm install @tibfinance/node

const TibFinance = require('@tibfinance/node');
const client = new TibFinance('sk_live_YOUR_SECRET_KEY');

const transaction = await client.transactions.create({
  amount: 4999,
  currency: 'USD',
  payment_method: 'pm_3Kd9fN7mQpJ2vH4x',
  reference: 'ORDER-001'
});
                        

Going Live Checklist

Before switching from the sandbox to production, verify each of the following. See our complete sandbox testing guide for testing methodology.

All test scenarios pass in the sandbox (successful payment, declined card, insufficient funds, 3DS flow)
Webhook endpoint is implemented, verified, and handles all relevant event types
Idempotency keys are used on all transaction creation requests
Error handling covers all documented error codes and displays appropriate user messages
Secret API keys are stored in environment variables, not in code
Publishable key is correctly distinguished from secret key
TLS is enforced on all pages in the payment flow
Payment tokens are stored, not raw card numbers
Webhook signature verification is implemented
Rate limiting and retry logic with exponential backoff is implemented
Monitoring and alerting are set up for payment failures and API errors

Ready to Start Integrating?

Access the TIB Finance sandbox, full API documentation, and developer resources. Our integration support team is available to help.

View API Docs Access Sandbox

Payment API Integration: Developer's Complete Guide