Payment Button

This guide will walk you through the steps to create a payment button that will take users to a paytheory checkout page.

1. Import the SDK

You need to use the Pay Theory Web SDK. This is available by adding the below script into your web header. This button will open a hosted checkout page that will allow the user to select a payment method and complete the payment.

The SDK URL can be found in the Pay Theory portal under the settings tab as the SDK Import URL.

<script src={SDK Import URL}> </script>

---

2. Add Pay Theory element to your Html

This div is used to mount an iframe that will include a checkout button. You need to add the Pay Theory elements to your HTML. You can place these elements anywhere in your HTML and the SDK will place the button in the correct place.

<div id="pay-theory-checkout-button" ></div>

---

3. Prepare the checkout details

You will need to put together the details of the checkout. This includes the amount, payment name, and any other details you want to pass to the checkout.

javascript

//Amount passed in is in cents
const AMOUNT = 1000

const PAYMENT_METADATA = {
  "student-name": "Pat Theodore"
};

// Parameters that you will pass in to configure the checkout page that opens when the button is clicked.
const CHECKOUT_DETAILS = {
  amount: AMOUNT,
  paymentName: "School Technology Fees",

  acceptedPaymentMethods: paytheory.ONLY_CARD,
  payorId: "ptl_pay_5Q860Z2ouH3KKLnWfNpyxd",
  metadata: PAYMENT_METADATA,
  recurringId: "ptl_rec_64ImZH6LpufCQddDXX2OYH",
}

Use either invoiceId or recurringId in checkoutDetails, not both. These are the parameters that you can pass into the checkoutDetails object to customize the checkout page that opens when the button is clicked.

Required parameters:

Key	type	description
amount	int	The amount of the payment in cents.
paymentName	string	The name of the payment that will be displayed on the checkout page. Will also be passed in to the reference field of the transaction.

Optional parameters:

Key	type	description
acceptedPaymentMethods	string	The payment methods that will be accepted for the payment. Defaults to paytheory.ALL. Constants are available from the SDK. Available options are paytheory.ONLY_CARD, paytheory.ONLY_ACH, paytheory.ONLY_CASH, paytheory.NOT_CARD, paytheory.NOT_ACH, paytheory.NOT_CASH, and paytheory.ALL.
payorId	string	The Pay Theory id for the payor that will be used for the payment. If this is not passed in, a new payor will be created.
metadata	JSON	The metadata that will be passed into the transaction.
recurring ID	string	The Pay Theory recurring ID to use for the payment. Allows for users to assign a payment to a recurring payment. If you pass in a recurring ID, the transaction amount must be an interval of the recurring payments amount per payment.

---

4. Create the Button

Using the button function, you can make the button. Send the style object, the checkout details, and the action-handling routines. To manage the button's actions, you can write functions. Among them are onReady, onClick, onSuccess, onError, and onCancel.

javascript

const handlePayment = () => {
  // Function that will be called when a payment is successful
  const ON_SUCCESS = (response) => {
    console.log("Payment Successful");
    console.log(response);
  };
// Create the button
paytheory.button({
    apiKey: "PT_API_KEY",
    checkoutDetails: CHECKOUT_DETAILS,
    style: STYLE_OBJECT,
    onReady: ON_READY,
    onClick: ON_CLICK,
    onSuccess: ON_SUCCESS,
    onError: ON_ERROR,
    onCancel: ON_CANCEL
});
};

These are the parameters that you can pass into the button function to customize the payment session. You pass a single object into the function with the following keys.

Required parameters

Key	type	description
apiKey	string	The API key for your Pay Theory account. You can find this in your Pay Theory Portal.
checkoutDetails	object	The details for the checkout page that opens when the button is clicked. Details are mentioned above.

Optional parameters

Key	type	description
onReady	function	A function that will be called when the button is ready to be clicked.
onClick	function	A function that will be called when the button is clicked.
onError	function	A function that will be called when an error occurs. It is passed an error string.
onCancel	function	A function that will be called when the user cancels the payment from the pop-up window.
onSuccess	function	A function that will be called when the payment is successful. It is passed an object with the following values. last_four (String): The last four digits of the card number or account number. amount (Int): The amount of the transaction (service fee is included). service_fee (Int): The service fee of the transaction. receipt_number (String): The unique transaction_id assigned to a transaction by Pay Theory. brand (String): The brand of the card. created_at (String): The date and time the transaction was created. state (String): The status of the transaction. metadata (JSON): The metadata of the transaction. payor_id (String): The Pay Theory id for the payor that was used for the transaction. payment_method_id (String): The Pay Theory id for the payment method token.
onBarcode	function	A function that will be called when a barcode is successfully created and the user closes the window. It is passed an object with the following values. barcodeUrl (String): The url for the barcode image. mapUrl (String): The url for the map to find retail locations to pay the barcode.

Setting up a button for multiple payments

The button session will only enable a single payment. If you want to enable multiple payments, you will need to clear the button from the DOM and create a new button.