Transactions

Transactions are the core operations in Prahsys Payments. They represent various payment actions like authorizations, captures, payments, refunds, and voids. This page explains how transactions work and how to use them effectively.

ℹ️

Important: Order IDs are created/generated by you before making API calls. These IDs should be unique identifiers in your system and are passed in the request URLs. They are not created by the API but are predetermined on your side.

Transaction Types

The Prahsys Payments API supports several transaction types. When processing transactions, you can use one of two approaches depending on your integration method:

  1. Session-based (Recommended): When using Pay Portal or Pay Session, you’ll typically specify a session parameter that references a payment session where card details were securely collected. Order information can also be stored in the session.

  2. SourceOfFunds-based: When using Pay API, you can specify a sourceOfFunds object that contains either a token or direct payment details.

For security and simplicity, the examples below primarily use tokens with the sourceOfFunds approach. Using sessions or tokens is strongly recommended over direct card information to reduce PCI compliance scope.

Authorization

An authorization reserves funds on a customer’s payment method without actually transferring the money. This is useful for verifying that funds are available before fulfilling an order.

Server-side JavaScript - Session-based approach (recommended)
// Request to authorize funds using a session
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/authorize`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 12.99, // Only necessary if the order details aren't stored in the session or if you want to update the order
    },
    session: {
      id: "SESSION0002742481646J67219140J7",
    },
  }),
});
Server-side JavaScript - SourceOfFunds with token
// Request to authorize funds using a token
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/authorize`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 12.99,
    },
    sourceOfFunds: {
      token: "9169573510715182",
    },
  }),
});

Capture

A capture completes a previously authorized order, actually transferring the funds from the customer to your account.

Server-side JavaScript
// Request to capture previously authorized funds
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/capture`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 12.99, // Can be equal to or less than the authorized amount
  }),
});

Pay

A pay transaction combines authorization and capture into a single step, immediately transferring funds from the customer to your account.

Server-side JavaScript - Session-based approach (recommended)
// Request to process a payment in one step using a session
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/pay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 12.99, // Only necessary if the order details aren't stored in the session or if you want to update the order
    },
    session: {
      id: "SESSION0002742481646J67219140J7",
    },
  }),
});
Server-side JavaScript - SourceOfFunds with token
// Request to process a payment in one step using a token
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/pay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 12.99,
    },
    sourceOfFunds: {
      token: "9169573510715182",
    },
  }),
});

Refund

A refund returns funds to a customer after a successful capture or pay transaction.

Server-side JavaScript
// Request to refund a payment
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/refund`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 12.99, // Can be equal to or less than the original captured amount
    // Note: No need to specify sourceOfFunds for refunds as it uses the original payment method
  }),
});

Void

A void cancels a pending authorization before it’s captured, preventing any funds from being transferred.

Server-side JavaScript
// Request to void an authorization
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/void`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetTransactionId: "AUTHORIZE-20250327-192029", // Each transaction returns a transaction ID in the response. Use this ID to reference previous transactions.
    // Note: No need to specify sourceOfFunds for voids as it uses the original payment method
  }),
});

Retrieving Transaction Details

You can retrieve details of a specific transaction using the transaction ID which is returned in all transaction responses:

Server-side JavaScript
const response = await fetch(
  `https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/transaction/${transactionId}`,
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);

Common Transaction Scenarios

Auth-Capture Flow

The auth-capture flow is commonly used for e-commerce:

  1. Create a session or token
  2. Authorize at checkout to verify funds
  3. Capture when order is shipped
Server-side JavaScript - Session-based approach
// Step 1: Already have a session (SESSION0002742481646J67219140J7)
 
// Step 2: Authorize
const authResponse = await fetch(
  `https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/authorize`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      order: {
        amount: 12.99, // Only necessary if the order details aren't stored in the session or if you want to update the order
      },
      session: {
        id: "SESSION0002742481646J67219140J7",
      },
    }),
  },
);
const transaction = await authResponse.json();
 
// Step 3: Later, when the order ships, capture the payment
const captureResponse = await fetch(
  `https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/capture`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 12.99,
    }),
  },
);

Using a Token

Server-side JavaScript - Token-based approach
// Step 1: Already have a token (9169573510715182)
 
// Step 2: Authorize
const authResponse = await fetch(
  `https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/authorize`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      order: {
        amount: 12.99,
      },
      sourceOfFunds: {
        token: "9169573510715182",
      },
    }),
  },
);
const transaction = await authResponse.json();
 
// Step 3: Later, when the order ships, capture the payment
const captureResponse = await fetch(
  `https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/capture`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 12.99,
    }),
  },
);

Pay Flow

The pay flow is used for immediate payment:

  1. Create a session or token
  2. Process payment in a single step
  3. Refund if necessary
Server-side JavaScript - Session-based approach
// Step 1: Already have a session (SESSION0002742481646J67219140J7)
 
// Step 2: Pay
const payResponse = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/pay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 12.99, // Only necessary if the order details aren't stored in the session or if you want to update the order
    },
    session: {
      id: "SESSION0002742481646J67219140J7",
    },
  }),
});
const transaction = await payResponse.json();
 
// Step 3: If needed, refund the payment
const refundResponse = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/refund`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 12.99,
  }),
});

Using a Token

Server-side JavaScript - Token-based approach
// Step 1: Already have a token (9169573510715182)
 
// Step 2: Pay
const payResponse = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/pay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 12.99,
    },
    sourceOfFunds: {
      token: "9169573510715182",
    },
  }),
});
const transaction = await payResponse.json();
 
// Step 3: If needed, refund the payment
const refundResponse = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/{orderId}/refund`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 12.99,
  }),
});

Recurring Billing

For subscriptions and recurring payments:

  1. Create a token from the initial payment method
  2. Process recurring transactions using the token
Server-side JavaScript
// Step 1: Create a token (if you don't already have one)
const tokenResponse = await fetch("https://api.prahsys.com/payments/n1/merchant/{merchantId}/token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceOfFunds: {
      card: {
        number: "4111111111111111",
        expiry: {
          month: "12",
          year: "25",
        },
        securityCode: "123",
      },
    },
  }),
});
const token = await tokenResponse.json();
 
// Step 2: Use token for initial payment
// ... (same as Pay Flow Step 2)
 
// Step 3: Use the same token for recurring payments
const recurringPaymentResponse = await fetch(
  `https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/RECURRING-ORDER-456/pay`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      order: {
        amount: 12.99,
      },
      sourceOfFunds: {
        token: token.id,
      },
    }),
  },
);