---
updatedAt: 2026-05-25T02:01:02.000Z
agentTools:
  projectIndex: https://checkout-docs.transfi.com/llms.txt
---

# TransFi SDK Documentation

<br />

# TransFi SDK Documentation

> Programmatically create and manage payment invoices using the TransFi Checkout API. SDKs are available for **Node.js** and **Python**.

***

## Prerequisites

Before using any SDK, you need:

1. A **TransFi merchant account** — [Sign up here](https://checkout-dashboard.transfi.com)
2. Your **Public Key** and **Secret Key** from the TransFi dashboard
3. A **Payment Link ID** — create one in the TransFi dashboard before making API calls

> **Security notice:** Never hardcode your Public Key or Secret Key in source code. Always store them in environment variables.

***

## Installation

```bash Node.js
npm install transfi-checkout
```
```python
pip install transfi-sdk
```
```java
Maven/Gradle via JitPack (com.github.Trans-Fi:transfi-checkout-java-sdk:v1.0.0)
```
```php
composer require transfi/payment-sdk
```

***

## Authentication

Both SDKs use **HMAC-based authentication** built in automatically — you only need to pass your keys when initializing the client.

```javascript Node.js
const { TransFiPaymentAPI } = require("transfi-checkout");

const client = new TransFiPaymentAPI({
  publicKey: process.env.TRANSFI_PUBLIC_KEY,
  secretKey: process.env.TRANSFI_SECRET_KEY,
});
```
```python
from transfi import TransFiPaymentAPI

api = TransFiPaymentAPI(
    public_key="YOUR_PUBLIC_KEY",
    secret_key="YOUR_SECRET_KEY",
)
```
```java
sdkConfig config = new sdkConfig("YOUR_PUBLIC_KEY", "YOUR_SECRET_KEY");
transfiPaymentApi api = new transfiPaymentApi(config);
```
```php
use TransFi\TransFiPaymentAPI;
use TransFi\TransFiError;
use TransFi\PaymentInvoiceRequest;
use TransFi\Individual;
use TransFi\ProductDetails;

$api = new TransFiPaymentAPI([
    'publicKey' => 'YOUR_PUBLIC_KEY',
    'secretKey' => 'YOUR_SECRET_KEY',
]);

```

| Parameter                  | Type   | Required | Description                 |
| :------------------------- | :----- | :------- | :-------------------------- |
| `publicKey` / `public_key` | string | Yes      | Your TransFi API public key |
| `secretKey` / `secret_key` | string | Yes      | Your TransFi API secret key |

***

## Quick Start

```javascript Node.js
const { TransFiPaymentAPI } = require("transfi-checkout");

const client = new TransFiPaymentAPI({
  publicKey: process.env.TRANSFI_PUBLIC_KEY,
  secretKey: process.env.TRANSFI_SECRET_KEY,
});

client
  .createPaymentInvoice({
    paymentLinkId: "your-payment-link-id",
    amount: "100",
    currency: "USD",
    productDetails: {
      name: "Premium Annual Plan",
      description: "12-month access to all premium features",
      imageUrl: "https://example.com/product-image.png",
    },
    successRedirectUrl: "https://yourapp.com/payment/success",
    failureRedirectUrl: "https://yourapp.com/payment/failure",
  })
  .then((paymentUrl) => {
    console.log("Redirect customer to:", paymentUrl);
  })
  .catch((error) => {
    console.error("Error:", error.message);
  });
```
```python
from transfi import TransFiPaymentAPI, TransFiError
from transfi.types import PaymentInvoiceRequest, ProductDetails

api = TransFiPaymentAPI(
    public_key="YOUR_PUBLIC_KEY",
    secret_key="YOUR_SECRET_KEY",
)

request = PaymentInvoiceRequest(
    payment_link_id="your-payment-link-id",
    amount="100",
    currency="USD",
    product_details=ProductDetails(
        name="Premium Annual Plan",
        description="12-month access to all premium features",
        image_url="https://example.com/product-image.png",
    ),
    success_redirect_url="https://yourapp.com/payment/success",
    failure_redirect_url="https://yourapp.com/payment/failure",
)

try:
    payment_url = api.create_payment_invoice(request)
    print("Redirect customer to:", payment_url)
except TransFiError as e:
    print("Error:", e)
```
```java
paymentInvoiceRequest request = paymentInvoiceRequest.builder()
    .paymentLinkId("YOUR_PAYMENT_LINK_ID")
    .amount("100.00")
    .currency("USD")
    .productDetails(productDetails.builder()
        .name("Premium Subscription")
        .description("Monthly subscription plan")
        .build())
    .individual(individual.builder()
        .firstName("John")
        .lastName("Doe")
        .email("john.doe@example.com")
        .phone("1234567890")
        .phoneCode("+1")
        .country("US")
        .build())
    .successRedirectUrl("https://yoursite.com/success")
    .failureRedirectUrl("https://yoursite.com/failure")
    .customerOrderId("order-" + System.currentTimeMillis())
    .build();

try {
    String paymentUrl = api.createPaymentInvoice(request);
    System.out.println("Payment URL: " + paymentUrl);
    // Redirect user to paymentUrl to complete payment
} catch (transfiError e) {
    System.err.println("Error: " + e.getMessage());
    System.err.println("Status Code: " + e.getStatusCode());
    System.err.println("Response: " + e.getResponseData());
}
```
```php

use TransFi\TransFiPaymentAPI;
use TransFi\TransFiError;
use TransFi\PaymentInvoiceRequest;
use TransFi\Individual;
use TransFi\ProductDetails;

$api = new TransFiPaymentAPI([
    'publicKey' => 'YOUR_PUBLIC_KEY',
    'secretKey' => 'YOUR_SECRET_KEY',
]);

$product = new ProductDetails('Premium Plan');
$product->description = 'Monthly subscription';

$individual = new Individual('John', 'Doe', 'john@example.com');
$individual->phone     = '1234567890';
$individual->phoneCode = '+1';
$individual->country   = 'US';

$paymentData = new PaymentInvoiceRequest(
    'LINK_ID',
    '100',
    'USD',
    'https://example.com/success',
    'https://example.com/failure'
);
$paymentData->productDetails  = $product;
$paymentData->individual      = $individual;
$paymentData->customerOrderId = 'order-001';

try {
    $paymentUrl = $api->createPaymentInvoice($paymentData);
    echo 'Checkout URL: ' . $paymentUrl . PHP_EOL;
} catch (TransFiError $e) {
    echo 'API Error   : ' . $e->getMessage() . PHP_EOL;
    echo 'Status Code : ' . $e->getStatusCode() . PHP_EOL;
    echo 'Response    : ' . json_encode($e->getResponseData(), JSON_PRETTY_PRINT) . PHP_EOL;
}
```

***

## Methods

### `createPaymentInvoice` / `create_payment_invoice`

Creates a payment invoice for a customer and returns a **payment URL** to redirect the customer to complete the payment.

```javascript Node.js
const paymentUrl = await client.createPaymentInvoice(paymentData);
// Returns: Promise<string> — the checkout URL
```
```python
payment_url = api.create_payment_invoice(request)
# Returns: str — the checkout URL
```
```java
String paymentUrl = api.createPaymentInvoice(request);
//// Returns: String — the checkout URL
```
```php
    $paymentUrl = $api->createPaymentInvoice($paymentData);
    echo 'Checkout URL: ' . $paymentUrl . PHP_EOL;
```

***

## Parameters

### Payment Invoice Request

```javascript Node.js
{
  paymentLinkId: "string",        // Required
  amount: "string",               // Required — e.g. "100" or "49.99"
  currency: "string",             // Required — ISO 4217, e.g. "USD"
  successRedirectUrl: "string",   // Required
  failureRedirectUrl: "string",   // Required
  productDetails: { ... },        // Optional — see below
  individual: { ... },            // Optional — see below
  customerOrderId: "string",      // Optional — your internal order ID
}
```
```python
PaymentInvoiceRequest(
    payment_link_id="string",         # Required
    amount="string",                  # Required — e.g. "100" or "49.99"
    currency="string",                # Required — ISO 4217, e.g. "USD"
    success_redirect_url="string",    # Required
    failure_redirect_url="string",    # Required
    product_details=ProductDetails(), # Optional — see below
    individual=Individual(),          # Optional — see below
    customer_order_id="string",       # Optional — your internal order ID
)
```
```java
//Builder pattern for creating payment requests:

paymentInvoiceRequest.builder()
    .paymentLinkId(String)           // Required: Payment link identifier
    .amount(String)                  // Required: Payment amount
    .currency(String)                // Required: Currency code (USD, EUR, etc.)
    .productDetails(productDetails)  // Optional — see below
    .individual(individual)          // Optional — see below
    .successRedirectUrl(String)      // Required: Success redirect URL
    .failureRedirectUrl(String)      // Required: Failure redirect URL
    .customerOrderId(String)         // Optional — see below
     .build();
```
```php

$paymentData = new PaymentInvoiceRequest(
    'LINK_ID',
    '100',
    'USD',
    'https://example.com/success',
    'https://example.com/failure'
);
$paymentData->productDetails  = $product;
$paymentData->individual      = $individual;
$paymentData->customerOrderId = 'order-001';
```

<br />

| Parameter       | Node.js key          | Python key             | PHP Key              | Java   Key           | Type   | Required | Description                                     |
| :-------------- | :------------------- | :--------------------- | :------------------- | :------------------- | :----- | :------- | :---------------------------------------------- |
| Payment Link ID | `paymentLinkId`      | `payment_link_id`      | `paymentLinkId`      | `paymentLinkId`      | string | **Yes**  | The Payment Link ID from your TransFi dashboard |
| Amount          | `amount`             | `amount`               | `amount`             | `amount`             | string | **Yes**  | Amount to charge, e.g. `"100"` or `"49.99"`     |
| Currency        | `currency`           | `currency`             | `currency`           | `currency`           | string | **Yes**  | ISO 4217 code, e.g. `"USD"`, `"EUR"`, `"SGD"`   |
| Success URL     | `successRedirectUrl` | `success_redirect_url` | `successRedirectUrl` | `successRedirectUrl` | string | **Yes**  | Redirect URL after successful payment           |
| Failure URL     | `failureRedirectUrl` | `failure_redirect_url` | `failureRedirectUrl` | `failureRedirectUrl` | string | **Yes**  | Redirect URL after failed payment               |
| Product Details | `productDetails`     | `product_details`      | `productDetails`     | `productDetails`     | object | No       | Product info shown at checkout                  |
| Customer        | `individual`         | `individual`           | `individual`         | `individual`         | object | No       | Customer details for pre-fill / KYC             |
| Order ID        | `customerOrderId`    | `customer_order_id`    | `customerOrderId`    | `customerOrderId`    | string | No       | Your internal order reference ID                |

***

### `productDetails` / `ProductDetails`

Product information displayed on the checkout page.

| Field       | Node.js key   | Python key    | Required | Description                      |
| :---------- | :------------ | :------------ | :------- | :------------------------------- |
| Name        | `name`        | `name`        | **Yes**  | Name of the product or service   |
| Description | `description` | `description` | No       | Short description of the product |
| Image URL   | `imageUrl`    | `image_url`   | No       | URL of a product image           |

```javascript Node.js
productDetails: {
  name: "Premium Annual Plan",
  description: "12-month access to all features",
  imageUrl: "https://example.com/product.png",
}
```
```python
from transfi.types import ProductDetails

ProductDetails(
    name="Premium Annual Plan",
    description="12-month access to all features",
    image_url="https://example.com/product.png",
)
```
```java
productDetails(productDetails.builder()
        .name("Premium Subscription")
        .description("Monthly subscription plan")
        .build())
```
```php
'productDetails'     => [
        'name'        => 'Premium Plan',
        'description' => 'Monthly subscription',
    ]
```

***

### `individual` / `Individual`

Customer information used to pre-fill the checkout form or speed up KYC verification.

| Field      | Node.js key | Python key   | Required | Description                                                       |
| :--------- | :---------- | :----------- | :------- | :---------------------------------------------------------------- |
| First name | `firstName` | `first_name` | **Yes**  | Customer's first name                                             |
| Last name  | `lastName`  | `last_name`  | **Yes**  | Customer's last name                                              |
| Email      | `email`     | `email`      | **Yes**  | Customer's email address                                          |
| Phone      | `phone`     | `phone`      | No       | Phone number without country code                                 |
| Phone code | `phoneCode` | `phone_code` | No       | Dialing code, e.g. `"+1"`, `"+91"`                                |
| Country    | `country`   | `country`    | No       | ISO 3166-1 alpha-3 (Node.js: `"USA"`) or alpha-2 (Python: `"US"`) |
| Address    | `address`   | `address`    | No       | Customer's address (see below)                                    |

```javascript Node.js
individual: {
  firstName: "Jane",
  lastName: "Smith",
  email: "jane.smith@example.com",
  phone: "9876543210",
  phoneCode: "+1",
  country: "USA",
  address: {
    street: "123 Main St",
    city: "New York",
    state: "NY",
    postalCode: "10001",
  },
}
```
```python
from transfi.types import Individual, Address

Individual(
    first_name="Jane",
    last_name="Smith",
    email="jane.smith@example.com",
    phone="9876543210",
    phone_code="+1",
    country="US",
    address=Address(
        street="123 Main St",
        city="New York",
        state="NY",
        postal_code="10001",
    ),
)
```
```java
individual(individual.builder()
        .firstName("John")
        .lastName("Doe")
        .email("john.doe@example.com")
        .phone("1234567890")
        .phoneCode("+1")
        .country("US")
        .build())
```
```php
'individual'         => [
        'firstName' => 'John',
        'lastName'  => 'Doe',
        'email'     => 'john@example.com',
        'phone'     => '1234567890',
        'phoneCode' => '+1',
        'country'   => 'US',
    ]
```

<br />

#### `address` / `Address`

| Field       | Node.js key  | Python key    | Description        |
| :---------- | :----------- | :------------ | :----------------- |
| Street      | `street`     | `street`      | Street address     |
| City        | `city`       | `city`        | City name          |
| State       | `state`      | `state`       | State or province  |
| Postal code | `postalCode` | `postal_code` | ZIP or postal code |

***

## Error Handling

Both SDKs throw a `TransFiError` when an API call fails.

| Property      | Node.js              | Python            | Type   | Description                                |
| :------------ | :------------------- | :---------------- | :----- | :----------------------------------------- |
| Message       | `error.message`      | `str(e)`          | string | Human-readable error message               |
| Status code   | `error.statusCode`   | `e.status_code`   | number | HTTP status code, e.g. `400`, `401`, `500` |
| Response body | `error.responseData` | `e.response_data` | any    | Raw JSON response from the API             |

```javascript Node.js
const { TransFiPaymentAPI, TransFiError } = require("transfi-checkout");

try {
  const paymentUrl = await client.createPaymentInvoice({ ... });
} catch (error) {
  if (error instanceof TransFiError) {
    console.error("TransFi API Error:", error.message);
    console.error("HTTP Status:", error.statusCode);   // e.g. 401, 400
    console.error("API Response:", error.responseData); // full error body
  } else {
    // Network error, timeout, etc.
    console.error("Unexpected error:", error.message);
  }
}
```
```python
from transfi import TransFiPaymentAPI, TransFiError

try:
    payment_url = api.create_payment_invoice(request)
except TransFiError as e:
    print("API Error:   ", e)
    print("Status Code: ", e.status_code)
    print("Response:    ", e.response_data)
except Exception as e:
    # Network error, timeout, etc.
    print("Unexpected error:", e)
```
```java
try {
    String paymentUrl = api.createPaymentInvoice(request);
    System.out.println("Payment URL: " + paymentUrl);
    // Redirect user to paymentUrl to complete payment
} catch (transfiError e) {
    System.err.println("Error: " + e.getMessage());
    System.err.println("Status Code: " + e.getStatusCode());
    System.err.println("Response: " + e.getResponseData());
}

```
```php
try {
    $paymentUrl = $api->createPaymentInvoice($paymentData);
    echo 'Checkout URL: ' . $paymentUrl . PHP_EOL;
} catch (TransFiError $e) {
    echo 'API Error   : ' . $e->getMessage() . PHP_EOL;
    echo 'Status Code : ' . $e->getStatusCode() . PHP_EOL;
    echo 'Response    : ' . json_encode($e->getResponseData(), JSON_PRETTY_PRINT) . PHP_EOL;
}
```

### Common HTTP status codes

| Status | Meaning      | Common cause                                        |
| :----- | :----------- | :-------------------------------------------------- |
| `400`  | Bad Request  | Missing required fields or invalid parameter values |
| `401`  | Unauthorized | Invalid or missing API keys                         |
| `404`  | Not Found    | `paymentLinkId` does not exist in your account      |
| `500`  | Server Error | Temporary TransFi API issue — retry with backoff    |

***

## Full Example

```javascript Node.js
const { TransFiPaymentAPI, TransFiError } = require("transfi-checkout");

const client = new TransFiPaymentAPI({
  publicKey: process.env.TRANSFI_PUBLIC_KEY,
  secretKey: process.env.TRANSFI_SECRET_KEY,
});

async function createInvoice() {
  try {
    const paymentUrl = await client.createPaymentInvoice({
      paymentLinkId: "your-payment-link-id",
      amount: "149.99",
      currency: "USD",
      customerOrderId: "order-" + Date.now(),
      productDetails: {
        name: "Premium Annual Plan",
        description: "12-month access to all premium features",
        imageUrl: "https://example.com/product-image.png",
      },
      individual: {
        firstName: "Jane",
        lastName: "Smith",
        email: "jane.smith@example.com",
        phone: "9876543210",
        phoneCode: "+1",
        country: "USA",
        address: {
          street: "123 Main St",
          city: "New York",
          state: "NY",
          postalCode: "10001",
        },
      },
      successRedirectUrl: "https://yourapp.com/payment/success",
      failureRedirectUrl: "https://yourapp.com/payment/failure",
    });

    console.log("Invoice created! Redirect user to:");
    console.log(paymentUrl);
  } catch (error) {
    if (error instanceof TransFiError) {
      console.error(`API Error [${error.statusCode}]: ${error.message}`);
      console.error("Details:", error.responseData);
    } else {
      console.error("Network or unexpected error:", error.message);
    }
  }
}

createInvoice();
```
```python
from transfi import TransFiPaymentAPI, TransFiError
from transfi.types import PaymentInvoiceRequest, Individual, ProductDetails, Address
import time

api = TransFiPaymentAPI(
    public_key="YOUR_PUBLIC_KEY",
    secret_key="YOUR_SECRET_KEY",
)

request = PaymentInvoiceRequest(
    payment_link_id="your-payment-link-id",
    amount="149.99",
    currency="USD",
    customer_order_id=f"order-{int(time.time())}",
    product_details=ProductDetails(
        name="Premium Annual Plan",
        description="12-month access to all premium features",
        image_url="https://example.com/product-image.png",
    ),
    individual=Individual(
        first_name="Jane",
        last_name="Smith",
        email="jane.smith@example.com",
        phone="9876543210",
        phone_code="+1",
        country="US",
        address=Address(
            street="123 Main St",
            city="New York",
            state="NY",
            postal_code="10001",
        ),
    ),
    success_redirect_url="https://yourapp.com/payment/success",
    failure_redirect_url="https://yourapp.com/payment/failure",
)

try:
    payment_url = api.create_payment_invoice(request)
    print("Invoice created! Redirect user to:")
    print(payment_url)
except TransFiError as e:
    print(f"API Error [{e.status_code}]: {e}")
    print("Details:", e.response_data)
except Exception as e:
    print("Network or unexpected error:", e)
```
```java
paymentInvoiceRequest request = paymentInvoiceRequest.builder()
    .paymentLinkId("YOUR_PAYMENT_LINK_ID")
    .amount("100.00")
    .currency("USD")
    .productDetails(productDetails.builder()
        .name("Premium Subscription")
        .description("Monthly subscription plan")
        .build())
    .individual(individual.builder()
        .firstName("John")
        .lastName("Doe")
        .email("john.doe@example.com")
        .phone("1234567890")
        .phoneCode("+1")
        .country("US")
        .build())
    .successRedirectUrl("https://yoursite.com/success")
    .failureRedirectUrl("https://yoursite.com/failure")
    .customerOrderId("order-" + System.currentTimeMillis())
    .build();

try {
    String paymentUrl = api.createPaymentInvoice(request);
    System.out.println("Payment URL: " + paymentUrl);
    // Redirect user to paymentUrl to complete payment
} catch (transfiError e) {
    System.err.println("Error: " + e.getMessage());
    System.err.println("Status Code: " + e.getStatusCode());
    System.err.println("Response: " + e.getResponseData());
}
```
```php
$api = new TransFiPaymentAPI([
    'publicKey' => 'YOUR_PUBLIC_KEY',
    'secretKey' => 'YOUR_SECRET_KEY',
]);

$product = new ProductDetails('Premium Plan');
$product->description = 'Monthly subscription';

$individual = new Individual('John', 'Doe', 'john@example.com');
$individual->phone     = '1234567890';
$individual->phoneCode = '+1';
$individual->country   = 'US';

$paymentData = new PaymentInvoiceRequest(
    'LINK_ID',
    '100',
    'USD',
    'https://example.com/success',
    'https://example.com/failure'
);
$paymentData->productDetails  = $product;
$paymentData->individual      = $individual;
$paymentData->customerOrderId = 'order-001';

try {
    $paymentUrl = $api->createPaymentInvoice($paymentData);
    echo 'Checkout URL: ' . $paymentUrl . PHP_EOL;
} catch (TransFiError $e) {
    echo 'API Error   : ' . $e->getMessage() . PHP_EOL;
    echo 'Status Code : ' . $e->getStatusCode() . PHP_EOL;
    echo 'Response    : ' . json_encode($e->getResponseData(), JSON_PRETTY_PRINT) . PHP_EOL;
}
```

***

## Python: Alternative dict syntax

The Python SDK also accepts a plain `dict` with camelCase keys matching the JSON API directly, if you prefer not to use the dataclasses:

```python
payment_url = api.create_payment_invoice({
    "paymentLinkId": "your-payment-link-id",
    "amount": "100",
    "currency": "USD",
    "productDetails": {
        "name": "Premium Plan",
        "description": "Monthly subscription",
    },
    "individual": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": "1234567890",
        "phoneCode": "+1",
        "country": "US",
    },
    "successRedirectUrl": "https://example.com/success",
    "failureRedirectUrl": "https://example.com/failure",
    "customerOrderId": "order-001",
})
```

***

## Python: Context manager

The Python client supports the context manager protocol, which ensures the underlying HTTP session is properly closed:

```python
with TransFiPaymentAPI(public_key="...", secret_key="...") as api:
    payment_url = api.create_payment_invoice(request)
    print(payment_url)
```

***

## SDK Reference Summary

|                 | Node.js (`transfi-checkout`)        | Java(`transfi-checkout`)                                                          | Python (`transfi-sdk`)              | PHP (transfi/payment-sdk)                                          |
| :-------------- | :---------------------------------- | :-------------------------------------------------------------------------------- | :---------------------------------- | :----------------------------------------------------------------- |
| Install         | `npm install transfi-checkout`      | `Maven/Gradle via JitPack (com.github.Trans-Fi:transfi-checkout-java-sdk:v1.0.0)` | `pip install transfi-sdk`           | `composer require transfi/payment-sdk`                             |
| Import          | `require("transfi-checkout")`       | `No explicit import needed (classes used directly)`                               | `from transfi import ...`           | `use TransFi\TransFiPaymentAPI`                                    |
| Client class    | `TransFiPaymentAPI`                 | `transfiPaymentApi`                                                               | `TransFiPaymentAPI`                 | `TransFiPaymentAPI`                                                |
| Create invoice  | `client.createPaymentInvoice(data)` | `api.createPaymentInvoice(request)`                                               | `api.create_payment_invoice(data)`  | `$api->createPaymentInvoice($data)`                                |
| Error class     | `TransFiError`                      | `transfiError`                                                                    | `TransFiError`                      | `TransFiError`                                                     |
| Status code     | `error.statusCode`                  | `e.getStatusCode()`                                                               | `e.status_code`                     | `$e->getStatusCode()`                                              |
| Response body   | `error.responseData`                | `e.getResponseData()`                                                             | `e.response_data`                   | `$e->getResponseData()`                                            |
| Context manager | No                                  | `No`                                                                              | Yes (`with` statement)              | `No`                                                               |
| Dict input      | Yes (camelCase keys)                | `No (Builder pattern)`                                                            | Yes (camelCase keys)                | `Yes (plain array, camelCase keys)`                                |
| Typed input     | No                                  | `Yes (paymentInvoiceRequest, productDetails, individual builders)`                | Yes (`PaymentInvoiceRequest`, etc.) | `Yes (PaymentInvoiceRequest, Individual, ProductDetails, Address)` |

<br />