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.

ℹ️

Important: Payment 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. You can use your own Payment ID or create one using the Update or Create Payment endpoint.

Payments and Transactions

With Pay API, if the provided payment ID does not already exist in our system, we will automatically create a new payment. No extra step is necessary to first create a payment. However, if you wish to do so, you can optionally create and manage payments directly with the API before processing transactions.

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

Processing Transactions

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

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.
Billing approach: With Pay API, you can provide payment details directly through the billing 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.

Billing Options

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

Direct Card Information

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

Tokenized Payment Method

See Tokenization page for more information.

payment: {
  billing: {
    token: "9169573510715182";
  },
}

Billing Address Verification

Address verification service (AVS) is used to confirm that a billing address matches the given card details. This is an optional feature that allows for more thorough customer verification. AVS is turned off by default and is controlled by the presence of the payment.billing.address object in the request body. If the "address" field is provided, then AVS will be used during payment authorization. This effects the authorize, pay, and verify endpoints.

payment: {
  billing: {
    address: {
      street: "Alpha St"
      city: "Conroe",
      stateProvince: "TX"
      postcodeZip: "77304",
      country: "USA",
    },
  },
}

Authorization

Reserve funds on a customer’s payment method. The payment 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.

Billing with Token

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

Direct Card Information (Higher PCI Scope)

const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/payment/PAYMENT-123/authorize`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payment: {
      amount: 1299,
      billing: {
        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}/payment/{paymentId}/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):

Billing with Token

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

const transaction = await response.json();
// transaction.payment contains the automatically created payment ID

Direct Card Information (Higher PCI Scope)

const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/payment/PAYMENT-123/pay`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payment: {
      amount: 1299,
      billing: {
        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}/payment/{paymentId}/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}/payment/{paymentId}/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.
  }),
});

Verify

Verify card information before processing a payment. Verification just confirms that the information is valid. It does not reserve any funds or check if enough funds are available. Requesting verification is not necessary to complete a payment.

Billing with Token

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

Direct Card Information (Higher PCI Scope)

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

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.