Payments

The Payments API allows you to create, retrieve, capture, and cancel payment transactions.

Payment Lifecycle

Created → Authorized → Captured → Succeeded
                    ↘ Canceled

Status	Description
pending	Payment is being processed
authorized	Funds are held, awaiting capture
succeeded	Payment completed successfully
failed	Payment was declined
canceled	Payment was canceled/voided

Create a Payment

Payments are typically created through Hosted Checkout, which is the recommended approach. The examples below show direct API usage for advanced integrations.

Using a Saved Token

const payment = await fyber.payments.create({
  amount: 5000, // $50.00 in cents
  currency: 'JMD',
  tokenId: 'tok_123', // Saved card token
  description: 'Order #1234',
  metadata: {
    orderId: '1234'
  }
});

Authorize Only

Hold funds without capturing:

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

// Capture later
await fyber.payments.capture(payment.id);

Retrieve a Payment

const payment = await fyber.payments.get('pay_123');

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

List Payments

const payments = await fyber.payments.list({
  limit: 20,
  status: 'succeeded',
  customerId: 'cus_123', // Optional filter
});

for (const payment of payments.data) {
  console.log(`${payment.id}: $${payment.amount / 100}`);
}

Capture a Payment

Capture an authorized payment:

// Full capture
const captured = await fyber.payments.capture('pay_123');

// Partial capture
const captured = await fyber.payments.capture('pay_123', {
  amount: 3000, // Capture $30 of $50 authorized
});

Authorizations expire after 7 days if not captured.

Cancel a Payment

Cancel an authorized payment to release the hold:

await fyber.payments.cancel('pay_123');

Only authorized (uncaptured) payments can be canceled. For captured payments, use Refunds.

Payment Object

{
  "id": "pay_abc123",
  "object": "payment",
  "amount": 5000,
  "amountCaptured": 5000,
  "amountRefunded": 0,
  "currency": "JMD",
  "status": "succeeded",
  "description": "Order #1234",
  "customerId": "cus_123",
  "tokenId": "tok_456",
  "metadata": {
    "orderId": "1234"
  },
  "card": {
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2025
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Create Payment Parameters

Parameter	Type	Required	Description
amount	integer	Yes	Amount in cents
currency	string	Yes	Three-letter currency code
tokenId	string	No	Saved card token
customerId	string	No	Customer ID
description	string	No	Payment description
capture	boolean	No	Auto-capture (default: true)
metadata	object	No	Custom key-value data

3D Secure

3D Secure (3DS) authentication is handled automatically when using Hosted Checkout. For direct API integrations, payments requiring 3DS will return a requires_action status with a redirect URL.

Idempotency

Include an Idempotency-Key header to safely retry requests:

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

Repeated requests with the same key return the original response.