npm package: @sourceallies/payment-gateway-form
Description: Form web component for integrating Source Allies Payment Gateway with your website.
Latest version: 0.10.3


- [@sourceallies/payment-gateway-form](#sourcealliespayment-gateway-form)
- [Introduction](#introduction)
- [sa-pg-form](#sa-pg-form)
  - [Properties](#properties)
  - [Attribute Combinations](#attribute-combinations)
    - [Required Attributes](#required-attributes)
    - [Payment Options](#payment-options)
    - [Payment Frequencies](#payment-frequencies)
    - [Payment Designation](#payment-designation)
    - [Events](#events)

# @sourceallies/payment-gateway-form

# Introduction

[![npm version](https://badge.fury.io/js/%40sourceallies%2Fpayment-gateway-form.svg)](https://badge.fury.io/js/%40sourceallies%2Fpayment-gateway)

Web component for adding the [Source Allies Payment Gateway](https://www.sourceallies.com/payment-gateway) form to your website. The developer documentation for this package [can be found here](https://sourceallies.github.io/payment-gateway-docs/@sourceallies/payment-gateway-form/latest/index.html). A tutorial of how to integrate Payment Gateway with your website [can be found here](https://www.sourceallies.com/payment-gateway/developer).

<!-- Do not remove the following line -->
# sa-pg-form



<!-- Auto Generated Below -->


## Properties

| Property                   | Attribute               | Description                                                                                                                                                                                                                                                                                                                                                            | Type                                                                           | Default     |
| -------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------- |
| `amountOptions`            | `amount-options`        | Specifies what values to display in default buttons. If empty, buttons will not render. Separate values with pipes. Example: '10\|25\|50\|100\|250'                                                                                                                                                                                                                    | `string`                                                                       | `undefined` |
| `amountPlaceholder`        | `amount-placeholder`    | The placeholder for the amount input.                                                                                                                                                                                                                                                                                                                                  | `string \| undefined`                                                          | `undefined` |
| `apiLoginId` _(required)_  | `api-login-id`          | Your login for Authorize.Net.                                                                                                                                                                                                                                                                                                                                          | `string`                                                                       | `undefined` |
| `appleMerchantName`        | `apple-merchant-name`   | Your Apple merchant name to be used for Apple Pay.                                                                                                                                                                                                                                                                                                                     | `string`                                                                       | `undefined` |
| `applePay`                 | `apple-pay`             | Enables Apple Pay.                                                                                                                                                                                                                                                                                                                                                     | `boolean`                                                                      | `undefined` |
| `buttonColor`              | `button-color`          | Specifies the background of the buttons. This can be a HEX value, RGB value, RGBA value, HSL value, HSLA value, or the color in all lowercase. This color does not set the color for the payment amount buttons.                                                                                                                                                       | `string`                                                                       | `'#fff'`    |
| `buttonTextColor`          | `button-text-color`     | Specifies the text color of the buttons. This can be a HEX value, RGB value, RGBA value, HSL value, HSLA value, or the color in all lowercase. This color does not set the color for the payment amount buttons.                                                                                                                                                       | `string`                                                                       | `'#1a80c7'` |
| `card`                     | `card`                  | Enables card transactions.                                                                                                                                                                                                                                                                                                                                             | `boolean`                                                                      | `undefined` |
| `cardProviders`            | `card-providers`        | Specifies the list of card providers to support. These values are used for Google Pay, Apple Pay...  Example: 'visa\|mastercard\|discover\|amex'  Valid Values: visa, mastercard, discover, amex                                                                                                                                                                       | `string`                                                                       | `undefined` |
| `clientCanonicalName`      | `client-canonical-name` | Your Apple client canonical name to be used for Apple Pay.                                                                                                                                                                                                                                                                                                             | `string`                                                                       | `undefined` |
| `defaultConfig`            | `default-config`        | Uses a default configuration with card, e-check, handle-result, one-time, and recurring enabled.                                                                                                                                                                                                                                                                       | `boolean \| undefined`                                                         | `undefined` |
| `designations`             | `designations`          | The designations options. These values are used for the name of the line item being sent through Payment Gateway. If the line item is longer than 31 characters, it will be truncated prior to sending it to Payment Gateway. Separate designations with pipes. If only one is specified, the select will not be displayed.  Example: 'Item one\|Item two\|Item three' | `string`                                                                       | `undefined` |
| `displayCoverFees`         | `display-cover-fees`    | Specifies whether you want to display the cover fees checkbox and information. If this is displayed, the payer will be able to opt in to covering the transaction fees that are calculated using 'percent-fee'.                                                                                                                                                        | `boolean`                                                                      | `undefined` |
| `eCheck`                   | `e-check`               | Enables eCheck transactions.                                                                                                                                                                                                                                                                                                                                           | `boolean`                                                                      | `undefined` |
| `environment`              | `environment`           | The environment of Payment Gateway you want to make HTTP requests to.                                                                                                                                                                                                                                                                                                  | `Environment.DEV \| Environment.LOCAL \| Environment.PROD \| Environment.QUAL` | `undefined` |
| `forceSurcharge`           | `force-surcharge`       | Specifies a dollar amount where a surcharge will be forced. This value must be the number where you want the surcharge to start being forced. Do not include the '\

## Attribute Combinations

### Required Attributes

Always required: `api-login-id`, `merchant-name`, `gateway-name`

Required for Google Pay: `google-merchant-id`, `google-merchant-name`, `gateway-merchant-id`

Required for Apple Pay: `apple-merchant-name`, `client-canonical-name`

### Payment Options

Attributes: `card`, `e-check`, `google-pay`, and `apple-pay`

| Attribute(s)                                                    | UI                                                                      |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `card`                                                          | Does not display payment option buttons and displays credit card inputs |
| `e-check`                                                       | Does not display payment option buttons and displays e check inputs     |
| `google-pay`                                                    | Displays Google Pay button only                                         |
| `apple-pay`                                                     | Displays Apple Pay button only                                          |
| two or more of `card`, `e-check`, `apple-pay`, and `google-pay` | Displays payment option buttons                                         |

### Payment Frequencies

Attributes: `one-time` and `recurring`

| Attribute(s)               | UI                                                                              |
| -------------------------- | ------------------------------------------------------------------------------- |
| `one-time`                 | Does not display payment frequency buttons                                      |
| `recurring`                | Does not display payment frequency buttons and displays payment schedule inputs |
| `one-time` and `recurring` | Displays payment option buttons                                                 |

### Payment Designation

Attributes: `designations` and `other-designation`

| Attribute(s)                         | UI                                                                                                               |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `designations`                       | Displays payment designation select                                                                              |
| `other-designation`                  | Displays payment designation input                                                                               |
| `designations` and `other-designation` | Displays payment designation select with an `Other` option. Selecting `Other` displays payment designation input |
 symbol. This attribute should only be used if you are legally allowed to charge a surcharge.                                                                                                     | `number`                                                                       | `undefined` |
| `gatewayMerchantId`        | `gateway-merchant-id`   | Your gateway merchant ID to be used for Google Pay.                                                                                                                                                                                                                                                                                                                    | `string`                                                                       | `undefined` |
| `gatewayName` _(required)_ | `gateway-name`          | Your Payment Gateway gateway name.                                                                                                                                                                                                                                                                                                                                     | `string`                                                                       | `undefined` |
| `getInvoiceNumber`         | `get-invoice-number`    | Specifies whether you want to display the invoice number field. If this is not displayed, a random, unique invoice number will be generated for each transaction.                                                                                                                                                                                                      | `boolean`                                                                      | `undefined` |
| `googleMerchantId`         | `google-merchant-id`    | Your Google merchant ID to be used for Google Pay.                                                                                                                                                                                                                                                                                                                     | `string`                                                                       | `undefined` |
| `googleMerchantName`       | `google-merchant-name`  | Your Google merchant name to be used for Google Pay.                                                                                                                                                                                                                                                                                                                   | `string`                                                                       | `undefined` |
| `googlePay`                | `google-pay`            | Enables Google Pay.                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                                                      | `undefined` |
| `handleResult`             | `handle-result`         | Enables default result handling for transactions that is built into the form.                                                                                                                                                                                                                                                                                          | `boolean`                                                                      | `undefined` |
| `keyword`                  | `keyword`               | Specifies the keyword to use for titling the sections of the form.  Examples: payment, gift, donation, or contribution.                                                                                                                                                                                                                                                | `string`                                                                       | `'payment'` |
| `oneTime`                  | `one-time`              | Enables one time transactions.                                                                                                                                                                                                                                                                                                                                         | `boolean`                                                                      | `undefined` |
| `otherDesignation`         | `other-designation`     | Stores whether to display the other designation input.                                                                                                                                                                                                                                                                                                                 | `boolean`                                                                      | `false`     |
| `partnerName` _(required)_ | `partner-name`          | Your Payment Gateway partner name.                                                                                                                                                                                                                                                                                                                                     | `string`                                                                       | `undefined` |
| `phoneNumber`              | `phone-number`          | Adds an optional phone number field.                                                                                                                                                                                                                                                                                                                                   | `boolean \| undefined`                                                         | `undefined` |
| `preferredName`            | `preferred-name`        | Adds an optional preferred name field.                                                                                                                                                                                                                                                                                                                                 | `boolean \| undefined`                                                         | `undefined` |
| `recaptchaSiteKey`         | `recaptcha-site-key`    | Site key used for enabling reCAPTCHA v3.                                                                                                                                                                                                                                                                                                                               | `string \| undefined`                                                          | `undefined` |
| `recurring`                | `recurring`             | Enables recurring transactions.                                                                                                                                                                                                                                                                                                                                        | `boolean`                                                                      | `undefined` |
| `reportErrors`             | `report-errors`         | Specifies if errors generated by the form should be reported to Source Allies. Disabled by default.                                                                                                                                                                                                                                                                    | `boolean`                                                                      | `false`     |
| `surcharge`                | `surcharge`             | Sets percentage processing fee amount. This is used to calculate the price with fees if a 'display-cover-fees' is set to true and the user opts in to cover the processing fees or if you set the attribute `force-surcharge`. This attribute should only be used if you are legally allowed to charge a surcharge.                                                    | `number`                                                                       | `0.03`      |


## Events

| Event               | Description                                    | Type                         |
| ------------------- | ---------------------------------------------- | ---------------------------- |
| `pgPaymentComplete` | Emits an event on the completion of a payment. | `CustomEvent<PaymentResult>` |




## Attribute Combinations

### Required Attributes

Always required: `api-login-id`, `merchant-name`, `gateway-name`

Required for Google Pay: `google-merchant-id`, `google-merchant-name`, `gateway-merchant-id`

Required for Apple Pay: `apple-merchant-name`, `client-canonical-name`

### Payment Options

Attributes: `card`, `e-check`, `google-pay`, and `apple-pay`

| Attribute(s)                                                    | UI                                                                      |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `card`                                                          | Does not display payment option buttons and displays credit card inputs |
| `e-check`                                                       | Does not display payment option buttons and displays e check inputs     |
| `google-pay`                                                    | Displays Google Pay button only                                         |
| `apple-pay`                                                     | Displays Apple Pay button only                                          |
| two or more of `card`, `e-check`, `apple-pay`, and `google-pay` | Displays payment option buttons                                         |

### Payment Frequencies

Attributes: `one-time` and `recurring`

| Attribute(s)               | UI                                                                              |
| -------------------------- | ------------------------------------------------------------------------------- |
| `one-time`                 | Does not display payment frequency buttons                                      |
| `recurring`                | Does not display payment frequency buttons and displays payment schedule inputs |
| `one-time` and `recurring` | Displays payment option buttons                                                 |

### Payment Designation

Attributes: `designations` and `other-designation`

| Attribute(s)                         | UI                                                                                                               |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `designations`                       | Displays payment designation select                                                                              |
| `other-designation`                  | Displays payment designation input                                                                               |
| `designations` and `other-designation` | Displays payment designation select with an `Other` option. Selecting `Other` displays payment designation input |