Payment Gateway Developer Documentation
Form
Form
Building a Website Integration with Source Allies' Payment Gateway - Form
Related Pages:
- [Payment Gateway Developer Documentation Overview](/payment-gateway/developer)
- [Credit Card and eCheck Transactions](/payment-gateway/developer/cc-and-echeck)
- [Recurring Payments](/payment-gateway/developer/cc-and-echeck)
- [Google Pay Transactions](/payment-gateway/developer/google-pay)
- [Apple Pay Transactions](/payment-gateway/developer/apple-pay)
- \@sourceallies/payment-gateway
- NPM package
- Developer Documentation
### Using the Payment Gateway Form on Your Website
#### Introduction
These directions include how to add Payment Gateway to your website from beginning to end using our Payment Gateway Form. These steps will walk you through including the necessary JavaScript scripts and added `sa-pg-form` to your website.
Before you can run payments through Payment Gateway, you must have an Authorize.Net account and a Partner account for Payment Gateway.
> Payments cannot be ran from your local machine. They must be deployed to your site that has the domain in your Payment Gateway Partner account. E.g. if you want to run payments in the Payment Gateway `DEV` environment, you must have the form on your website that is in your Payment Gateway Partner account for https://gateway.dev.sourceallies.com/
To get started adding Payment Gateway to your site, you will need to create a HTML file with the following contents:
```html
<html>
<head>
</head>
<body>
</body>
</html>
```
#### Getting Started
You will also need to include our @sourceallies/payment-gateway-form NPM package for this tutorial. The developer documentation for @sourceallies/payment-gateway-form can be found here. Add the following script tag to your payment page:
```html
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
```
You will want to replace `@latest` in the URL with the current version which can be found on the NPM repository here or in the badge below (i.e. If the badge shows 0.3.2 in the green part, replace `@latest` with `@0.3.2`). Including this package allows you to access all of the functions for interfacing with Payment Gateway.
[](https://badge.fury.io/js/%40sourceallies%2Fpayment-gateway-form)
You HTML file should now look like this:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
</body>
</html>
```
#### Implementation
To add the Payment Gateway Form to your website, we will need a few properties that will link the form to your Payment Gateway account. These properties include your partner name, gateway name, and API login ID from Authorize.NET. Once we have those, we can add the Payment Gateway Form to your website by adding the following code snippet to your HTML file:
```html
<sa-pg-form
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
></sa-pg-form>
```
The environment attribute sets what environment of Payment Gateway to send requests to. This can be set to `DEV` or `PROD`. If you set it to `DEV`, you must use your Authorize.Net sandbox account credentials. `DEV` will not charge cards but simulates running real payments.
Now that we have the attributes set to link `sa-pg-form` to your Payment Gateway account, we can add other attributes to enable more features. To enable credit card and eCheck transactions, we have to add the attributes `credit-card` and `e-check` respectively to `sa-pg-form`. To enable one time and recurring transactions, we have to add the attributes `one-time` and `recurring` respectively to `sa-pg-form`. Your HTML file will now look like this:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
></sa-pg-form>
</body>
</html>
```
> If you do not want to include on of the options we added, you can exclude them from your HTML file.
The final step to finish implementing the Payment Gateway Form on your website is to add result handling when a payment is finished and to point the form to the production environment. To use the result handling provided by the Payment Gateway Form, add the `handle-result` attribute to `sa-pg-form`. To point `sa-pg-form` to the production environment, set the attribute `environment` to `"PROD"`. Your HTML file will now look like this:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
handle-result
></sa-pg-form>
</body>
</html>
```
If you would like to enable custom result handling, refer to the advanced usage section.
The Payment Gateway Form will now be ready to use on your website! To customize the form more, a description of attribute combinations can be found at the bottom of this page, or you can refer to the developer documentation.
### Advanced Usage
#### Styling the Form
Since `sa-pg-form` is a web component, you can style it how your normally would with css. There are a couple attributes you can set to style the form without having to write css.
`button-color` and `button-text-color` will color the buttons with the value you pass into it. Here is an example for red buttons with white text:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
handle-result
button-color="#D10041"
button-text-color="#fff"
></sa-pg-form>
</body>
</html>
```
Another attribute that change the styling of the form is `keyword`. This attribute replaces all occurrences of `payment` with the word you set it to. Here is an example with the keyword 'Contribution':
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
handle-result
keyword="contribution"
></sa-pg-form>
</body>
</html>
```
#### Adding Google Pay
To add Google Pay, you need to obtain the following properties from your Google Pay account: Google merchant id, Google merchant name, and gateway merchant name. Once you have those, you can add the following attributes to your HTML page:
```html
gateway-merchant-name="YOUR GATEWAY MERCHANT NAME"
google-merchant-name="YOUR GOOGLE MERCHANT NAME"
google-merchant-id="YOUR GOOGLE MERCHANT ID"
google-pay
```
After adding those to `sa-pg-form`, your code will be similar to the following:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
handle-result
gateway-merchant-name="YOUR GATEWAY MERCHANT NAME"
google-merchant-name="YOUR GOOGLE MERCHANT NAME"
google-merchant-id="YOUR GOOGLE MERCHANT ID"
google-pay
></sa-pg-form>
</body>
</html>
```
#### Adding Apple Pay
To add Apple Pay, you need to obtain the following properties from your Google Pay account: Apple merchant name and client canonical name. Once you have those, you can add the following attributes to your HTML page:
```html
client-canonical-name="YOUR CLIENT CANONICAL NAME"
apple-merchant-name="YOUR APPLE MERCHANT NAME"
apple-pay
```
After adding those to `sa-pg-form`, your code will be similar to the following:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
handle-result
client-canonical-name="YOUR CLIENT CANONICAL NAME"
apple-merchant-name="YOUR APPLE MERCHANT NAME"
apple-pay
></sa-pg-form>
</body>
</html>
```
#### Custom Result Handling
Whenever a transaction is complete, `sa-pg-form` emits an event called `pgPaymentComplete`. To handle the result you must add an event listener to `sa-pg-form` that listens to this event. An example of how to redirect to a new page when a transaction is successful can be seen below. For this example, `id="sa-pg-form"` has been added to the `sa-pg-form` element. This example will not work without this `id`:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
id="sa-pg-form"
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
handle-result
></sa-pg-form>
</body>
<script>
const saPgForm = document.getElementById('sa-pg-form');
saPgForm.addEventListener('pgPaymentComplete', (event) => {
if (event.detail.status === 'TRANSACTION_SUCCESS' || event.detail.status === 'SUBSCRIPTION_SUCCESS') {
window.location.replace('YOUR SUCCESS PAGE URL'); // This url must be the absolute url. E.g. https://sourceallies.com/payment-gateway.
// If you wan to route to a relative url, uncomment the following line and delete the line above
// window.location.href = 'relative-url'
}
});
</script>
</html>
```
> If you would like to handle failures also, you can remove the `handle-result` attribute from the `sa-pg-form` component. __We highly recommend using the built in handling for failures__.
The `event` parameter may consist of different properties based on the payment result. `event.detail` will contain all the information about the transaction. `event.detail.status` will always be defined. The following are all the possible values for `event.detail.status`:
- `TRANSACTION_SUCCESS`
- `TRANSACTION_FAILURE`
- `SUBSCRIPTION_SUCCESS`
- `SUBSCRIPTION_FAILURE`
- `MERCHANT_DETAILS_FAILURE`
- `SECURE_DATA_FAILURE`
- `NO_ACCEPTJS`
- `ACCEPTJS_FAILURE`
- `GOOGLE_PAY_FAILURE`
- `APPLE_PAY_FAILURE`
If `TRANSACTION_SUCCESS`, `TRANSACTION_FAILURE`, `SUBSCRIPTION_SUCCESS`, or `SUBSCRIPTION_FAILURE` is returned, `event.detail.xmlHttpRequest` will be defined. This will have a property `response` that is the response received from sending the request from Payment Gateway. This response can be turned into a JavaScript object by doing the following:
```javascript
const response = JSON.parse(event.detail.xmlHttpResponse.response);
```
The `response` variable will look like the following if it is `TRANSACTION_SUCCESS`:
```json
{
"refId": null,
"messages": {
"resultCode": "OK",
"message": [
{
"code": "I00001",
"text": "Successful."
}
]
},
"sessionToken": null,
"transactionResponse": {
"responseCode": "1",
"rawResponseCode": null,
"authCode": "SL47NA",
"avsResultCode": "Y",
"cvvResultCode": "P",
"cavvResultCode": "2",
"transId": "40047844022",
"refTransID": "",
"transHash": "",
"testRequest": "0",
"accountNumber": "XXXX1111",
"entryMode": null,
"accountType": "Visa",
"splitTenderId": null,
"prePaidCard": null,
"messages": {
"message": [
{
"code": "1",
"description": "This transaction has been approved."
}
]
},
"errors": null,
"splitTenderPayments": null,
"userFields": null,
"shipTo": null,
"secureAcceptance": null,
"emvResponse": null,
"transHashSha2": "",
"profile": null,
"networkTransId": "ERQL94OI6JZQRNCF7Q18U1P"
},
"profileResponse": null
}
```
The `response` variable will look like the following if it is `TRANSACTION_FAILURE`:
```json
{
"refId": null,
"messages": {
"resultCode": "OK",
"message": [
{
"code": "I00001",
"text": "Successful."
}
]
},
"sessionToken": null,
"transactionResponse": {
"responseCode": "2",
"rawResponseCode": null,
"authCode": "",
"avsResultCode": "Y",
"cvvResultCode": "P",
"cavvResultCode": "2",
"transId": "40047885239",
"refTransID": "",
"transHash": "",
"testRequest": "0",
"accountNumber": "XXXX1111",
"entryMode": null,
"accountType": "Visa",
"splitTenderId": null,
"prePaidCard": null,
"messages": null,
"errors": {
"error": [
{
"errorCode": "2",
"errorText": "This transaction has been declined."
}
]
},
"splitTenderPayments": null,
"userFields": null,
"shipTo": null,
"secureAcceptance": null,
"emvResponse": null,
"transHashSha2": "",
"profile": null,
"networkTransId": "0BKWE0WSLF0N2WH79JZUYKL"
},
"profileResponse": null
}
```
Notice that in both cases, the result is located in the `transactionResponse` object (in a `messages` object for success, and in an `errors` object for failure). There is also a `messages` object in the parent object. This message block will indicate if there is something wrong with the submitted transaction request.
The `response` variable will look like the following if it is `SUBSCRIPTION_SUCCESS`:
```json
{
"refId": null,
"messages": {
"resultCode": "OK",
"message": [
{
"code": "I00001",
"text": "Successful."
}
]
},
"sessionToken": null,
"subscriptionId": "6884096",
"profile": {
"customerProfileId": "1512459546",
"customerPaymentProfileId": "1512539187",
"customerAddressId": null
}
}
```
The `response` variable will look like this for `SUBSCRIPTION_FAILURE`:
```json
{
"refId": null,
"messages": {
"resultCode": "ERROR",
"message":[
{
"code": "E00013",
"text": "Bank Routing Number is invalid."
}
]
},
"sessionToken": null,
"subscriptionId": null,
"profile": null
}
```
Error codes in the `message` array starting with SAI are from Source Allies. All other error codes are from Authorize.Net. For help with their response codes, see Authorize.Net's Response Codes page. `transactionResponse` is the response from Authorize.Net. More information for what might be in this object can be found here for one time payments and here for subscriptions.
If `MERCHANT_DETAILS_FAILURE` or `SECURE_DATA_FAILURE` happen, this means there was an error retrieving your merchant information from Payment Gateway. This is usually caused by setting the wrong values for the `gateway-name` or `partner-name` attributes.
If `NO_ACCEPTJS` or `ACCEPTJS_FAILURE` happen, this means there was an error trying to encrypt the payment data prior to sending it to Payment Gateway. If `NO_ACCEPTJS` occurs consistently, there is likely something blocking `sa-pg-form` from adding the scripts to the window. `ACCEPTJS_FAILURE` will occur if the `api-login-id` is set to the wrong value.
`GOOGLE_PAY_FAILURE` and `APPLE_PAY_FAILURE` happen if the attributes that provide the credentials (can be found above) for these payment methods are invalid. These errors could also occur if there is an error causing Google Pay or Apple Pay to get setup incorrectly. This is caused by something blocking these scripts from being loaded and executed.
The following is a more in depth code snippet that shows how to get the transaction id or subscription id from a successful payment:
```html
<html>
<head>
<script
type="module"
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.esm.js">
</script>
<script
nomodule
src="https://unpkg.com/@sourceallies/payment-gateway-form@latest/dist/payment-gateway-form/payment-gateway-form.js">
</script>
</head>
<body>
<sa-pg-form
id="sa-pg-form"
environment="PROD"
partner-name="YOUR PARTNER NAME"
gateway-name="YOUR GATEWAY NAME"
api-login-id="YOUR API LOGIN ID"
credit-card
e-check
one-time
recurring
handle-result
></sa-pg-form>
</body>
<script>
const saPgForm = document.getElementById('sa-pg-form');
saPgForm.addEventListener('pgPaymentComplete', (event) => {
if (event.detail.status === 'TRANSACTION_SUCCESS') {
const response = JSON.parse(event.detail.xmlHttpRequest.response);
const transactionId = response.transactionResponse.transId;
// ... code for a successful transaction ...
} else if (event.detail.status === 'SUBSCRIPTION_SUCCESS') {
const response = JSON.parse(event.detail.xmlHttpRequest.response);
const subscriptionId = response.subscriptionId;
// ... code for a successful subscription ...
}
});
</script>
</html>
```
### Detailed Information on sa-pg-form
#### 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` |
| `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` | `'#1a80c7'` |
| `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` | `'#fff'` |
| `card` | `card` | Enables credit and debit 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` |
| `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` |
| `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` |
| `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` |
| `recurring` | `recurring` | Enables recurring transactions. | `boolean` | `undefined` |
#### Events
| Event | Description | Type |
| ------------------- | ---------------------------------------------- | ---------------------------- |
| `pgPaymentComplete` | Emits an event on the completion of a payment. | `CustomEvent` |