Tokens (Saved Cards)

Tokens represent saved payment methods that can be reused for future payments, subscriptions, and installment plans.

Save a Card

The recommended way to save a card is through Hosted Checkout with mode: 'setup':

JavaScript

// Create a setup session
const session = await fyber.checkout.sessions.create({
  mode: 'setup',
  customerId: 'cus_123',
  successUrl: 'https://yoursite.com/card-saved?session_id={SESSION_ID}',
  cancelUrl: 'https://yoursite.com/cancel',
});

// Redirect to session.url

// After checkout completes, retrieve the token
const completed = await fyber.checkout.sessions.getBySessionId('cs_...');
const tokenId = completed.tokenId; // tok_xxx

PHP

$session = $fyber->checkout->sessions->create([
    'mode' => 'setup',
    'customerId' => 'cus_123',
    'successUrl' => 'https://yoursite.com/card-saved?session_id={SESSION_ID}',
    'cancelUrl' => 'https://yoursite.com/cancel',
]);

// After checkout completes
$completed = $fyber->checkout->sessions->getBySessionId('cs_...');
$tokenId = $completed['tokenId'];

C#

var session = await fyber.Checkout.Sessions.CreateAsync(new CreateCheckoutSessionRequest
{
    Mode = "setup",
    CustomerId = "cus_123",
    SuccessUrl = "https://yoursite.com/card-saved?session_id={SESSION_ID}",
    CancelUrl = "https://yoursite.com/cancel"
});

// After checkout completes
var completed = await fyber.Checkout.Sessions.GetBySessionIdAsync("cs_...");
var tokenId = completed.TokenId;

Token Purpose

When saving a card, specify the intended use:

Purpose	Description
general	General use (default)
recurring	Subscription billing
installment	Installment plans
unscheduled	Merchant-initiated transactions

Use a Saved Card

For Payments

const payment = await fyber.payments.create({
  amount: 5000,
  currency: 'JMD',
  tokenId: 'tok_123',
});

For Subscriptions

const subscription = await fyber.subscriptions.create({
  customerId: 'cus_123',
  tokenId: 'tok_123',
  amount: 999,
  interval: 'month',
});

For Installments

const plan = await fyber.installments.create({
  customerId: 'cus_123',
  tokenId: 'tok_123',
  totalAmount: 50000,
  installmentCount: 4,
});

Retrieve a Token

const token = await fyber.tokens.get('tok_123');

console.log(token.card.brand); // 'visa'
console.log(token.card.last4); // '4242'

List Customer's Tokens

const tokens = await fyber.tokens.list({
  customerId: 'cus_123',
});

for (const token of tokens.data) {
  const card = token.card;
  console.log(`${card.brand} •••• ${card.last4} (exp ${card.expMonth}/${card.expYear})`);
}

Set Default Token

Make a token the default payment method for a customer:

await fyber.tokens.setDefault('tok_123');

Delete a Token

await fyber.tokens.delete('tok_123');

Token Object

{
  "id": "tok_abc123",
  "object": "token",
  "customerId": "cus_123",
  "purpose": "recurring",
  "isDefault": true,
  "card": {
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2025,
    "funding": "credit"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Card Brands

Brand	Example
visa	4242 4242 4242 4242
mastercard	5555 5555 5555 4444
amex	3782 822463 10005

Webhooks

Listen for token events:

switch (event.type) {
  case 'token.created':
    console.log('Card saved:', event.data.object.id);
    break;
  case 'token.deleted':
    console.log('Card removed:', event.data.object.id);
    break;
}