Pay API

Pay API is a direct integration option that provides complete control over the payment experience. This approach requires more development effort but offers maximum flexibility for customized payment flows.

You would also utilize the Pay API for managing recurring debits or subscriptions. After you tokenize the user’s card details, you can use the token for future transactions using the Pay API directly.

Orders and Transactions

With Pay API, orders are automatically created when processing a transaction. You don’t need to create an order separately before processing a payment.

Important: Unlike some payment systems, there is no separate step to create an order. When you submit a transaction (PAY, AUTHORIZE, etc.), the system automatically creates an order to group related transactions.

Processing Transactions

When initiating transactions with Pay API, you can use one of two approaches:

1. Session-based approach (Recommended): If you’re using Pay Portal or Pay Session integration methods, you can reference a payment session using the session parameter.

2. SourceOfFunds approach: With Pay API, you can provide payment details directly through the sourceOfFunds field, using tokens (preferred) or direct card information.

For security and simplicity, using sessions or tokens is strongly recommended over direct card information to reduce PCI compliance scope.

For a complete reference of all transaction operations and examples of both approaches, visit the Transactions page.

Source of Funds Options

The Pay API gives you flexibility in how you provide payment details through the sourceOfFunds field:

Direct Card Information

sourceOfFunds: {
  card: {
    number: '4111111111111111',
    expiry: {
      month: '12',
      year: '25'
    },
    securityCode: '123'
  }
}

Tokenized Payment Method

See Tokenization page for more information.

sourceOfFunds: {
  token: "9169573510715182";
}

Authorization

Reserve funds on a customer’s payment method. The order must have a successful authorization before a capture transaction can be completed. The authorized amount must be greater than or equal to the amount being captured.

SourceOfFunds with Token

const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/ORDER-123/authorize`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 1299,
    },
    sourceOfFunds: {
      token: "9169573510715182",
    },
  }),
});

Direct Card Information (Higher PCI Scope)

const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/ORDER-123/authorize`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 1299,
    },
    sourceOfFunds: {
      card: {
        number: "4111111111111111",
        expiry: {
          month: "12",
          year: "25",
        },
        securityCode: "123",
      },
    },
  }),
});

Capture

Capture the funds for a previously authorized transaction:

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: 1299, // Can be equal to or less than the authorized amount
  }),
});

Pay

Process a payment in a single step (authorize and capture combined):

SourceOfFunds with Token

const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/ORDER-123/pay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 1299,
    },
    sourceOfFunds: {
      token: "9169573510715182",
    },
  }),
});
 
const transaction = await response.json();
// transaction.order contains the automatically created order ID

Direct Card Information (Higher PCI Scope)

const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/order/ORDER-123/pay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order: {
      amount: 1299,
    },
    sourceOfFunds: {
      card: {
        number: "4111111111111111",
        expiry: {
          month: "12",
          year: "25",
        },
        securityCode: "123",
      },
    },
  }),
});
 
const transaction = await response.json();

Refund

Return funds to a customer after a successful capture or pay transaction has been completed:

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: 1299, // Can be equal to or less than the original captured amount
  }),
});

Void

Cancel a pending transaction:

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.
  }),
});

Using Tokens

For enhanced security, improved checkout experiences, and recurring payments, we recommend using tokenization. The Pay API allows you to create tokens from payment details and then use those tokens for future transactions.

For more details on token management, see the Tokenization page.

Benefits of Using Tokens

Using tokens with the Pay API offers several advantages:

• Reduced PCI Scope: Minimize your exposure to sensitive card data (can reduce PCI compliance requirements)
• Improved Security: Store tokens instead of actual card details
• Faster Checkout: Enable one-click payments for returning customers
• Recurring Billing: Simplify subscription and installment payment processing
• Customer Management: Associate multiple payment methods with customer profiles

PCI Compliance Tip: Using tokenization with Pay API can help reduce your PCI DSS compliance scope, even though direct API integration typically requires SAQ D. See our PCI Compliance guide for more details.