xStreet	xZip	AvsResultCode	xAvsResult
xStreet	xZip	AvsResultCode	xAvsResult
111	11111	YYY	Address: Match & 5 Digit Zip: Match
999	99999	NNN	Address: No Match & 5 Digit Zip: No Match
111	111111111	YYX	Address: Match & 9 Digit Zip: Match
111	99999	YNA	Address: Match & 5 Digit Zip: No Match
999	111111111	NYW	Address: No Match & 9 Digit Zip: Match
999	11111	NYZ	Address: No Match & 5 Digit Zip: Match
888	88888	XXR	Retry / System Unavailable
777	77777	XXU	Address Information not verified for domestic transaction
666	66666	XXS	Service Not Supported

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerNumber	No	string	Merchant's internal customer identifier.
CustomerNotes	No	string	Notes pertaining to the customer.
Email	No	string	Customer's email address.
Fax	No	string	Customer's fax number.
BillFirstName	Yes*	string	Customer's first name for their billing profile. *Required if `BillLastName` and `BillCompany` are not passed in.
BillMiddleName	No	string	Customer's middle name or middle initial for their billing profile.
BillLastName	Yes*	string	Customer's last name or family name for their billing profile. *Required if `BillFirstName` and `BillCompany` are not passed in.
BillCompany	Yes*	string	Customer's company name for their billing profile. *Required if `BillFirstName` and `BillLastName` are not passed in.
BillStreet	No	string	Customer's street address for their billing profile.
BillStreet2	No	string	Customer's street address second line for their billing profile.
BillCity	No	string	Customer's city for their billing profile.
BillState	No	string	Customer's state for their billing profile.
BillZip	No	string	Customer's ZIP code or postal code for their billing profile.
BillCountry	No	string	Customer's country for their billing profile.
BillPhone	No	string	Customer's phone number for their billing profile.
BillMobile	No	string	Customer's mobile number for their billing profile.
ShipFirstName	No	string	Customer’s first name for their shipping profile.
ShipMiddleName	No	string	Customer’s middle name or initial for their shipping profile.
ShipLastName	No	string	Customer’s last/family name for their shipping profile.
ShipCompany	No	string	Customer’s company name for their shipping profile.
ShipStreet	No	string	Customer’s street address for their shipping profile.
ShipStreet2	No	string	Customer’s street address second line for their shipping profile.
ShipCity	No	string	Customer’s city for their shipping profile.
ShipState	No	string	Customer’s state for their shipping profile.
ShipZip	No	string	Customer’s ZIP code for their shipping profile.
ShipCountry	No	string	Customer’s country for their shipping profile.
ShipPhone	No	string	Customer’s phone number for their shipping profile.
ShipMobile	No	string	Customer’s mobile number for their shipping profile.
ShipEmail	No	string	Customer’s shipping email address for their shipping profile.
CustomerCustomXX	No	string	Custom fields (20 available) used for custom data such as customer comments and so forth. Use `CustomerCustom01` through `CustomerCustom20`.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
CustomerId	integer	The created customer ID.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
Revision	Yes	integer	The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.
CustomerId	Yes	string	The ID of the customer to update.
CustomerNumber	No	string	Merchant's internal customer identifier.
CustomerNotes	No	string	Notes pertaining to the customer.
DefaultPaymentMethodId	Yes	string	The ID of the created payment method.
Email	No	string	Customer's email address.
Fax	No	string	Customer's fax number.
BillFirstName	Yes*	string	Customer's first name for their billing profile. *Required if `BillLastName` and `BillCompany` are not passed in.
BillMiddleName	No	string	Customer's middle name or middle initial for their billing profile.
BillLastName	Yes*	string	Customer's last/family name for their billing profile. *Required if `BillFirstName` and `BillCompany` are not passed in.
BillCompany	Yes*	string	Customer's company name for their billing profile. *Required if `BillFirstName` and `BillLastName` are not passed in.
BillStreet	No	string	Customer's street address for their billing profile.
BillStreet2	No	string	Customer's street address second line for their billing profile.
BillCity	No	string	Customer's city for their billing profile.
BillState	No	string	Customer's state for their billing profile.
BillZip	No	string	Customer's ZIP code or postal code for their billing profile.
BillCountry	No	string	Customer's country for their billing profile.
BillPhone	No	string	Customer's phone number for their billing profile.
BillMobile	No	string	Customer's mobile number for their billing profile.
ShipFirstName	No	string	Customer’s first name for their shipping profile.
ShipMiddleName	No	string	Customer’s middle name or initial for their shipping profile.
ShipLastName	No	string	Customer’s last/family name for their shipping profile.
ShipCompany	No	string	Customer’s company name for their shipping profile.
ShipStreet	No	string	Customer’s street address for their shipping profile.
ShipStreet2	No	string	Customer’s street address second line for their shipping profile.
ShipCity	No	string	Customer’s city for their shipping profile.
ShipState	No	string	Customer’s state for their shipping profile.
ShipZip	No	string	Customer’s ZIP code for their shipping profile.
ShipCountry	No	string	Customer’s country for their shipping profile.
ShipPhone	No	string	Customer’s phone number for their shipping profile.
ShipMobile	No	string	Customer’s mobile number for their shipping profile.
ShipEmail	No	string	Customer’s shipping email address for their shipping profile.
CustomerCustomXX	No	string	Custom fields (20 available) used for custom data such as customer comments and so forth. Use `CustomerCustom01` through `CustomerCustom20`.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerId	Yes	string	The ID of the customer to retrieve.
ShowDeleted	No	boolean	A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e. customers that are not deleted will not be returned).

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
Revision	integer	The revision number of the customer record.
CreatedDate	string	The date and time the customer was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).
CustomerId	string	The ID of the customer to update.
CustomerNumber	string	Merchant's internal customer identifier.
CustomerNotes	string	Notes pertaining to the customer.
Email	string	Customer's email address.
Fax	string	Customer's fax number.
BillFirstName	string	Customer's first name for their billing profile.
BillMiddleName	string	Customer's middle name or initial for their billing profile.
BillLastName	string	Customer's last/family name for their billing profile.
BillCompany	string	Customer's company name for their billing profile.
BillStreet	string	Customer's street address for their billing profile.
BillStreet2	string	Customer's street address second line for their billing profile.
BillCity	string	Customer's city for their billing profile.
BillState	string	Customer's state for their billing profile.
BillZip	string	Customer's ZIP code or postal code for their billing profile.
BillCountry	string	Customer's country for their billing profile.
BillPhone	string	Customer's phone number for their billing profile.
BillMobile	string	Customer's mobile number for their billing profile.
ShipFirstName	string	Customer’s first name for their shipping profile.
ShipMiddleName	string	Customer’s middle name or initial for their shipping profile.
ShipLastName	string	Customer’s last/family name for their shipping profile.
ShipCompany	string	Customer’s company name for their shipping profile.
ShipStreet	string	Customer’s street address for their shipping profile.
ShipStreet2	string	Customer’s street address second line for their shipping profile.
ShipCity	string	Customer’s city for their shipping profile.
ShipState	string	Customer’s state for their shipping profile.
ShipZip	string	Customer’s ZIP code for their shipping profile.
ShipCountry	string	Customer’s country for their shipping profile.
ShipPhone	string	Customer’s phone number for their shipping profile.
ShipMobile	string	Customer’s mobile number for their shipping profile.
ShipEmail	string	Customer’s shipping email address for their shipping profile.
CustomerCustomXX	string	Custom fields (20 available) used for custom data such as customer comments and so forth. Use `CustomerCustom01` through `CustomerCustom20`.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerId	Yes	string	The ID of the customer to update.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Default Value	Description	Valid Values
Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
PageSize	No	integer	100	The maximum number of items to retrieve for this request.
NextToken	No	string		A token that can be sent in to the following request to get the next set of customers.
SortOrder	No	string	Ascending	The list order. Order is determined by customer creation date.	Ascending, Descending
Filters	No	object	{ "IsDeleted" : false }	Filters that can be applied to limit the result set. Filters will remove any items that do not contain the string for that filter value. If there are multiple filters applied, the item must match all of them. Available filters: CustomerId CustomerNumber IsDeleted Email BillName BillFirstName BillLastName BillMiddleName BillCompany BillStreet BillStreet2 BillCity BillState BillZip BillCountry BillPhoneNumber BillPhone BillMobile BillFax

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
Customers	object[]	An array of customer objects. Refer to the /GetCustomer endpoint for the values that are returned for each customer.
NextToken	string	A token to include in the next request to get the next set of results.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerId	Yes	string	The ID of the customer to update with the new payment method.
Token	Yes	string	Sola token that represents a payment method. *Raw card information cannot be passed in the request.
TokenType	Yes	string	The `Token` payment type.
TokenAlias	No	string	Custom name for the `Token`.
Exp	Yes*	string	Credit card expiration date. *Required if `Token` is an iFields token and `TokenType` is cc.
Routing	Yes*	string	ACH payment routing number. Required if `Token` is an iFields token and `TokenType` is ach*.
AccountType	No	string	The account type - checking / savings. Allowed if the `TokenType` is check*.
Name	No	string	Name on the customer's account. *Required for ACH (check) transactions.
Street	No	string	Customer's street address for their billing profile.
Zip	No	string	Customer's ZIP code or postal code for their billing profile.
SetAsDefault	No	boolean	Sets this payment method as the default payment method. Note: If there are no other payment methods, this method is automatically set as the default.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
PaymentMethodId	string	The ID of the created payment method.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
Revision	Yes	integer	The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.
PaymentMethodId	Yes	string	The ID of the payment method to update.
TokenAlias	No	string	Custom name for the `Token`.
Exp	No	string	Credit card expiration date.
AccountType	No	string	The account type - checking / savings Allowed if `TokenType` is check*.
Routing	Yes*	string	ACH payment routing number. Required if `Token` is an iFields token and `TokenType` is ach*.
Name	No*	string	Name on the customer's account. *Required for ACH (check) transactions.
Street	No	string	Customer's street address for their billing profile.
Zip	No	string	Customer's ZIP code or postal code for their billing profile.
SetAsDefault	No	boolean	Sets this payment method as the default payment method. Note: If there are no other payment methods, this method is automatically set as the default.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents an error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
PaymentMethodId	Yes	string	The ID of the payment method to retrieve.
ShowDeleted	No	boolean	A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e., payment methods that are not deleted will not be returned).

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
PaymentMethodId	string	The ID of the payment method.
Revision	number	The revision number of the record to update. If this does not match the current revision number of the record the update will fail.
Token	string	Sola token that references a previously used payment method to use for the charge.
TokenType	string	The `Token` payment type.	CC, Check
TokenAlias	string	Custom name for the `Token`.
Exp	string	Credit card expiration date (in `MMYY` format).
AccountType	string	The account type - checking / savings Note: This field is only populated when `TokenType` is Check.
Issuer	string	The credit card issuer. Note: This field is only populated when `TokenType` is CC.
MaskedCardNumber	string	The masked credit card number. Note: This field is only populated when `TokenType` is CC.
Name	string	The name on the check. Note: This field is only populated when `TokenType` is Check.
Street	string	The building number and street name of the customer being billed.
Zip	string	The zip code of the customer being billed.
CreatedDate	string	The date and time the payment method was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
PaymentMethodId	Yes	string	The ID of the payment method to retrieve.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Default Value	Description	Valid Values
Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
PageSize	No	integer	100	The maximum number of items to retrieve for this request.
NextToken	No	string		A token that can be sent in to the following request to get the next set of payment methods.
SortOrder	No	string	Ascending	The list order. Order is determined by payment method creation date.	Ascending, Descending
Filters	No	object	{ "IsDeleted" : false }	Filters that can be applied to limit the result set. Filters will remove any items that do not contain the string for that filter value. If there are multiple filters applied, the item must match all of them. Available filters: IsDeleted CustomerId PaymentMethodId Token TokenType TokenAlias

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
PaymentMethods	object[]	An array of payment method objects. Refer to the /GetPaymentMethod endpoint for the values that are returned for each payment method.
NextToken	string	A token to include in the next request to get the next set of results.

Parameter	Required	Type	Default Value	Description	Valid Values
Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
CustomerId	Yes*	string		Customer's unique ID number. *Required if linking the schedule to an existing customer.
PaymentMethodId	No	string		The unique ID number of the payment method the schedule should use to process the transactions. If none is set, the default payment method on the customer will be used. *Allowed if linking the schedule to an existing customer
NewCustomer	Yes*	object		The customer details. Refer to the /CreateCustomer endpoint for fields that can be set for this object. Required if not* linking the schedule to an existing customer. This cannot be set if linking to an existing customer.
NewPaymentMethod	Yes*	object		The payment method details. Refer to the /CreatePaymentMethod endpoint for fields that can be set for this object. Required if not* linking the schedule to an existing customer. This cannot be set if linking to an existing customer.
IntervalType	Yes	string		Type of time interval.	day, week, month, year
Amount	Yes	decimal		Total amount of each transaction.	Must be a number with up to 2 decimal places
Currency	No	string		Currency code to be used when processing transactions Note: If the currency code used is not supported for the merchant and it does not run a transaction on schedule creation, the schedule will not error until the first transaction is processed.
TotalPayments	No	integer	infinite	Total count of scheduled payment occurrences, including the initial payment. Note: If left blank, the count is indefinite. This field cannot be set together with `EndDate`.
Cvv	No	string		The CVV value for the first transaction that is run if a transaction is run immediately. This value will not be applied to a future transaction run by the created schedule.
Description	No	string		Additional data sent with the transaction.
Invoice	No	string		Customer's invoice number for the transaction. Use `Invoice` when available for improved duplicate handling (recommended).
PONumber	No	string		Customer's purchase order number for the transaction.
ScheduleName	No	string		Merchant's internal schedule identifier.
IntervalCount	No	integer	1	Number of time periods to elapse before the payment schedule is re-triggered. Examples: For every 28 days, set `IntervalType` to day and set `IntervalCount` to 28. For every other month, set `IntervalType` to month and set `IntervalCount` to 2.
FailedTransactionRetryTimes	No	integer	5	Maximum number of times to retry before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day. If it’s set to 0, it will try one time total.
DaysBetweenRetriesnew	No	integer	1	Number of days between retries after a declined transaction.	Any natural number greater than 0.
SkipSaturdayAndHolidays	No	boolean	false	Indicates whether to process payments on the Sabbath and Jewish holidays.
CustReceipt	No	boolean	false	A flag that can be set to send the receipts to the email set in `Email` for the customer.
CalendarCulture	No	string	Gregorian	Type of calendar to use when executing month and year interval types.	Gregorian, Hebrew
UseDefaultPaymentMethodOnly	No	boolean	false	Indicates that the system should not try another card if the default card fails.
ScheduleRule	No	object		The schedule rule used to determine the next run time after each processed payment. See Appendix A for more information on the `ScheduleRule` object.
StartDate	No	string	current date	Schedule start date in YYYY-MM-DD format. The start date must be within one year. Unless the `StartDate` parameter is included to specify a future start date for the schedule, the first charge takes place immediately by default.
EndDate	No	string		Schedule expiration date in YYYY-MM-DD format. Note: This field cannot be set together with `TotalPayments`.
AfterMaxRetriesAction	No	string	ContinueNextInterval	The action to perform after a schedule hits the maximum number of failed attempts in a single interval. Disable: Disables the schedule. ContinueNextInterval: Skips the current interval and continues at the next interval.	Disable, ContinueNextInterval
AllowInitialTransactionToDecline	No	Boolean	False	Create the schedule even if the initial payment fails. Note: Can be used only if the `StartDate` is set to today's date (or left empty).
SplitInstruction	No	Object	False	On Instructional Funding accounts, add split instructions for each scheduled transaction. Format is an array of json objects, each having a mid and the amount for that mid.
CustomXX	No	String		Custom fields (19 available) used for custom data, such as customer comments and so forth. `Custom01` is reserved. Use `Custom02` - `Custom20`.
InitialAmount	No	String or Integer		Overrides Amount on initial transaction	5.99

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
ScheduleId	string	The ID of the schedule that was created.
CustomerId	string	The ID of the customer that was created if the schedule was not linked to an existing customer.
PaymentMethodId	string	The ID of the payment method that was created if the schedule was not linked to an existing customer.

Parameter	Required	Type	Default Value	Description	Valid Values
Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
Revision	Yes	integer		The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.
ScheduleId	Yes	string		The ID of the schedule to update.
Amount	No	decimal		Transaction amount
Currency	No	string		Currency code to be used when processing transactions. Note: If the currency code used is not supported for the merchant and it does not run a transaction on schedule creation, the schedule will not error until the first transaction is processed.
TotalPayments	No	integer	infinite	Total count of scheduled payment occurrences, including the initial payment. You can only change this field before a schedule has been completed. Additionally, you cannot set the value to be lower than the number of payments already processed. Note: This can be updated to at least the number of payments processed or higher.
Description	No	string		Additional data sent with the transaction.
Invoice	No	string		Customer's invoice number for the transaction Use `Invoice` when available for improved duplicate handling (recommended).
PONumber	No	string		Customer's purchase order number for the transaction.
ScheduleName	No	string		Merchant's internal schedule identifier.
FailedTransactionRetryTimes	No	integer	5	Maximum number of times to retry before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day. If it’s set to 0, it will try one time. You can only change this field before a schedule has been completed.
DaysBetweenRetries	No	integer		Number of days between retries after a declined transaction.	Any natural number greater than 0
SkipSaturdayAndHolidays	No	boolean	false	Indicates whether to process payments on the Sabbath and Jewish holidays.
CustReceipt	No	boolean	false	A flag that can be set to send the receipts to the email set in `Email` for the customer.
CalendarCulture	Yes	string	Gregorian	Type of calendar to use when executing month and year interval types. Note: You cannot change this once the schedule has begun.	Gregorian, Hebrew
UseDefaultPaymentMethodOnly	No	boolean	false	Indicates that the system should not try another card if the default card fails.
PaymentMethodId	No	string		The unique ID of the payment method the schedule should use to process the transactions
ScheduleRule	No	object		The schedule rule used to determine the next run time after each processed payment. See Appendix A for more information on the `ScheduleRule` object.
StartDate	Yes	string		Schedule start date in YYYY-MM-DD format. The start date must be within one year. Note: This cannot be changed once the schedule has begun.
EndDate	No	string		Schedule expiration date in YYYY-MM-DD format. Note: This field cannot be set together with `TotalPayments`. This cannot be changed once the schedule has completed.
AfterMaxRetriesAction	No	String	ContinueNextInterval	The action to perform after a schedule hits the maximum number of failed attempts in a single interval. Disable: Disables the schedule. ContinueNextInterval: Skips the current interval and continues at the next interval.	Disable, ContinueNextInterval
SplitInstruction	No	Object		On Instructional Funding accounts, update the split instructions for each scheduled transaction. Format is an array of json objects, each having a mid and the amount for that mid.
CustomXX	No	String		Custom fields (19 available) used for custom data, such as customer comments and so forth. `Custom01` is reserved. Use `Custom02` - `Custom20`.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
ScheduleId	Yes	string	The ID of the schedule to enable.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E,this parameter will contain any relevant error messages.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
ScheduleId	Yes	string	The ID of the schedule to disable.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
ScheduleId	Yes	string	The ID of the schedule to delete.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
ScheduleId	Yes	string	The ID of the schedule to retrieve.
ShowDeleted	No	boolean	A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e., schedules that are not deleted will not be returned).

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
Revision	integer	The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.
ScheduleId	string	Schedule reference number.
ScheduleName	string	Schedule name.
CustomerId	string	Customer's unique ID number.
PaymentMethodId	string	The unique ID number of the payment method the schedule uses to process the transactions Note: Only populated when a specific PaymentMethodId was sent in on creating/updating schedule
IsDeleted	boolean	A flag indicating whether the record is deleted.
UseDefaultCardOnly	boolean	Indicates that the system should not try another card if the default card fails.
FailedTransactionRetryTimes	integer	Maximum number of times to retry before rescheduling to the next run time if the transaction fails. The tries are spaced apart into 1-day intervals.
FailedAttemptsInCurrentInterval	integer	The number of unsuccessful transactions that were processed for the current interval. This value will reset to 0 at the start of the next interval.
DaysBetweenRetries	integer	Number of days between retries after a declined transaction.
ScheduleRule	object	The schedule rule used to determine the next run time after each processed payment. See Appendix A for more information on the `ScheduleRule` object.
StartDate	string	Schedule start date in YYYY-MM-DD format.
EndDate	string	Schedule end date in YYYY-MM-DD format.
AllowInitialTransactionToDecline	boolean	Indicates whether the schedule was set up to allow the first transaction to be declined.
Description	string	Additional data sent with the transaction (optional).
Amount	decimal	Transaction amount.
Currency	string	Currency code to be used when processing transactions.
TotalPayments	integer	Total count of scheduled payment occurrences, including the initial payment.
PaymentsProcessed	integer	The number of payments processed by the schedule.
SkipSaturdayAndHolidays	boolean	Indicates whether to process payments on the Sabbath and Jewish holidays.
IntervalType	string	Type of time interval.
IntervalCount	integer	Number of time periods to elapse before the payment schedule is re-triggered. Note: Refer to the /CreateSchedule endpoint for more details.
LastTransactionStatus	string	The status of the last transaction run by the schedule.
LastTransactionError	string	The error message of the last transaction if the status was Error.
LastProjectedPaymentDate	string	The projected payment date of the last transaction that the schedule will run. Note: This may not be 100% accurate if that last date falls on a Saturday or Holiday and `SkipSaturdayAndHolidays` is set.
Invoice	string	Customer's invoice number for the transaction.
PONumber	string	Customer's purchase order number for the transaction.
CustReceipt	boolean	A flag indicating whether receipts will be sent to the email set in `Email` for the customer.
NextScheduledRunTime	string	The date and time that the schedule will next run.
InitialRunTime	string	The date and time of the first transaction run by the schedule.
LastRunTime	string	The date and time of the last transaction run by the schedule.
IsActive	boolean	A flag indicating whether the schedule is currently enabled/active.
CalendarCulture	string	Type of calendar to use when executing month and year interval types.
CreatedDate	string	Date that the schedule was created.
CustomerNumber	string	Merchant's internal customer identifier.
Email	string	Customer's email address.
BillFirstName	string	Customer's first name for their billing profile.
BillMiddleName	string	Customer's middle name or initial for their billing profile.
BillLastName	string	Customer's last/family name for their billing profile.
BillCompany	string	Customer's company for their billing profile.
AfterMaxRetriesAction	string	The action to perform after a schedule hits the maximum number of failed attempts in a single interval. Disable: Disables the schedule. ContinueNextInterval: Skips the current interval and continues at the next interval.	Disable, ContinueNextInterval
SplitInstruction	Object	On Instructional Funding accounts, the split instructions used for each scheduled transaction.
CustomXX	string	Custom fields (19 available) used for custom data, such as customer comments and so forth. `Custom01` is reserved.

Parameter	Required	Type	Default Value	Description	Valid Values
Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
ScheduleId	Yes	string		The ID of the schedule to retrieve.
NumberOfPayments	Yes	integer		The number of payment dates to retrieve.	An integer between 1 and 100 (inclusive)
CalendarCulture	No	string	Gregorian	The culture the dates should be returned in.	Gregorian, Hebrew

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents an error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
UpcomingPaymentDates	string[]	The upcoming payment dates for the specified schedule in the format yyyy-mm-dd.

Parameter	Required	Type	Default Value	Description	Valid Values
Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
PageSize	No	integer	100	The maximum number of items to retrieve for this request.
NextToken	No	string		A token that can be sent in to the following request to get the next set of schedules.
SortOrder	No	string	Ascending	The list order. Order is determined by schedule creation date.	Ascending, Descending
Filters	No	object	{ "IsDeleted" : false }	Filters that can be applied to limit the result set. Filters will remove any items that don't contain the string for that filter value. If there are multiple filters applied the item must match all of them. Available filters: IsDeleted Active Amount IntervalCount CustomerId ScheduleId BillFirstName BillMiddleName BillLastName BillName Email BillCompany CustomerNumber ScheduleName Description IntervalType StartDate PaymentsRemaining

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents an error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
Schedules	object[]	An array of schedule objects. Refer to the /GetSchedule endpoint for the values that are returned for each schedule. Note: The `ScheduleRule` field is not returned by this endpoint for each schedule.
NextToken	string	A token to include in the next request to get the next set of results.

Parameter	Required	Type	Default Value	Description
Parameter	Required	Type	Default Value	Description
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
CustomerId	Yes	string		Customer's unique ID number. *This field is required if PaymentMethodID is not passed in. Valid combinations are below: PM ID only Customer ID Only (will use default PM on file) Customer ID & new PM info
PaymentMethodId	Yes*	string		The ID of the payment method to use for the transaction. *Required if using an existing non-default payment method.
Amount	Yes	decimal		The amount of the transaction.
Tax	No	decimal		The tax portion that is included in the total transaction amount.
PaymentDetails	No*	object		The details for a new method of payment. Required if not* using an existing payment method. Note: Refer to the /CreatePaymentMethod endpoint for available and required fields.
UseBackupPaymentMethods	No	boolean	false	Indicates that the system should try another card if the default card fails.
Invoice	No	string		Customer's invoice number for the transaction. Use `Invoice` when available for improved duplicate handling (recommended).
PONumber	No	string		Customer's purchase order number for the transaction.
Description	No	string		Additional data sent with the transaction.
AllowDuplicates	No	boolean	false	A flag indicating whether to disable duplicate detection. Useful for testing, but it is not suggested that this be set to true in production.
CustReceipt	No	boolean		A flag that can be set to send the receipts to the email address set in `Email` for the customer.
Cvv	No	string		The CVV value for the transaction.
Email	No	string		Customer's email address.
Fax	No	string		Customer's fax number.
BillFirstName	Yes*	string		Customer's first name for their billing profile. *This field is required if `BillLastName` and `BillCompany` are not passed in.
BillMiddleName	No	string		Customer's middle name or initial for their billing profile.
BillLastName	Yes*	string		Customer's last/family name for their billing profile. *This field is required if `BillFirstName` and `BillCompany` are not passed in.
BillCompany	Yes*	string		Customer's company for their billing profile. *This field is required if `BillFirstName` and `BillLastName` are not passed in.
BillStreet	No	string		Customer's street address for their billing profile.
BillStreet2	No	string		Customer's street address second line for their billing profile.
BillCity	No	string		Customer's city for their billing profile.
BillState	No	string		Customer's state for their billing profile.
BillZip	No	string		Customer's ZIP code or postal code for their billing profile.
BillCountry	No	string		Customer's country for their billing profile.
BillPhone	No	string		Customer's phone number for their billing profile.
BillMobile	No	string		Customer's mobile number for their billing profile.
ShipFirstName	No	string		Customer’s first name for their shipping profile.
ShipMiddleName	No	string		Customer’s middle name or initial for their shipping profile.
ShipLastName	No	string		Customer’s last/family name for their shipping profile.
ShipCompany	No	string		Customer’s company name for their shipping profile.
ShipStreet	No	string		Customer’s street address for their shipping profile.
ShipStreet2	No	string		Customer’s street address second line for their shipping profile.
ShipCity	No	string		Customer’s city for their shipping profile.
ShipState	No	string		Customer’s state for their shipping profile.
ShipZip	No	string		Customer’s ZIP or postal code for their shipping profile.
ShipCountry	No	string		Customer’s country for their shipping profile.
ShipPhone	No	string		Customer’s phone number for their shipping profile.
ShipMobile	No	string		Customer’s mobile number for their shipping profile.
ShipEmail	No	string		Customer’s shipping email address for their shipping profile.
CustomXX	No	string		Custom fields (19 available) used for custom data, such as customer comments and so forth. `Custom01` is reserved. Use `Custom02` - `Custom20`.
Currency	No	string		Currency code for the transaction.
SplitInstruction	No	object	sale	On Instructional Funding accounts, add split instructions for the transaction. Format is an array of json objects, each having a mid and the amount for that mid.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
GatewayRefnum	string	The gateway reference number for the transaction.
GatewayStatus	string	The status of the transaction passed back by the gateway.	Approved, Declined, Error
GatewayErrorMessage	string	The error message for the transaction passed back by the gateway if the status indicates an error.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
RefNum	Yes	string	The ID of the transaction to retrieve.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
TransactionId	string	The ID of the retrieved transaction.
ScheduleId	string	The ID of the schedule that the transaction was run for.
CustomerId	string	The ID of the customer that the transaction was run for.
PaymentMethodId	string	The ID of the payment method used in the transaction.
TransactionDate	string	The date the transaction was run.
GatewayRefNum	string	The reference number generated by the gateway for the transaction.
GatewayStatus	string	The transaction processing status returned by the gateway.	Approved, Declined, Error
GatewayError	string	The error message returned by the gateway if `GatewayStatus` indicates an error.

Parameter	Required	Type	Default Value	Description	Valid Values
Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
PageSize	No	integer	100	The maximum number of items to retrieve for this request.
NextToken	No	string		A token that can be sent in to the following request to get the next set of transactions.
SortOrder	No	string	Ascending	The list order. Order is determined by the date the transaction ran.	Ascending, Descending
Filters	No	object		Filters that can be applied to limit the result set. Filters will remove any items that do not contain the string for that filter value. If there are multiple filters applied, the item must match all of them. Available filters: IsApproved FromDate ToDate CustomerId ScheduleId PaymentMethodId TransactionId

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
Transactions	object[]	An array of transaction objects. Refer to the /GetTransaction endpoint for the values that are returned for each transaction.
NextToken	string	A token to include in the next request to get the next set of results.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
Revision	Yes	integer	The current revision number of the record. If his value is incorrect the update will fail.
ScheduleReportSettings	Yes	object	The schedule report settings for the merchant: Enabled (boolean): A flag indicating if the system should send the report. EmailAddresses (array of string): One or more email addresses that will be sent the report. ShowDetails (boolean): A flag indicating if the system should send the detailed version of the report with transaction details. The system can send the detailed version sent only if there are 500 transactions or less.
MaxRetriesReachedNotification	No	object	Settings for an email notification when a schedule reaches the maximum number of retries in an interval. Enabled (boolean): A flag indicating if the system should send the email notification. EmailAddresses (array of string): One or more email addresses that will be sent the notification. Note: Values are only updated if they are not set to null. To clear the EmailAddresses, an empty array must be passed in.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.

Parameter	Required	Type	Description
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.

Parameter	Type	Description	Valid Values
Parameter	Type	Description	Valid Values
Result	char	The result of the API call. S represents success, E represents error.	S, E
RefNum	string	A unique request ID.
Error	string	If the `Result` parameter contains a value of E, this parameter will contain any relevant error messages.
Revision	integer	The current revision number of the record.
ScheduleReportSettings	object	The schedule report settings for the merchant: Enabled (boolean): A flag indicating if the system should send the report. EmailAddresses (array of string): One or more email addresses that will be sent the report. ShowDetails (boolean): A flag indicating if the system should send the detailed version of the report with transaction details. The system can send the detailed version sent only if there are 500 transactions or less.
MaxRetriesReachedNotification	object	The max retry reached notification settings for the merchant: Enabled (boolean): A flag indicating if the system should send the email notification. EmailAddresses (array of string): One or more email addresses that will be sent the notification.

Name	Type	Description	Valid Values
Name	Type	Description	Valid Values
RuleType	string	The type of rule to create.	On, Nth
DayOfWeek	integer	The day of the week to run the schedule on.	1 - 7
DayOfMonth	integer	The day of the month to run the schedule on.	1 - 31 for gregorian schedules 1 - 30 for hebrew schedules
MonthOfYear	integer	The month of the year to run the schedule on.	1 - 12 for gregorian schedules 1 - 13 for hebrew schedules
N	integer	The nth value to run the schedule on.	Any positive or negative integer other than zero
NthOfType	string	The type that the nth value should be applied to.	Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Day, Weekday, WeekendDay

Role	Capabilities
Integration	In Scope
Language	Swift
UI Toolkit	Storyboard
Transaction	cc:sale

Role	Capabilities
Integration	Out of Scope
Language	Swift
UI Toolkit	Storyboard
Transaction	cc:sale

Provides Apple Pay button customization options.
For more information please click the link.

Name of a callback function to be called when Apple Pay button is loaded.
Accepts an object of type APButtonLoadedResult
Please click here for the sample code.

Name of a callback function to be called that returns the final price and tax calculations.
Please click here for the sample code.

Name of a callback function to be called that returns a list of available Shipping Methods.
Please click here for the sample code.

Name of a callback function to be called when Shipping Contact is selected/changed.
Accepts a parameter PaymentContact.
Returns ShippingContactResponse.
If address\_validation is part of requiredFeatures in your ApplePay Request object you can return an Error as part of ShippingContactResponse.
Please click here for the sample code.

Name of a callback function to be called when Shipping Method is selected/changed.
Accepts a parameter ShippingMethod.
Please click here for the sample code.

Name of a callback function to be called when Payment Method is selected/changed.
Accepts a parameter PaymentMethod.
Please click here for the sample code.

Name of a callback function to be called when consumer clicked the button but before Apple Pay sheet is loaded. Usually used to make validations before the payment.
Please click here for the sample code.

Name of a callback function to be called to validate the Merchant.
This functions accepts a parameter validationUrl.
Please click here for the sample code.

Name of a callback function to be called when Apple Payment is authorized for the completion of the transaction.
This function accepts a parameter of PaymentResponse.
Please click here for the sample code.

Name of a callback function to be called when Apple confirms the completion of the transaction.
This function accepts a parameter of PaymentComplete.
Please click here for the sample code.

Name of a callback function to be called when Error occurs.
Please click here for the sample code.
Make sure to assign onError in initAP function like below.

Name of a callback function to be called when user cancels.
Please click here for the sample code.

From Google documentation:

default: A Google-selected default value. Currently black but it may change over time (default).
black: A black button suitable for use on white or light backgrounds.
white: A white button suitable for use on colorful backgrounds.

From Google documentation:

buy: "Buy with Google Pay" button (default).
donate: "Donate with Google Pay" button.
plain: Google Pay button without additional text.

| #### **Button Options example** ``` buttonOptions: { buttonContainer: "ap-container", buttonColor: APButtonColor.black, buttonType: APButtonType.pay } ``` *** ### APButtonLoadedResult Object | **Name** | **Type** | **Description** | | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | status | iStatus |

There are 3 possible cases:

Apple Pay Button loaded successfully: status = iStatus.success
Apple Pay not supported: status = iStatus.unsupported
An error occurred while loading Apple Pay Button: status = iStatus.error

| | reason | String | If Apple Pay Button failed to load this field will be populated with the reason. | *** ### ApplePayContactField *Field names used for requesting contact information in a payment request.* Available fields: * name * email * phone * postalAddress ### **ApplePay Contact Field example** ``` ... requiredBillingContactFields: ['postalAddress', 'name', 'phone', 'email'], requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'], ... ``` ### PaymentContact Object | **Name** | **Type** | **Description** | | --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | phoneNumber | String | A phone number for the contact | | emailAddress | String | An email address for the contact | | givenName | String | The contact’s given name | | familyName | String | The contact’s family name | | addressLines | String\[] | The street portion of the address for the contact | | subLocality | String | Additional information associated with the location, typically defined at the city or town level (such as district or neighborhood), in a postal address | | locality | String | The city for the contact | | postalCode | String | The zip code or postal code, where applicable, for the contact | | subAdministrativeArea | String | The subadministrative area (such as a county or other region) in a postal address | | administrativeArea | String | The state for the contact | | country | String | The name of the country or region for the contact | | countryCode | String | The contact’s two-letter ISO 3166 country code | ### ShippingContactResponse Object | **Name** | **Type** | **Description** | | ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- | | `lineItems` | [LineItem](#lineitem-object)\[] | A set of line items that explain recurring payments and additional charges and discounts. | | `total` | [LineItem](#lineitem-object) | A line item that represents the total for the payment. | | `shippingMethods` | [ShippingMethod](#shippingmethod-object)\[] | A list of Shipping Methods | | `error` | [Error](#aperrorcode) | Error code | ### LineItem Object {% hint style="info" %} We’re now supporting **Recurring** and **Deferred** Payments as well as **Subscriptions**.\ These features are supported starting iOS 15.4.
These features are available if `support_recurring` and/or `support_subscription` is part of [requiredFeatures](https://docs.cardknox.com/mobile-wallets/apple-pay-hosted-checkout/apple-pay-hosted-checkout-objects-reference-request#applepayrequest) list. {% endhint %} | Name | Type | Description | | --------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | type | ApplePayLineItemType | A value that indicates whether the line item is final or pending | | label | String | A required value that’s a short, description of the line item | | amount | String | A required value that’s the monetary amount of the line item. | | **Recurring and Subscription** | | | | `paymentTiming` | ApplePayPaymentTiming object | The time that the payment occurs as part of a successful transaction | | `recurringPaymentStartDate` | Date | The date of the first payment | | `recurringPaymentEndDate` | Date | The date of the final payment | | `recurringPaymentIntervalUnit` | ApplePayRecurringPaymentDateUnit | The amount of time — in calendar units, such as day, month, or year — that represents a fraction of the total payment interval | | `recurringPaymentIntervalCount` | Long | The number of interval units that make up the total payment interval | | `deferredPaymentDate` | Date | The date, in the future, of the payment | | `automaticReloadPaymentThresholdAmount` | String | The balance an account reaches before the merchant applies the automatic reload amount | ### ApplePayLineItemType * `final` - A line item representing the known, final cost. * `pending` - A line item representing an estimated or unknown cost. ### ApplePayRecurringPaymentDateUnit * `year` * `month` * `day` * `hour` * `minute` **Recurring Line Item Example (Charging $20 starting today for the next year)** {% code lineNumbers="true" %} ```javascript const startDate = new Date(); const endDate = new Date(startDate.getFullYear()+1, startDate.getMonth(), startDate.getDate()); lineItem = { "label": "Subscription", "amount": "20.00", "type": "final", "paymentTiming": "recurring", "recurringPaymentStartDate": startDate, "recurringPaymentIntervalUnit": "month", "recurringPaymentIntervalCount": 1, "recurringPaymentEndDate": endDate, } ``` {% endcode %} ### ShippingMethod Object | **Name** | **Type** | **Description** | | ---------- | -------- | ------------------------------------ | | label | String | Label for this Shipping Method | | amount | String | Price for this shipping option | | detail | String | Description for this Shipping Method | | identifier | String | Identifier for this Shipping Method | ### **ShippingMethod example** ```json { "label": "Free Shipping", "amount": "0.00", "detail": "Arrives in 7 to 10 business days", "identifier": "free" } ``` *** ### PaymentMethod Object | **Name** | **Type** | **Description** | | -------------- | ----------------- | ------------------------------------------------------- | | displayName | String | A string, suitable for display, that describes the card | | network | String | Name of the payment network backing the card | | type | PaymentMethodType | The card's type of payment | | billingContact | PaymentContact | The billing contact associated with the card | *** ### PaymentMethodType *A payment card’s type of payment.* The payment method type value is one of: * debit * credit * prepaid * store ### Error Object **Note:** Supported starting iOS 11.\ Available when `address_validation` is part of [requiredFeatures](https://docs.cardknox.com/mobile-wallets/apple-pay-hosted-checkout/apple-pay-hosted-checkout-objects-reference-request#applepayrequest) list. | **Name** | **Type** | **Description** | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `code` | [APErrorCode](https://cardknox.atlassian.net/wiki/spaces/PUB/pages/2366144654/Apple+Pay+Hosted+Checkout+Objects+reference+Request#APErrorCode) | One of Apple Pay Error Codes | | `contactField` | [APErrorContactField](https://cardknox.atlassian.net/wiki/spaces/PUB/pages/2366144654/Apple+Pay+Hosted+Checkout+Objects+reference+Request#APErrorContactField) | One of Apple Pay Error Contact fields | | `message` | String | Error message displayed to the customer |
# Apple Pay Hosted Checkout Objects Reference (Response) ## **Response objects** For the Full Response example click [here](/mobile-wallets/apple-pay-hosted-checkout/apple-pay-hosted-checkout-sample-code) *** ### ApplePayload Object | **Name** | **Type** | **Always exists** | **Description** | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------- | | billingContact | [PaymentContact](https://docs.cardknox.com/cardknox-products/apple-pay-hosted-checkout/apple-pay-hosted-checkout-objects-reference-request#paymentcontact-object) | No | Contains all transaction data. For more details please click on the link. | | shippingContact | [PaymentContact](https://docs.cardknox.com/cardknox-products/apple-pay-hosted-checkout/apple-pay-hosted-checkout-objects-reference-request#paymentcontact-object) | No | This is a response object that's returned by Apple after a payer approves payment. | | token | PaymentToken | Yes | This is a response object that's returned by Apple after a payer approves payment. | *** ### PaymentToken Object | **Name** | **Type** | **Always exists** | **Description** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | paymentData | JSON | Yes | An object containing the encrypted payment data. **This is the object that needs to be Base64 Encoded and sent to gateway as** xCardNum. | | paymentMethod | [PaymentMethod](https://docs.cardknox.com/cardknox-products/apple-pay-hosted-checkout/apple-pay-hosted-checkout-objects-reference-request#paymentmethod-object) | Yes | Information about the card used in the transaction. | | transactionIdentifier | String | Yes | A unique identifier for this payment | **paymentData use example** ``` var reqGateway = new { ......... xcardnum = Convert.ToBase64String(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(req.paymentData))) ......... }; ``` *** ### PaymentComplete Object An object returned from onPaymentAuthorize ajax call - typically a Gateway Response\ An example of PaymentComplete Response returned by iFields is below: ``` { "xResult": "A", "xStatus": "Approved", "xError": "", "xErrorCode": "00000", "xRefNum": "481244058", "xExp": "0424", "xAuthCode": "OK8853", "xBatch": "6332569", "xAvsResultCode": "YYY", "xAvsResult": "Address: Match & 5 Digit Zip: Match", "xCvvResultCode": "S", "xCvvResult": "Should be On card but Not so indicated", "xAuthAmount": "1.12", "xMaskedCardNumber": "5xxxxxxxxxxx6344", "xCardType": "MasterCard", "xName": "Test Applepay", "xToken": "34q9h58n68qh24p7719m76m0nhm013hh", "xMID": "xxxxxxxxxxx0661", "xTID": "xxxx0003", "xDate": "7/13/2021 7:18:02 PM", "xAuthNetwork": "3", "xEntryMethod": "Keyed", "xCAVV": "ALyaPlPZZIgIADhFniB+AoABFA==", "xEciFlag": "01" } ``` # Apple Pay iFields Integration ```javascript

``` # Apple Pay Hosted Checkout Sample Code 1. **Let's define a helper object with all necessary components:** ```javascript window.apRequest = { buttonOptions: { buttonContainer: "ap-container", buttonColor: APButtonColor.black, buttonType: APButtonType.pay }, totalAmount: null, taxAmt: null, shippingMethod: null, creditType: null, getTransactionInfo: function (taxAmt, shippingMethod, creditType) { try { this.shippingMethod = shippingMethod || this.shippingMethod || { "label": "Free Shipping", "amount": "0.00", "type": "final" }; this.taxAmt = roundToNumber(taxAmt, 4) || this.taxAmt || 0.07; this.creditType = creditType || this.creditType; const amt = getAmount(); const lineItems = [ { "label": "Subtotal", "type": "final", "amount": amt }, this.shippingMethod ]; if (this.creditType === "credit") { lineItems.push({ "label": "Credit Card Fee", "amount": roundTo(0.0275*amt, 2), "type": "final" }); } lineItems.push({ "label": "Estimated Tax", "amount": roundTo(this.taxAmt*amt, 2), "type": "final" }); let totalAmt = 0; lineItems.forEach((item) => { totalAmt += parseFloat(item.amount)||0; }); totalAmt = roundTo(totalAmt, 2); this.totalAmount = totalAmt; return { 'lineItems': lineItems, total: { type: 'final', label: 'Total', amount: totalAmt, } }; } catch (err) { console.error("getTransactionInfo error ", exMsg(err)); } }, onGetTransactionInfo: function () { try { return this.getTransactionInfo(); } catch (err) { console.error("onGetTransactionInfo error ", exMsg(err)); } }, onGetShippingMethods: function() { return [ { label: 'Free Shipping', amount: '0.00', identifier: 'free', detail: 'Delivers in five business days', }, { label: 'Express Shipping', amount: '5.00', identifier: 'express', detail: 'Delivers in two business days', }, ]; }, onShippingContactSelected: function(shippingContact) { const self = this; return new Promise((resolve, reject) => { try { console.log("shippingContact", JSON.stringify(shippingContact)); let taxAmt = 0.1; const newShippingMethods = [ { label: 'Free Shipping', amount: '0.00', identifier: 'free', detail: 'Delivers in five business days', } ]; if (shippingContact && shippingContact.administrativeArea) { if (shippingContact.administrativeArea === "NY") { taxAmt = 0.0875; newShippingMethods.push( { label: 'Overnight Shipping', amount: '10.00', identifier: 'overnight', detail: 'Delivers in one business days', } ); } else if (shippingContact.administrativeArea === "NJ") { taxAmt = 0.07; newShippingMethods.push( { label: 'Express Shipping', amount: '5.00', identifier: 'express', detail: 'Delivers in two business days', } ); } } const resp = self.getTransactionInfo(taxAmt, newShippingMethods[0]); resp.shippingMethods = newShippingMethods; resolve(resp); } catch (err) { const apErr = { code: "-101", contactField: "", message: exMsg(err) } console.error("onShippingContactSelected error.", exMsg(err)); reject({errors: [err]}); } }) }, onShippingMethodSelected: function(shippingMethod) { const self = this; return new Promise(function (resolve, reject) { try { console.log("shippingMethod", JSON.stringify(shippingMethod)); const resp = self.getTransactionInfo(null, shippingMethod); resolve(resp); } catch (err) { const apErr = { code: "-102", contactField: "", message: exMsg(err) } console.error("onShippingMethodSelected error.", exMsg(err)); reject({errors: [err]}); } }) }, onPaymentMethodSelected: function(paymentMethod) { const self = this; return new Promise((resolve, reject) => { try { console.log("paymentMethod", JSON.stringify(paymentMethod)); const resp = self.getTransactionInfo(null, null, paymentMethod.type); resolve(resp); } catch (err) { const apErr = { code: "-102", contactField: "", message: exMsg(err) } console.error("onPaymentMethodSelected error.", exMsg(err)); reject({errors: [err]}); } }) }, validateApplePayMerchant: function () { return new Promise((resolve, reject) => { try { var xhr = new XMLHttpRequest(); xhr.open("POST", "https://api.cardknox.com/applepay/validate"); xhr.onload = function () { if (this.status >= 200 && this.status < 300) { console.log("validateApplePayMerchant", JSON.stringify(xhr.response)); resolve(xhr.response); } else { console.error("validateApplePayMerchant", JSON.stringify(xhr.response), this.status); reject({ status: this.status, statusText: xhr.response }); } }; xhr.onerror = function () { console.error("validateApplePayMerchant", xhr.statusText, this.status); reject({ status: this.status, statusText: xhr.statusText }); }; xhr.setRequestHeader("Content-Type", "application/json"); xhr.send(); } catch (err) { setTimeout(function () { console.log("getApplePaySession error: " + exMsg(err)) }, 100); } }); }, onValidateMerchant: function() { return new Promise((resolve, reject) => { try { this.validateApplePayMerchant() .then((response) => { try { console.log(response); resolve(response); } catch (err) { console.error("validateApplePayMerchant exception.", JSON.stringify(err)); reject(err); } }) .catch((err) => { console.error("validateApplePayMerchant error.", JSON.stringify(err)); reject(err); }); } catch (err) { console.error("onValidateMerchant error.", JSON.stringify(err)); reject(err); } }); }, authorize: function(applePayload, totalAmount) { return new Promise(function (resolve, reject) { var xhr = new XMLHttpRequest(); xhr.open("POST", "https:///"); xhr.onload = function () { if (this.status >= 200 && this.status < 300) { resolve(xhr.response); } else { reject({ status: this.status, statusText: xhr.statusText }); } }; xhr.onerror = function () { reject({ status: this.status, statusText: xhr.statusText }); }; const data = { amount: totalAmount, payload: applePayload }; xhr.setRequestHeader("Content-Type", "application/json"); xhr.send(JSON.stringify(data)); }); }, onPaymentAuthorize: function(applePayload) { return new Promise((resolve, reject) => { try { this.authorize(applePayload, this.totalAmount) .then((response) => { try { console.log(response); const resp = JSON.parse(response); if (!resp) throw "Invalid response: "+ response; if (resp.xError) { throw resp; } resolve(response); } catch (err) { throw err; // reject(err); } }) .catch((err) => { console.error("authorizeAPay error.", JSON.stringify(err)); apRequest.handleAPError(err); reject(err); }); } catch (err) { console.error("onPaymentAuthorize error.", JSON.stringify(err)); apRequest.handleAPError(err); reject(err); } }); }, onPaymentComplete: function(paymentComplete) { if (paymentComplete.response) { //Success const resp = JSON.parse(paymentComplete.response); if (resp.xRefNum) { setTimeout(function(){ console.log("Thank you for your order:("+resp.xRefNum+")")}, 100); } else { setTimeout(function(){ console.log("Thank you for your order.")}, 100); } } else if (paymentComplete.error) { console.error("onPaymentComplete", exMsg(paymentComplete.error)); handleAPError(paymentComplete.error); } }, handleAPError: function(err) { if (err && err.xRefNum) { setTimeout(function(){ alert("There was a problem with your order:("+err.xRefNum+")")}, 100); } else { setTimeout(function(){ alert("There was a problem with your order:"+exMsg(err))}, 100); } }, initAP: function() { return { buttonOptions: this.buttonOptions, merchantIdentifier: "", requiredBillingContactFields: ['postalAddress', 'name', 'phone', 'email'], requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'], onGetTransactionInfo: "apRequest.onGetTransactionInfo", onGetShippingMethods: "apRequest.onGetShippingMethods", onShippingContactSelected: "apRequest.onShippingContactSelected", onShippingMethodSelected: "apRequest.onShippingMethodSelected", onPaymentMethodSelected: "apRequest.onPaymentMethodSelected", onValidateMerchant: "apRequest.onValidateMerchant", onPaymentAuthorize: "apRequest.onPaymentAuthorize", onPaymentComplete: "apRequest.onPaymentComplete", onAPButtonLoaded: "apRequest.apButtonLoaded", isDebug: true }; }, apButtonLoaded: function(resp) { if (!resp) return; if (resp.status === iStatus.success) { showHide(this.buttonOptions.buttonContainer, true); showHide("lbAPPayload", true); } else if (resp.reason) { console.log(resp.reason); } } } ``` 2. **Let’s enable Apple Pay for the website:** ```javascript document.addEventListener("DOMContentLoaded", function(event) { ..... ckApplePay.enableApplePay({ initFunction: 'apRequest.initAP', amountField: 'amount' }); ..... } ``` 3. To see the full solution please click [**here**](/mobile-wallets/apple-pay-hosted-checkout/apple-pay-ifields-integration)**.** # Apple Pay Features ## Overview In this section we will describe the new Apple Pay features supported by Sola. Please note that every feature is supported starting with certain iOS version. This means that if you requesting a feature (Recurring for example) and it requires iOS 15.4 - Apple Pay button will be shown on consumer devices with iOS 15.4+ #### Available Features * Address Validation * Support Recurring * Support Subscription - For subscriptions you have to follow [Apple Pay Guidelines](https://developer.apple.com/design/human-interface-guidelines/technologies/apple-pay/subscriptions-and-donations) In order to take advantage of any new feature Sola supports, you need to request it through [ApplePayRequest](https://docs.cardknox.com/mobile-wallets/apple-pay-hosted-checkout/apple-pay-hosted-checkout-objects-reference-request#applepayrequest) endpoint. The requiredFeatures object contains features from the [Available Features](https://docs.cardknox.com/mobile-wallets/apple-pay-hosted-checkout/apple-pay-hosted-checkout-objects-reference-request#aprequiredfeatures) list.


Feature	Feature Code
Address Validation	`APRequiredFeatures.address_validation`
Support Recurring	`APRequiredFeatures.support_recurring`
Support Subscription	`APRequiredFeatures.support_subscription`

**Apple Pay Request example** ``` initAP: function() { return { buttonOptions: this.buttonOptions, merchantIdentifier: "", .................................. requiredFeatures: [APRequiredFeatures.address_validation, APRequiredFeatures.support_recurring], .................................. requiredBillingContactFields: ['postalAddress', 'name', 'phone', 'email'], requiredShippingContactFields: ['postalAddress', 'name', 'phone', 'email'], }; } ``` # Set up Apple Pay Merchant ID with Sola ## Setting up Apple Pay Merchant ID 1. Login to 2. Navigate to Gateway Settings > Payment Methods 3. Click on “Configure Apple Pay“
# Click-To-Pay - Hosted Checkout ## Overview Click-To-Pay Hosted Checkout is our simple integration that enables online Click-To-Pay processing through the Sola gateway. This landing page contains all of the links and references needed for setting up and maintaining Click-To-Pay Checkout Experience. \ Please reference the **Initial Setup** and Click-To-Pay **Resources** sections below. ## Flow There are three possible scenario: 1. **New User**\ In this case Click-To-Pay Experience will be presented as a button\ ![](/files/fZNJJen6xl4XeVdC04Af) 2. **Recognized User**\ Consumer’s cards will be displayed\ ![](/files/UJKmguSVzzRUXIPW2iTm) 3. **Recognized Device**\ An email screen to identify the consumer and load his cards\ ![](/files/soISUXM5NMSyYn2P9WAK)
## Click-To-Pay Resources The following pages can be found by viewing the navigation bar on the left side of the screen. * [Initial Setup](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-initial-setup) * [Sample Code](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-sample-code) * [iFields Integration](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-ifields-integration) * [Request Objects](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-objects-reference-request) * [Response Objects](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-objects-reference-response) # Click-To-Pay Initial Setup ## Overview Our simple iFields integration enables online Click-To-Pay processing through the Sola gateway.\ This document details the steps necessary to integrate Click-To-Pay with your site. **Contents** * [Prerequisites](#prerequisites) * [Client-Side Integration](#client-side-integration) * [Adding Reference to iFields](#adding-reference-to-ifields) * [Adding JavaScript Objects for Click-To-Pay button](#adding-javascript-objects-for-click-to-pay-button) * [Enabling Click-To-Pay](#enable-click-to-pay) * [Server-Side Integration](#server-side-integration) * [Server Endpoint Creation](#server-endpoint-creation) * [API Integration](#api-integration) ## Prerequisites Register for Click-To-Pay: See \[insert link here] ## Implementing Click-To-Pay ### Client-Side Integration #### Adding Reference to iFields {% hint style="info" %} Find the latest version of iFields at: [https://cdn.cardknox.com/ifields/versions.htm](https://nam10.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcdn.cardknox.com%2Fifields%2Fversions.htm\&data=04%7C01%7Csaltman%40cardknox.com%7Cee27e2f8cee34d8eb64108d96965fb39%7Cbee12808a32d4518bad72e695a86fc91%7C0%7C0%7C637656709056206810%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000\&sdata=EkulORguWhCwZ%2BApGRr3WBqvzxcnnMsHj6w2nxzCwog%3D\&reserved=0) {% endhint %} **Step 1:** Add the iFields.js file after the \ tag on your payment page: ```html ``` #### Adding JavaScript Objects for Click-To-Pay button **Step 1:** Add the following JS snippet inside the *\* where the Click-To-Pay button is desired. ```html

``` **Step 2:** Create JavaScript object that holds all of the properties/methods required to process Click-To-Pay. ```javascript const click2payRequest = { paymentPrefill: function(){ const result = { merchantRequestId: "Merchant defined request ID", currencyCode: "USD", description: "...corp Product", orderId: "Merchant defined order ID", promoCode: "Merchant defined promo code", subtotal: roundTo(getAmount(), 2), shippingHandling: "2.00", tax: "2.00", discount: "1.00", giftWrap: "2.00", misc: "1.00", setTotal: function() { this.total = roundTo( roundToNumber(this.subtotal, 2) + roundToNumber(this.shippingHandling, 2) + roundToNumber(this.tax, 2) + roundToNumber(this.giftWrap, 2) + roundToNumber(this.misc, 2) - roundToNumber(this.discount, 2) , 2); delete this.setTotal; return this; }, }.setTotal(); logDebug({ label: "paymentPrefill", data: result }); return result; }, paymentCallback: function (payload) { click2payRequest.setPayload(payload); }, setPayload: function (value) { document.getElementById('c2p-payload').value = JSON.stringify(value, null, 2); showHide("divC2PPayload", value); } } ``` For a full sample code please refer to [Click-To-Pay Sample Code](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-sample-code) **Step 3:** Implement desired callbacks. For the list of available callbacks, please refer to [Click-To-Pay Request](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-objects-reference-request) object. There are two main callbacks that must be implemented (the rest are optional): * onPaymentPrefill - calculates total amount and sets transaction information. * onPaymentSuccess - a callback that will be called after the consumer pays and Click-To-Pay returns a payload with all of the requested consumer information. This is where you need to make an ajax call to your server with the payload. The sample for making an ajax call is below: *Sample Code for Making Ajax Call:* ```javascript onPaymentSuccess: function(clickToPayResponse) { return new Promise(function (resolve, reject) { var xhr = new XMLHttpRequest(); xhr.open("POST", "https:///"); xhr.onload = function () { if (this.status >= 200 && this.status < 300) { resolve(xhr.response); } else { reject({ status: this.status, statusText: xhr.statusText }); } }; xhr.onerror = function () { reject({ status: this.status, statusText: xhr.statusText }); }; xhr.setRequestHeader("Content-Type", "application/json"); xhr.send(JSON.stringify(clickToPayResponse)); }); } ``` For full integration code, please refer to [Click-To-Pay iFields Integration](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-ifields-integration) #### Enable Click-To-Pay **window\.ckClickToPay object** - controls initialization of Click-To-Pay button | **Method** | **Call Required** | **Description** | | ---------------- | ----------------- | -------------------------------------------- | | enableClickToPay | Yes | Initializes and enables Click-To-Pay Button. | #### enableClickToPay Parameters | **Name** | **Type** | **Required** | **Description** | | -------------- | -------- | ------------ | --------------------------------------------------------------- | | initParameters | Object | Yes | Object that contains initialization parameters for Click-To-Pay | {% hint style="info" %} For full list of Init Parameters, please refer to [Click-To-Pay Request Object](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-objects-reference-request#clicktopayrequest) {% endhint %} *** {% code title="Enable Click-To-Pay example" %} ```javascript ckClick2Pay.enableClickToPay({ environment: c2pEnvironment.sandbox, externalClientId: "", click2payContainer: "click2payContainer", onPaymentPrefill: click2payRequest.paymentPrefill, onPaymentSuccess: click2payRequest.paymentCallback }); ``` {% endcode %} *** ### Server-Side Integration #### Server Endpoint Creation A server endpoint is needed in order to accept the Click-To-Pay Payload from your website. **Step 1:** Create an endpoint and method for API Integration on your server side that takes a Click-To-Pay Payload and makes a call to Sola. For full list of Returned Parameters, please refer to Click-To-Pay Response Reference #### API Integration This section assumes that you already know how to integrate other payments with [Sola API](/api/transaction). **Below are the steps to integrate Click-To-Pay with the Sola API:** Once the consumer confirms the payment, Click-To-Pay API generates a [Click-To-Pay Response](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-objects-reference-response#clicktopayresponse-object) in the form of a JSON string. Integration Steps: 1. Set the required fields: 1. xDigitalWalletType to ClickToPay 2. xClickToPayTransactionId to clickToPayResponse.payload.transactionId 3. xClickToPayExternalClientId to clickToPayResponse.payload.externalClientId 4. xClickToPayEncryptionKey to clickToPayResponse.payload.encryptionKey 5. xCardNum to clickToPayResponse.payload.token 6. xAmount to clickToPayResponse.amount 7. xCommand - Set to one of the values that starts with cc: like cc:sale, cc:auth, etc. 8. xKey to "Your xKey" 9. xVersion = "4.5.9" 10. xSoftwareName to “Your Software Name" 11. xSoftwareVersion to "Your Software Version" Sample Request: ```javascript public async Task Authorize(clickToPayResponse resp) { var reqGateway = new { xKey = "Your xKey", xDigitalWalletType = "ClickToPay", xAmount = (decimal)resp.amount, xClickToPayTransactionId = resp.payload.transactionId, xClickToPayExternalClientId = resp.payload.externalClientId, xClickToPayEncryptionKey = resp.payload.encryptionKey, xCardNum = resp.payload.token, xCommand = "cc:sale", xVersion = "4.5.8", xSoftwareName= "Your Software Name", xSoftwareVersion = "Your Software Version" }; var respMsg = ""; using (var http = new HttpClient()) { var resp = await http.PostAsJsonAsync("https://x1.cardknox.com/gatewayJSON", reqGateway); respMsg = await resp.Content.ReadAsStringAsync(); ..... } ..... } ``` For more details, please contact your Sola Representative. ## Questions? Contact # Click-To-Pay Sample Code 1. **Let's define a helper object with all necessary components:** ```javascript const click2payRequest = { paymentPrefill: function(){ const result = { merchantRequestId: "Merchant defined request ID", currencyCode: "USD", description: "...corp Product", orderId: "Merchant defined order ID", promoCode: "Merchant defined promo code", subtotal: roundTo(getAmount(), 2), shippingHandling: "2.00", tax: "2.00", discount: "1.00", giftWrap: "2.00", misc: "1.00", setTotal: function() { this.total = roundTo( roundToNumber(this.subtotal, 2) + roundToNumber(this.shippingHandling, 2) + roundToNumber(this.tax, 2) + roundToNumber(this.giftWrap, 2) + roundToNumber(this.misc, 2) - roundToNumber(this.discount, 2) , 2); delete this.setTotal; return this; }, }.setTotal(); logDebug({ label: "paymentPrefill", data: result }); return result; }, authorize: function(payload) { return new Promise(function (resolve, reject) { var xhr = new XMLHttpRequest(); xhr.open("POST", "https:///"); xhr.onload = function () { if (this.status >= 200 && this.status < 300) { resolve(xhr.response); } else { reject({ status: this.status, statusText: xhr.statusText }); } }; xhr.onerror = function () { reject({ status: this.status, statusText: xhr.statusText }); }; xhr.setRequestHeader("Content-Type", "application/json"); xhr.send(JSON.stringify(payload)); }); }, paymentSuccess: async function(clickToPayResponse) { return new Promise((resolve, reject) => { try { const response = await this.authorize(clickToPayResponse); console.log(response); const resp = JSON.parse(response); if (!resp) throw "Invalid response: "+ response; if (resp.xError) { throw resp; } resolve(response); } catch (err) { console.error("paymentSuccess error.", JSON.stringify(err)); reject(err); } }); },a paymentCallback: function (clickToPayResponse) { click2payRequest.setPayload(clickToPayResponse); }, cpButtonLoaded: function(resp) { if (!resp) return; if (resp.status === iStatus.success) { showHide("click2payContainer", true); } else if (resp.reason) { console.log(resp.reason); } }, setPayload: function (value) { document.getElementById('c2p-payload').value = JSON.stringify(value, null, 2); showHide("divC2PPayload", value); } } ``` 2. **Let’s enable Click-To-Pay for the website:** ```javascript document.addEventListener("DOMContentLoaded", function(event) { ..... ckClick2Pay.enableClickToPay({ environment: c2pEnvironment.sandbox, externalClientId: "", click2payContainer: "click2payContainer", onPaymentPrefill: click2payRequest.paymentPrefill, onPaymentSuccess: click2payRequest.paymentSuccess, onPaymentError: click2payRequest.paymentCallback, onPaymentCancel: click2payRequest.paymentCallback, onButtonLoaded: click2payRequest.cpButtonLoaded }); ..... } ``` 3. To see the full solution please click [**here**](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-ifields-integration)**.** # Click-To-Pay iFields Integration {% code lineNumbers="true" %} ```javascript

``` {% endcode %} # Click-To-Pay Objects Reference (Request) ***For complete sample code please refer*** [***here***](/mobile-wallets/click-to-pay-hosted-checkout/click-to-pay-sample-code) ### **Available dictionary objects** #### iStatus ```javascript const iStatus = { success: 100, unsupported: -100, error: -200 } ``` **Use:** iStatus.success #### c2pEnvironment ```javascript const c2pEnvironment = { sandbox: 0, production: 1 } ``` **Use:** c2pEnvironment.sandbox #### c2pReviewAction ```javascript const c2pReviewAction = { pay: "PAY", continue: "CONTINUE" } ``` **Use:** c2pReviewAction.pay ### **Request objects** #### ClickToPayRequest **The Main object that contains all the information necessary to communicate with Click-To-Pay API.** | **Name** | **Type** | **Required** | **Description** | | -------------------------------- | ----------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `environment` | [c2pEnvironment](#c2penvironment) | Yes |

Can be either
c2pEnvironment.sandbox or
c2pEnvironment.production

ID assigned to your merchant by
Click-To-Pay Registration

ID of the main div that will host the
Click-To-Pay experience

Default: c2p-def
To override default styling, use
this field to provide the name of your
own css class

Default: true
After checkout Click-To-Pay control
will be automatically reloaded.
This controls if “Wait“ screen is set
during that operation

Default: c2pReviewAction.pay
Controls final Button caption
consumer clicks to make the payment

A callback function to be called when
Click-To-Pay button is loaded.
Accepts an object of type
CPButtonLoadedResult
Please click here for the sample code

A callback function that returns the
final price and tax calculations.
Please click here for the sample code

A callback function to be called
before Payment is made.
Usually used to make custom
validations before the payment.
Please click here for the sample code

A callback function to be called when
Click-To-Pay Payment is authorized
for the completion of the transaction.
This function accepts a parameter of
ClickToPayResponse.
Please click here for the sample code

A callback function to be called when
user cancels.
Please click here for the sample code

A callback function to be called when
payment errors out.
Please click here for the sample code

| #### **onCPButtonLoaded callback example** ```javascript onCPButtonLoaded: function(resp) { if (!resp) return; if (resp.status === iStatus.success) { showHide("click2payContainer", true); } else if (resp.reason) { console.log(resp.reason); } } ``` #### **onPaymentPrefill callback example** ```javascript onPaymentPrefill: function(){ const result = { merchantRequestId: "Merchant defined request ID", currencyCode: "USD", description: "...corp Product", orderId: "Merchant defined order ID", promoCode: "Merchant defined promo code", subtotal: roundTo(getAmount(), 2), shippingHandling: "2.00", tax: "2.00", discount: "1.00", giftWrap: "2.00", misc: "1.00", setTotal: function() { this.total = roundTo( roundToNumber(this.subtotal, 2) + roundToNumber(this.shippingHandling, 2) + roundToNumber(this.tax, 2) + roundToNumber(this.giftWrap, 2) + roundToNumber(this.misc, 2) - roundToNumber(this.discount, 2) , 2); delete this.setTotal; return this; } }.setTotal(); return result; } ``` #### **onPaymentValidate callback example** ```javascript onPaymentValidate: function () { return new Promise(function (resolve, reject) { try { //Do some validation here resolve(iStatus.success); } catch (err) { reject(err); } }); } ``` #### **onPaymentSuccess callback example** ```javascript onPaymentSuccess: async function(clickToPayResponse) { return new Promise((resolve, reject) => { try { const response = await this.authorize(clickToPayResponse); console.log(response); const resp = JSON.parse(response); if (!resp) throw "Invalid response: "+ response; if (resp.xError) { throw resp; } resolve(response); } catch (err) { console.error("paymentSuccess error.", JSON.stringify(err)); reject(err); } }); } ``` #### **onPaymentCancel callback example** ```javascript onPaymentCancel: function (payload) { logError("Click-To-Pay Cancelled", payload); //Do some custom logic here } ``` #### **onPaymentError callback example** ```javascript onPaymentCancel: function (payload) { logError("Click-To-Pay Error", payload); //Do some custom logic here } ``` *** #### CPButtonLoadedResult Object | **Name** | **Type** | **Description** | | -------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | status | [iStatus](#istatus) |

There are be 3 possible cases:

Click-To-Pay Button loaded successfully: status = iStatus.success
An error occurred while loading Click-To-Pay Button: status = iStatus.error

| | reason | String | If Click-To-Pay Button failed to load this field will be populated with the reason. | *** # Click-To-Pay Objects Reference (Response) ### **Response objects** *** #### ClickToPayResponse Object | **Name** | **Type** | **Always exists** | **Description** | | ------------------- | ---------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------- | | `status` | String | Yes | Contains all transaction data. For more details please click on the link | | `amount` | Decimal | Yes | This is a response object that's returned by Google after a payer approves payment | | `merchantRequestId` | String | No | This is a response object that's returned by Google after a payer approves payment | | `merchantOrderId` | String | No | This is a response object that's returned by Google after a payer approves payment | | `payload` | [ClickToPayPayload](#clicktopaypayload-object) | Yes | This is a response object that's returned by Google after a payer approves payment | *** #### ClickToPayPayload Object | **Name** | **Type** | **Always exists** | **Description** | | ------------------ | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `transactionId` | String | Yes | A unique identifier for this payment | | `externalClientId` | String | Yes | Information about the card used in the transaction. | | `encryptionKey` | String | Yes | A unique identifier for this payment | | `token` | String | Yes | An object containing the encrypted payment data. **This is the object that needs to be Base64 Encoded and sent to gateway as** `xCardNum` | *** **ClickToPayResponse object example** ```json { "status": "success", "amount": 6, "merchantRequestId": "Merchant defined request ID", "merchantOrderId": "Merchant defined order ID", "payload": { "transactionId": "1947120568389887601", "externalClientId": "test123", "encryptionKey": "Pqdjv842Nv...8q14l", "token": "FPA6TTy0q457.....tCf+tqH5/ruIQ1Iz4FI9hE5NBD+EM=" } } ``` # Google Pay Hosted Checkout ## Overview Google Pay Hosted Checkout is our simple integration that enables online Google Pay processing through the Sola gateway. This document details the steps necessary to integrate Google Pay Hosted Checkout with your site. **Contents** * Server-Side Integration * Server Endpoint Creation * API Integration * Client-Side Integration * Adding Reference to iFields * Adding iFrame and JavaScript objects for the Google Pay button * Enabling Google Pay ## Implementing Google Pay Hosted Checkout ### Server-Side Integration #### Server Endpoint Creation A server endpoint is needed in order to accept the Google Payload from Hosted Checkout. **Step 1:** Create an endpoint and method for API Integration on your server side that takes the [Google Payload](/mobile-wallets/google-pay-hosted-checkout/response-objects) and makes a call to Sola.
#### API Integration **Below are the steps to integrate Google Pay with the Sola API:** Once the consumer confirms the payment, Google Pay API generates a token in the form of a JSON string. Integration Steps: 1. Encode that token with Base64 encoding. 2. Set `xCardNum` field to the encoded token above. 3. Set `xDigitalWalletType` to `GooglePay`. 4. Set the remaining required fields: 1. `xAmount` to `transactionInfo.totalPrice` - this is the consumer-approved amount from the Google Pay payment sheet. 2. `xCommand` - Set to one of the values that start with `cc:` like `cc:sale`, `cc:auth`, etc. 3. `xBillFirstName` 4. `xBillLastName` 5. `xBillStreet` if available 6. `xBillCity` if available 7. `xBillState` if available 8. `xBillZip` For more details, please contact your Sola Representative. ### Client-Side Integration #### Adding Reference to iFields {% hint style="info" %} Find the latest version of iFields [here](https://cdn.cardknox.com/ifields/versions.htm). {% endhint %} **Step 1:** Add the iFields .js file after the \ tag on your payment page: ```javascript ``` #### Adding iFrame and JavaScript Objects for Google Pay button **Step 1:** Add the following iFrame JS snippet inside the *\* where the Google Pay button is desired. * Make sure you have an attribute `data-ifields-id="igp"` as part of *\ ``` **Step 2:** Create JavaScript object that holds all of the properties/methods required to process Google Pay. ```javascript window.gpRequest = { merchantInfo: { merchantName: "Example Merchant" }, buttonOptions: { buttonSizeMode: GPButtonSizeMode.fill }, billingParams: { //phoneNumberRequired: true, emailRequired: true, billingAddressRequired: true, billingAddressFormat: GPBillingAddressFormat.full }} ``` {% hint style="info" %} Full a full sample code, refer to the iFields [document.](/products/ifields) {% endhint %} **Step 3:** Implement desired callbacks. For the list of available callbacks, please refer to [Google Pay Object](/mobile-wallets/google-pay-hosted-checkout/request-objects#GooglePayRequest). * The two main functions below need to be implemented (the rest are optional): * **onGetTransactionInfo:** calculates the total amount based on the charge amount, fees, taxes, shipping costs, etc. * **onProcessPayment** - a callback that will be called after the consumer pays and Google returns a token with all other requested consumer information like billing address, shipping address, etc. This is where you need to make an ajax call to your server with the Google Payload. The sample for making an ajax call please see below. *Sample Code for making Ajax Call:* ```javascript initGP: function authorizeGPay(googlePayload) { return new Promise(function (resolve, reject) { var xhr = new XMLHttpRequest(); xhr.open("POST", https://yourserver.com/your-endpoint); xhr.onload = function () { if (this.status >= 200 && this.status < 300) { resolve(xhr.response); } else { reject({ status: this.status, statusText: xhr.statusText }); } }; xhr.onerror = function () { reject({ status: this.status, statusText: xhr.statusText }); }; xhr.setRequestHeader("Content-Type", "application/json"); xhr.send(JSON.stringify(googlePayload)); }); } ``` {% hint style="info" %} For full sample code, please refer to [Google Pay Sample Code](/mobile-wallets/google-pay-hosted-checkout/sample-code). {% endhint %} **Step 4:** Create JavaScript function that will initialize iFields. ```javascript function initGP() { return { merchantInfo: gpRequest.merchantInfo, buttonOptions: gpRequest.buttonOptions, onGetTransactionInfo: "gpRequest.onGetTransactionInfo", environment: gpRequest.environment, billingParameters: gpRequest.billingParams, shippingParameters: { emailRequired: gpRequest.shippingParams.emailRequired, onGetShippingCosts: "gpRequest.shippingParams.onGetShippingCosts", onGetShippingOptions: "gpRequest.shippingParams.onGetShippingOptions" }, onBeforeProcessPayment: "gpRequest.onBeforeProcessPayment", onProcessPayment: "gpRequest.onProcessPayment", onPaymentCanceled: "gpRequest.onPaymentCanceled", onGPButtonLoaded: "gpButtonLoaded" }; } ``` Make sure that the iFrame attribute`data-ifields-oninit` has the name of this function. The initGP() function above returns [Google Pay Object.](/mobile-wallets/google-pay-hosted-checkout/request-objects#GooglePayRequest) #### Enable Google Pay **window\.ckGooglePay** **object** - controls initialization of Google Pay button. | **Method** | **Call Required** | **Description** | | ----------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `enableGooglePay` | Yes |

Initializes and enables Google Pay Button.
Takes EnableGooglePayParams object

| | `updateAmount` | Conditional | Updates amount on Google Sheet. | You can provide either All, One or None of the parameters for `enableGooglePay` call. * `amountField` specified - in this case, the Google Pay total amount will be automatically updated whenever the amount has changed. * `amountField` *is not* specified - in this case, it’s up to you to provide the correct amount for Google Pay. One of the ways to do it is to call `window.ckGooglePay.updateAmount` manually. * `iframeField` specified - this value will be used to communicate, with Google Pay button.\ This option is especially helpful for Angular clients using shadow DOM. * `iframeField` *is not* specified - its value will be calculated based on `data-ifields-id` attribute.\ In this case, it must be set to “igp“: `data-ifields-id="igp"`. #### **EnableGooglePayParams Object** | **Name** | **Type** | **Required** | **Description** | | ------------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `amountField` | String\|Object | No |

Field containing amount.
Could be either the name of the field (String) or the
field itself (Object)

Field containing iFrame with Google Pay button.
Could be either the name of the field (String) or the
field itself (Object)

| #### **Enable Google Pay example** `ckGooglePay.enableGooglePay({amountField: 'amount'});`
## Questions? Check out the Google Pay FAQ page [here](/mobile-wallets/google-pay-hosted-checkout/google-pay-faq). For additional questions, contact # Google Pay Control Object #### window\.ckGooglePay object - controls initialization of Google Pay button. | **Method** | **Call Required** | **Description** | | --------------- | ----------------- | --------------------------------------------------------------------------------------- | | enableGooglePay | Yes |

Initializes and enables Google Pay Button.
Takes EnableGooglePayParams object

| | updateAmount | Conditional | Updates amount on Google Sheet. | You can provide either All, One or None of the parameters for enableGooglePay call. * `amountField` specified - in this case Google Pay total amount will be automatically updated whenever amount has changed * `amountField` *is not* specified - in this case it’s up to you to provide the correct amount for Google Pay. One of the ways to do it is to call `window.ckGooglePay.updateAmount` manually. * `iframeField` specified - this value will be used to communicate with Google Pay button.\ This option is especially helpful for Angular clients using shadow DOM. * `iframeField` *is not* specified - it’s value will be calculated based on `data-ifields-id` attribute. In this case it must be set to “igp“: `data-ifields-id="igp"`. #### EnableGooglePayParams Object | **Name** | **Type** | **Required** | **Description** | | ----------- | -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | amountField | String\|Object | No |

Field containing amount.
Could be either name of the field (String) or
field itself (Object)

Field containing iframe with Google Pay button.
Could be either name of the field (String) or
field itself (Object)

| **Enable Google Pay example** ``` ckGooglePay.enableGooglePay({amountField: 'amount'}); ``` # Google Pay Request Objects #### *For complete sample code please refer* [*here*](/mobile-wallets/google-pay-hosted-checkout/sample-code) ## **Available dictionary objects** ### iStatus ``` const iStatus = { success: 100, unsupported: -100, error: -200 } ``` **Use:** `iStatus.success` ### GPEnvironment ``` const GPEnvironment = { test: "TEST", production: "PRODUCTION" } ``` **Use:** `GPEnvironment.test` ### GPButtonColor ``` const GPButtonColor = { default: "default", black: "black", white: "white" } ``` **Use:** `GPButtonColor.white` ### GPButtonType ``` const GPButtonType = { buy: "buy", donate: "donate", plain: "plain" } ``` **Use:** `GPButtonType.buy` ### GPButtonSizeMode ``` const GPButtonSizeMode = { static: "static", fill: "fill" } ``` **Use:** `GPButtonSizeMode.fill` ### GPBillingAddressFormat ``` const GPBillingAddressFormat = { min: "MIN", full: "FULL" } ``` **Use:** `GPBillingAddressFormat.min` ## **Request objects** ### GooglePayRequest The Main object that contains all the information necessary to communicate with Google Pay API. | **Name** | **Type** | **Required** | **Description** | | ------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchantInfo` | [*MerchantInfo*](/mobile-wallets/google-pay-hosted-checkout/request-objects#merchantinfo-object) | No | Describes the Merchant name and website. For more information please click the link | | `onGPButtonLoaded` | String | No |

Name of a callback function to be called when Google Pay button is loaded.
Accepts an object of type GPButtonLoadedResult.

Name of a callback function to be called that returns the final price and tax calculations.
Please click here for the sample code

Name of a callback function to be called when consumer clicked the button but before Google Pay sheet is loaded . Usually used to make validations before the payment.
Please click here for the sample code

Name of a callback function to be called when Google Payment is authorized for the completion of the transaction.
This function accepts a parameter of PaymentResponse.
Please click here for the sample code

Name of a callback function to be called when Google Pay sheet is closed/canceled without completing the transaction.
Please click here for the sample code

Google Pay Environment. Could be either “TEST“ or “PRODUCTION“.
If omitted, defaults to “TEST“

| | `billingParameters` | [BillingParameters](/mobile-wallets/google-pay-hosted-checkout/request-objects#billingparameters-object) | No |

Sets Billing parameters, including transactionId.
For more information please click the link

| | `shippingParameters` | [ShippingParameters](/mobile-wallets/google-pay-hosted-checkout/request-objects#shippingparameters-object) | No | Sets various Shipping Options. For more information please click the link | | `buttonOptions` | [ButtonOptions](/mobile-wallets/google-pay-hosted-checkout/request-objects#buttonoptions-object) | No |

Provides Google Pay button customization options.
For more information please click the link

| **Payment Request example** ``` initGP: function() { return { merchantInfo: this.merchantInfo, buttonOptions: this.buttonOptions, environment: this.getGPEnvironment(), billingParameters: this.billingParams, shippingParameters: { emailRequired: this.shippingParams.emailRequired, onGetShippingCosts: "gpRequest.shippingParams.onGetShippingCosts", onGetShippingOptions: "gpRequest.shippingParams.onGetShippingOptions" }, onGetTransactionInfo: "gpRequest.onGetTransactionInfo", onBeforeProcessPayment: "gpRequest.onBeforeProcessPayment", onProcessPayment: "gpRequest.onProcessPayment", onPaymentCanceled: "gpRequest.onPaymentCanceled", onGPButtonLoaded: "gpRequest.gpButtonLoaded" }; } ``` **onGPButtonLoaded example** ``` gpButtonLoaded: function(resp) { if (!resp) return; if (resp.status === iStatus.success) { showHide("divGpay", true); showHide("lbGPPayload", true); } else if (resp.reason) { alert(resp.reason); } } ``` **onGetTransactionInfo example** ``` onGetTransactionInfo: function () { let amt = this.getAmount(); return { displayItems: [ { label: "Subtotal", type: "SUBTOTAL", price: amt.toString(), }, { label: "Tax", type: "TAX", price: (0.1 * amt).toString(), } ], countryCode: 'US', currencyCode: "USD", totalPriceStatus: "FINAL", totalPrice: (1.1 * amt).toString(), totalPriceLabel: "Total" } } ``` **onBeforeProcessPayment callback example** ``` onBeforeProcessPayment: function () { return new Promise(function (resolve, reject) { try { //Do some validation here resolve(iStatus.success); } catch (err) { reject(err); } }); } ``` **onProcessPayment callback example** ``` onProcessPayment: function (paymentRequest) { let self = this; return new Promise(function (resolve, reject) { setTimeout(function () { try { console.log("paymentRequest", JSON.stringify(paymentRequest)); paymentToken = paymentRequest.paymentData.paymentMethodData.tokenizationData.token; console.log("paymentToken", paymentToken); const amt = (chained([paymentRequest, "transactionInfo", "totalPrice"]) && paymentRequest.transactionInfo.totalPrice) || 0; try { if (amt <= 0) throw "Payment is not authorized. Invalid amount. Amount must be greater than 0"; authorizeGPay({ token: paymentToken, amount: amt}) .then((resp) => { gpRequest.handleResponse(resp); resolve(resp); }) .catch((rej) => { console.error("Payment is not authorized", JSON.stringify(rej)); setTimeout(function () { alert("Payment is not authorized. Please check the logs") }, 500); reject(rej); }); } catch (err) { const emsg = JSON.stringify(err); console.error(emsg); setTimeout(function () { alert(emsg) }, 500); reject({error: err}); } } catch (e) { reject(e); } }, 100); //3000); }); } ``` **onPaymentCanceled callback example** ``` onPaymentCanceled: function(respCanceled) { setTimeout(function () { alert("Payment was canceled") }, 500); } ``` ### MerchantInfo Object | **Name** | **Type** | **Required** | **Description** | | -------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchantName` | String | Yes |

From Google documentation:
Merchant name encoded as UTF-8. Merchant name is rendered in the payment sheet. In TEST environment, or if a merchant isn't recognized, a “Pay Unverified Merchant” message is displayed in the payment sheet.

| **Merchant Info example** ``` merchantInfo: { merchantName: "Example Merchant" } ``` ### GPButtonLoadedResult Object | **Name** | **Type** | **Description** | | -------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | [iStatus](/mobile-wallets/google-pay-hosted-checkout/request-objects#iStatus) |

There are 3 possible cases:

Google Pay Button loaded successfully: status = iStatus.success
Google Pay not supported: status = iStatus.unsupported
An error occurred while loading Google Pay Button: status = iStatus.error

| | `reason` | String | If Google Pay Button failed to load this field will be populated with the reason. | ### BillingParameters Object | **Name** | **Type** | **Required** | **Description** | | -------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `transactionId` | String | No |

From Google documentation:
A unique ID that identifies a transaction attempt.
If not provided will be automatically generated by iFields API. Will be sent back on paymentRequest..transactionInfo response object.

If not provided will be defaulted to \["PAN\_ONLY", "CRYPTOGRAM\_3DS"]
From Google documentation:
Fields supported to authenticate a card transaction.

PAN\_ONLY: This authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with the expiration month and the expiration year.
CRYPTOGRAM\_3DS: This authentication method is associated with cards stored as Android device tokens. Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device.

If not provided will be defaulted to \["AMEX", "DISCOVER", "MASTERCARD", "VISA"]
From Google documentation:
One or more card networks that you support, also supported by the Google Pay API.

AMEX
DISCOVER
INTERAC
JCB
MASTERCARD
VISA

From Google documentation:
Set to true to request assuranceDetails. This object provides information about the validation performed on the returned payment data.

From Google documentation:
Set to true if you require a billing address. A billing address should only be requested if it's required to process the transaction.

| | `billingAddressFormat` | [GPBillingAddressFormat](/mobile-wallets/google-pay-hosted-checkout/request-objects#GPBillingAddressFormat) | No |

Has an effect when billingAddressRequired is set to true
From Google documentation:
Billing address format required to complete the transaction.

MIN: Name, country code, and postal code (default).
FULL: Name, street address, locality, region, country code, and postal code.

Has an effect when billingAddressRequired is set to true
From Google documentation:
Set to true if a phone number is required to process the transaction.

| **Billing Parameters example** ``` billingParameters: { transactionId: "b65c7435-b57a-407e-a6e0-b166518d5d97", allowedAuthMethods: ["PAN_ONLY"], allowedCardNetworks: ["VISA", "MASTERCARD"], emailRequired: true billingAddressRequired: true, billingAddressFormat: GPBillingAddressFormat.min, phoneNumberRequired: true } ``` ### ShippingParameters Object | **Name** | **Type** | **Required** | **Description** | | ------------------------- | --------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onGetShippingOptions` | String | No |

When shipping is required you need to provide the name of your function that returns a list of shipping options.
For an example - please see below

When shipping is required you need to provide the name of your function that returns a list of shipping costs.
For an example - please see below

From Google documentation:
Set to true to request a full shipping address..

From Google documentation:
Set to true to request an email address.

From Google documentation:
Set to true if a phone number is required for the provided shipping address.

From Google documentation:
ISO 3166-1 alpha-2 country code values of the countries where shipping is allowed. If this object isn't specified, will be defaulted to US only.

| **Shipping Parameters example** ``` shippingParams: { allowedCountryCodes: ['US'], onGetShippingCosts: function (shippingData) { logDebug({ label: "onGetShippingCosts", data: shippingData }); return { "shipping-001": "0.00", "shipping-002": "1.99", "shipping-003": "10.00" } }, onGetShippingOptions: function (shippingData) { logDebug({ label: "onGetShippingOptions", data: shippingData }); let selectedOptionid = "shipping-001"; if (shippingData && shippingData.shippingOptionData && shippingData.shippingOptionData.id !== "shipping_option_unselected") { selectedOptionid = shippingData.shippingOptionData.id; } return { defaultSelectedOptionId: selectedOptionid, shippingOptions: [ { "id": "shipping-001", "label": "Free: Standard shipping", "description": "Free Shipping delivered in 5 business days." }, { "id": "shipping-002", "label": "$1.99: Standard shipping", "description": "Standard shipping delivered in 3 business days." }, { "id": "shipping-003", "label": "$10: Express shipping", "description": "Express shipping delivered in 1 business day." }, ] }; } } ``` ### ShippingData Object | **Name** | **Type** | **Description** | | -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | `shippingAddress` | [ShippingAddress](#shippingaddress-object) | An Address containing `countryCode`, `postalCode`, `locality`(city), `administrativeArea`(state). | | `shippingOptionData` | [ShippingOptionData](#shippingoptiondata-object) | An object containing a selected option | **ShippingData object example** ``` { "shippingAddress": { "countryCode": "US", "postalCode": "10601", "locality": "White Plains", "administrativeArea": "NY" }, "shippingOptionData": { "id": "shipping-001" } } ``` ### ShippingAddress Object | **Name** | **Type** | **Description** | | -------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `postalCode` | String |

From Google documentation:
The postal or ZIP code.

| | `countryCode` | String |

From Google documentation:
ISO 3166-1 alpha-2 country code.

| | `locality` | String |

From Google documentation:
City, town, neighborhood, or suburb.

| | `administrativeArea` | String |

From Google documentation:
A country subdivision, such as a state or province.

| ### ShippingOptionData Object | **Name** | **Type** | **Description** | | -------- | -------- | ------------------------------ | | `id` | String | id of selected shipping option | ### ButtonOptions Object | **Name** | **Type** | **Required** | **Description** | | ---------------- | ----------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buttonColor` | [GPButtonColor](/mobile-wallets/google-pay-hosted-checkout/request-objects#GPButtonColor) | No |

From Google documentation:

default: A Google-selected default value. Currently black but it may change over time (default).
black: A black button suitable for use on white or light backgrounds.
white: A white button suitable for use on colorful backgrounds.

From Google documentation:

buy: "Buy with Google Pay" button (default).
donate: "Donate with Google Pay" button.
plain: Google Pay button without additional text.

From Google documentation:

static: Button has a static width and height (default).
fill: Button size changes to fill the size of its container.

| **Button Options example** ``` buttonOptions: { buttonColor: GPButtonColor.white, buttonType: GPButtonType.buy, buttonSizeMode: GPButtonSizeMode.full } ``` # Google Pay Response Objects #### *For complete sample code please refer* [*here*](/mobile-wallets/google-pay-hosted-checkout/sample-code) ## Available Response Objects ### PaymentResponse Object This Object contains Google Pay response. | **Name** | **Type** | **Always exists** | **Description** | | ----------------- | ------------------------------------------ | ----------------- | ---------------------------------------------------------------------------------- | | `transactionInfo` | [TransactionInfo](#transactioninfo-object) | Yes | Contains all transaction data. For more details please click on the link | | `paymentData` | [PaymentData](#paymentdata-object) | Yes | This is a response object that's returned by Google after a payer approves payment | ### TransactionInfo Object | **Name** | **Type** | **Always exists** | **Description** | | ------------------ | ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `displayItems` | DisplayItem | Yes | Array of line items describing the charge. For more details please click on the link | | `countryCode` | String | Yes | ISO 3166-1 alpha-2 country code | | `currencyCode` | String | Yes | ISO 4217 alphabetic currency code. | | `totalPriceStatus` | String | Yes | Set to `FINAL` | | `totalPrice` | String | Yes | Total amount consumer should be charged. This is a sum of all DisplayItems | | `transactionId` | String | Yes | A unique ID that identifies a transaction attempt. Can be passed on the Request through [billingParameters](/mobile-wallets/google-pay-hosted-checkout/request-objects#BillingParameters-Object) | ### DisplayItem Object | **Name** | **Type** | **Always exists** | **Description** | | -------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | String | Yes |

From Google documentation:
The label to be displayed for the given option

From Google documentation:
Type of displayed line item:

LINE\_ITEM
SUBTOTAL

From Google documentation:
The monetary value of the cart item with an optional decimal precision of two decimal places. Negative values are allowed.

From Google documentation:
The following variables define price variance:

FINAL
PENDING

Default to FINAL if not provided

| #### **TransactionInfo example** ``` "transactionInfo": { "displayItems": [ { "label": "Subtotal", "type": "SUBTOTAL", "price": "2" }, { "label": "Tax", "type": "TAX", "price": "0.2" }, { "type": "LINE_ITEM", "label": "Shipping cost", "price": "0.00", "status": "FINAL" } ], "countryCode": "US", "currencyCode": "USD", "totalPriceStatus": "FINAL", "totalPrice": "2.2", "totalPriceLabel": "Total", "transactionId": "1200640e-5ed3-45d3-870b-5491d5af8248" } ``` ### PaymentData Object | **Name** | **Type** | **Always exists** | **Description** | | -------------------- | -------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | | `apiVersion` | Number | Yes |

From Google documentation:
Major API version

From Google documentation:
Minor API version

From Google documentation:
Data about the selected payment method

From Google documentation:
The selected shipping option in the payment sheet.

| | `shippingAddress` | [Address](#address-object) | No | Shipping address, if `shippingAddressRequired` is set to `true` in the request | ### SelectionOptionData Object | **Name** | **Type** | **Always exists** | **Description** | | -------- | -------- | ----------------- | ---------------------------------- | | `id` | String | Yes | Id of the selected Shipping Option | ### PaymentMethodData Object | **Name** | **Type** | **Always exists** | **Description** | | ------------------ | ---------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `description` | String | Yes |

From Google documentation:
User-facing message to describe the payment method that funds this transaction.

From Google documentation:
Data about the selected payment method

From Google documentation:
Payment tokenization data for the selected payment method.

| | `type` | String | Yes | Will be always set to `CARD` | ### CardInfo Object | **Name** | **Type** | **Always exists** | **Description** | | ------------------ | ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cardNetwork` | String | Yes |

From Google documentation:
The payment card network of the selected payment.

From Google documentation:
The details about the card. This value is commonly the last four digits of the selected payment account number.

From Google documentation:
This object provides information about the validation performed on the returned payment data if assuranceDetailsRequired is set to true on the request.

From Google documentation:
The billing address associated with the provided payment method, if billingAddressRequired is set to true in the request

| ### PaymentMethodTokenizationData Object | **Name** | **Type** | **Always exists** | **Description** | | -------- | -------- | ----------------- | ---------------------------------------------------------------------- | | `type` | String | Yes | Will be always set to `PAYMENT_GATEWAY` | | `token` | String | No | A JSON object string that contains a chargeable token issued by Google | #### PaymentData Example ``` { "apiVersion": 2, "apiVersionMinor": 0, "paymentMethodData": { "type": "CARD", "description": "Visa •••• 1234", "info": { "cardNetwork": "VISA", "cardDetails": "1234" }, "tokenizationData": { "type": "PAYMENT_GATEWAY", "token": "examplePaymentMethodToken" } } } ``` ### Address Object | **Name** | **Address format** | **Description** | | -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | MIN |

From Google documentation:
The full name of the addressee.

| | `postalCode` | MIN |

From Google documentation:
The postal or ZIP code.

| | `countryCode` | MIN |

From Google documentation:
ISO 3166-1 alpha-2 country code.

| | `phoneNumber` | MIN |

From Google documentation:
A telephone number, if phoneNumberRequired is set to true in the request

| | `address1` | FULL |

From Google documentation:
The first line of the address.

| | `address2` | FULL |

From Google documentation:
The second line of the address.

| | `address3` | FULL |

From Google documentation:
The third line of the address.

| | `locality` | FULL |

From Google documentation:
City, town, neighborhood, or suburb.

| | `administrativeArea` | FULL |

From Google documentation:
A country subdivision, such as a state or province.

| | `sortingCode` | FULL |

From Google documentation:
The sorting code.

| #### Address Example ```json { "name": "John Doe", "address1": "c/o Google LLC", "address2": "1600 Amphitheatre Pkwy", "address3": "Building 40", "locality": "Mountain View", "administrativeArea": "CA", "countryCode": "US", "postalCode": "94043", "sortingCode": "" } ``` ### Full Response Object ```json { "transactionInfo": { "displayItems": [ { "label": "Subtotal", "type": "SUBTOTAL", "price": "2" }, { "label": "Tax", "type": "TAX", "price": "0.2" }, { "type": "LINE_ITEM", "label": "Shipping cost", "price": "0.00", "status": "FINAL" } ], "countryCode": "US", "currencyCode": "USD", "totalPriceStatus": "FINAL", "totalPrice": "2.2", "totalPriceLabel": "Total", "transactionId": "aff9e1-3209-4b2c-8037-120d2c0d" }, "paymentData": { "apiVersionMinor": 0, "apiVersion": 2, "paymentMethodData": { "description": "Mastercard •••• 1771", "tokenizationData": { "type": "PAYMENT_GATEWAY", "token": "{\"signature\":\"MEUCI+slJGaKBHZmphgIgJ8GKHlrPKnQcObF/lGfYjDmt1pu3kzPOYoBmdjdUFvw\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQca0NVUE0gp/9xbueVNmy1o+NTcInbX/9ZN0QbXr8mng\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1614913712991\\\"}\",\"signatures\":[\"MEUCIQDb6d5nYqcL57Q09DPDrDKWxMgIgKaiLAEfdwNwG7S6nMvX1gRvQ\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"9gmVUfk1Jua03felBqSUY4yXwzDzlhSHE2jm4VHDgsQ3xnzjQrlTAiyM87dP+8Cx9cks6SbrrK6vyWR7WmrPFhOaNFlulCvn9fI213ofHjRz7ebP71IFRCpgjeqG+nMQJXY8zjkhwXkUJTtOJ4SpXV7ByLyIXb/UJU7pg3O1m3Tl1zpe8C+hLQpKvAIZSAwEl4EBRafbcE33JyuV7RNLMlAerlELsGPUm0c04mM11vF3vdBVfgiyvVw5pJD2Gk/DX7fHdrUpPnzRt5ZoFU0jWZq/8rsj57cEzR+MK2MJVZE014D7iB8+7qcFjJ5H6Tdc/DCsyO5XDVp3Lu5aWZrIqJ6b9BkNPGiCDrV1OKRngc4OYPIGj7OrP7nQgIeU97EYT2xLzqWnfZ/PNCtj89mvT9mKp8y7V6eCJmK8BJsH9MLH08olwGo9pcU7Av2OXo837qUkcCxrkDrYh+wSbqS4p1SyoqgW+2BR+2zRoXU/\\\",\\\"ephemeralPublicKey\\\":\\\"BAAqw+C7aP+Z6KL2HLiP5J7Y/gEWpLQedowh7+r/7taxfNbNuC4\\\\u003d\\\",\\\"tag\\\":\\\"jkqoAh5l16mzlpmqVzpFx/k64\\\\u003d\\\"}\"}" }, "type": "CARD", "info": { "cardNetwork": "MASTERCARD", "cardDetails": "1771", "billingAddress": { "address3": "", "sortingCode": "", "address2": "", "countryCode": "US", "address1": "123 Main Street", "postalCode": "07103", "name": "John Smith", "locality": "Newark", "administrativeArea": "NJ" } } }, "shippingOptionData": { "id": "shipping-001" }, "shippingAddress": { "address3": "", "sortingCode": "", "address2": "", "countryCode": "US", "address1": "123 Main Street", "postalCode": "10601", "name": "Test Test", "locality": "White Plains", "administrativeArea": "NY" }, "email": "jsmith1234@abc.com" } } ``` # Google Pay Sample Code 1. **Let's define a helper object with all necessary components:** ```javascript window.gpRequest = { environment: GPEnvironment.test, merchantInfo: { merchantName: "Example Merchant" }, buttonOptions: { buttonSizeMode: GPButtonSizeMode.fill }, billingParams: { billingAddressRequired: true, billingAddressFormat: GPBillingAddressFormat.full }, shippingParams: { emailRequired: true, onGetShippingCosts: function (shippingData) { logDebug({ label: "onGetShippingCosts", data: shippingData }); return { "shipping-001": "0.00", "shipping-002": "1.99", "shipping-003": "10.00" } }, onGetShippingOptions: function (shippingData) { logDebug({ label: "onGetShippingOptions", data: shippingData }); let selectedOptionid = "shipping-001"; if (shippingData && shippingData.shippingOptionData && shippingData.shippingOptionData.id !== "shipping_option_unselected") { selectedOptionid = shippingData.shippingOptionData.id; } return { defaultSelectedOptionId: selectedOptionid, shippingOptions: [ { "id": "shipping-001", "label": "Free: Standard shipping", "description": "Free Shipping delivered in 5 business days." }, { "id": "shipping-002", "label": "$1.99: Standard shipping", "description": "Standard shipping delivered in 3 business days." }, { "id": "shipping-003", "label": "$10: Express shipping", "description": "Express shipping delivered in 1 business day." }, ] }; } }, onGetTransactionInfo: function () { let amt = getAmount(); return { displayItems: [ { label: "Subtotal", type: "SUBTOTAL", price: amt.toString(), }, { label: "Tax", type: "TAX", price: (0.1 * amt).toString(), } ], countryCode: 'US', currencyCode: "USD", totalPriceStatus: "FINAL", totalPrice: (1.1 * amt).toString(), totalPriceLabel: "Total" } }, onBeforeProcessPayment: function () { return new Promise(function (resolve, reject) { try { //Do some validation here resolve(iStatus.success); } catch (err) { reject(err); } }); }, onProcessPayment: function (paymentResponse) { return new Promise(function (resolve, reject) { try { // show returned data in developer console for debugging console.log("paymentResponse", JSON.stringify(paymentResponse)); paymentToken = paymentResponse.paymentData.paymentMethodData.tokenizationData.token; console.log("paymentToken", paymentToken); const amt = (paymentResponse && paymentResponse.transactionInfo && paymentResponse.transactionInfo.totalPrice) || 0; try { if (amt <= 0) { throw "Payment is not authorized. Invalid amount. Amount must be greater than 0"; } authorizeGPay(paymentResponse) .then((resp) => { gpRequest.handleResponse(resp); setGPPayload(JSON.stringify(paymentResponse, null, 2)); resolve(resp); }) .catch((rej) => { console.error("Payment is not authorized", JSON.stringify(rej)); setGPPayload(""); setTimeout(function () { alert("Payment is not authorized. Please check the logs") }, 500); reject(rej); }); } catch (err) { const emsg = JSON.stringify(err); console.error(emsg); setTimeout(function () { alert(emsg) }, 500); reject({error: err}); } } catch (err) { reject(err); } }); }, onPaymentCanceled: function(respCanceled) { setTimeout(function () { alert("Payment was canceled") }, 500); }, handleResponse: function (resp) { const respObj = JSON.parse(resp); if (respObj) { if (respObj.xError) { setTimeout(function () { alert(`There was a problem with your order (${respObj.xRefNum})!`) }, 500); } else setTimeout(function () { alert(`Thank you for your order (${respObj.xRefNum})!`) }, 500); } }, }; ``` 2. **Object with necessary properties to initialize Google Pay:** ```javascript function initGP() { return { merchantInfo: gpRequest.merchantInfo, buttonOptions: gpRequest.buttonOptions, onGetTransactionInfo: "gpRequest.onGetTransactionInfo", environment: gpRequest.environment, billingParameters: gpRequest.billingParams, shippingParameters: { emailRequired: gpRequest.shippingParams.emailRequired, onGetShippingCosts: "gpRequest.shippingParams.onGetShippingCosts", onGetShippingOptions: "gpRequest.shippingParams.onGetShippingOptions" }, onBeforeProcessPayment: "gpRequest.onBeforeProcessPayment", onProcessPayment: "gpRequest.onProcessPayment", onPaymentCanceled: "gpRequest.onPaymentCanceled", onGPButtonLoaded: "gpButtonLoaded" }; } ``` For more information please refer to [Request](/mobile-wallets/google-pay-hosted-checkout/request-objects) object
3. **Google Pay iField:** ```html ``` 4. **Let’s enable Google Pay for the website:** ```javascript document.addEventListener("DOMContentLoaded", function(event) { ..... ckGooglePay.enableGooglePay({amountField: 'amount'}); ..... } ``` For more information please refer to [Google Pay Control Object](/mobile-wallets/google-pay-hosted-checkout/google-pay-control-object)
5. To see the full solution please click [**here**](/mobile-wallets/google-pay-hosted-checkout/ifields-integration)**.** # iFields Integration The code below is a source of ifield-sample.htm ```html ``` # Google Pay FAQ #### **Q:** Can I run Test transactions with Google Pay? **A:** Yes, just follow these steps: 1. Setup your Google Pay Wallet with your real card 2. Point Google Pay to Test Environment (in your init Google Pay function set `environment` to `GPEnvironment.test`) 3. Let Sola representative know that you want to use Google Pay Test environment for your Sandbox account. Your real card won’t be charged, the transaction will run against test Visa card 4111…1111. #### **Q:** What’s the maximum allowed amount for the Test transaction **A:** The maximum amount for test transaction allowed by Sola is $10 # Netsuite ## Overview The Sola bundle for NetSuite is an easy integration that allows users to accept payments via the Sola gateway directly within NetSuite. This plugin also supports the secure storage of customer payment methods for future transactions. {% hint style="info" %} **Note:** Only NetSuite administrators can install this bundle. {% endhint %} ### Bundle Components ![](/files/-Me03xVef7qbIVGZtxqC) ## Install the Bundle ### Prerequisites: * An existing Sola account (live or sandbox) with a token and transaction key. * Provide Sola with your NetSuite ID by emailing it to . We will enable the bundle for your NetSuite ID and enable the license for NetSuite on your Sola account. ### Installation: 1. Navigate to Customization > Suite Bundler > Search & Install Bundles. 2. Search and install the ‘xPayment’ bundle (you can also install ‘xPayment Beta’ for additional features). ### Setup #### **Configure Account Settings:** 1. Navigate to Setup > Company > PE Merchant Account to create a new PE merchant account record. * **Name**: Name of the merchant account. * **PE Transaction Key:** API key. * **PE Token Key:** iFields key * **PE Void When Canceled:** Voids the Sola transaction if a NetSuite transaction is voided. * **PE Accept ACH:** Accept ACH payments with Sola.\ Note: The merchant account needs to be set up for ACH as well. * **PE Allow Undeposited Funds:** This allows the system to accept a payment in the Undeposited Funds account. Note: Make sure to change all credit card types to ‘Group with Undeposited Funds’ (Setup > Accounting > Accounting Lists > Card Type > Edit > Account Tab > Group with Undeposited Funds). * **PE Void Transaction When Declined:** Automatically void the NetSuite transaction If a Sola transaction gets declined or fails. Note: Only use this setting if the 'PE Require Charge Button' setting is unchecked. * **PE Require Charge Button Transaction:** does not process if the 'PE PROCESS TRANSACTION' button was not selected. Note: This does not apply to sales orders or transactions in edit mode. * **PE Send Record Type ID:** Send the record type and ID of the record along with transaction to the gateway as the 'xCustom01' field. * **PE Description Field ID:** NetSuite Field ID to send along with the transaction to the gateway as the ‘xDescription’ field. If this field is empty, or the field is not found on the form that submits the transaction, the system does not send a description as part of the transaction. 2. Navigate to Setup > Accounting > Accounting preferences * **Void Transactions Using Reversing Journals:** Enable this setting. #### Form Setup Add the “PE” fields to the forms that accept payments (cash sale, cash refund, customer deposit, customer payment, customer refund, sales order). Make sure to hide the NetSuite fields that the plugin is replacing. | Name | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | PE Stored Credit Card | The payment method saved with the customer. | | PE Credit Card Number | The credit card number. | | PE CVV Code | The security code of the credit card. | | PE Account Number | The ACH account number (only needed if ACH is enabled). | | PE Routing Number | The ACH routing number (only needed if ACH is enabled). | | PE Get Authorization | Perform an Authorize Only transaction (only needed by sales order). | | PE Retry Transaction | Try charging the card again. | | PE Merchant Account | The name of the merchant account that should be used. It defaults to the first merchant account created. | | PE Charge Card | The button that the merchant needs to select for the transaction to process. It should be renamed on the refund form to **PE Refund Card**. | **Step 3: Upload Existing Customer Card**\ Use a regular .CSV upload and map the fields to PE Stored Credit Card. **Step 4: Use a Card Reader**\ To use the card reader, select the **PE Credit Card Number** field, then swipe or insert the card to populate the field with the card data. **Step 5: Test the Installation**\ From Sola, request a sandbox account with a token and transaction key. Follow the installation steps above to perform the setup. What to Test: * Approved transaction * Declined transaction * Ensure that all scripts are running by creating a transaction and adding a stored payment. * Verify that the Sola log shows the transaction history. * Make sure that other users in NetSuite have access to the bundle and that the scripts run. NetSuite recommends that administrators installing a bundle test that bundle using a NetSuite sandbox account. ### Use the Bundle **Roles and Permissions** Make sure the roles using this plugin have permission for the following: * Transaction Logs: Saved Search and Audience (Roles and Employees) need to be set for all users using this bundle (Transaction logs > Edit > Audience). * Accounting lists need at least View rights (Role > Permissions > Setup > Accounting lists ). * Customers need at least View rights (Role > Permissions > Lists > Customers). * PE Merchant Account needs at least View rights (Role > Permissions > Custom Record). * PE Payment Logs need at least Create rights (Role > Permissions > Custom Record). * PE Stored Credit Card needs Edit rights (Role > Permissions > Custom Record). **User Procedures** Add a Stored Card to a Customer 1. In the customer record, select Financials > PE Stored Card. 2. Select the new **PE Stored Card** button. You can also add a new card to a transaction screen that has the **PE Stored Card** field. Check the plus symbol (+) to add a new card. ### Miscellaneous **How the Plugin Pulls Customer Billing and Shipping Values** The plugin retrieves customer billing and shipping values from various locations in a specific order of preference. The order is as follows: 1. From the current record itself. If the Bill To or Ship To values are set, they are used. (Exception: a customer payment with a single applied invoice. See Note below.) * If the current record doesn’t have the Bill To or Ship To values set, then the plugin pulls the values from the parent record (if one exists). * If no parent record exists, or the parent record does not have the values set, the plugin pulls the values from the address list on the customer record: 1. The default billing and shipping addresses are used if they are set. 2. If the defaults are not set, the first address is used. **Note:** For customer payments with a single applied invoice, the plugin pulls the values from the applied invoice first. If the values are not set on the applied invoice (or if multiple invoices are applied), the plugin pulls the values from the address list on the customer record. ### Update the Bundle Use SuiteBundler to update when a new version is available. SuiteBundler capabilities may change over time; verify the current SuiteBundler features as described in the NetSuite Help Center topic, Updating Bundles in the Bundle Repository. ### Uninstall the Bundle Use SuiteBundler to uninstall the bundle completely. Note that this completely removes all history of Sola payments. Uninstalling this bundle should generally follow the steps provided in the NetSuite Help Center topic, Uninstalling Bundles into Your NetSuite Account. The SuiteBundler capabilities may change over time; review this help topic to verify the current behavior of uninstalling bundles. # NetSuite Features and Demo ## Overview Our plugin is a NetSuite bundle that lets you use the Sola gateway to accept integrated payments with NetSuite. It also allows you to securely store payment methods for future transactions. Sola currently does not support the following NetSuite integrations: * SCA (NS eComm shopping cart) * SCIS (NS Retail) ### Prerequisites 1. Create an account with Sola (live or sandbox). 2. Obtain your token and transaction key. 3. Request a NetSuite license (create a sandbox account [here](https://solapayments.com/devsdk/)). 4. Provide Sola with your NetSuite ID (). Sola will share the bundle with you. ## Installation **Note:** Only NetSuite administrators can install this bundle. Find and install the “xPayment” (and xPayment beta) bundle in the “Search & Install Bundles“ section. The following video demonstrates these steps: ## FAQs **Q: How do I add credit card information and save it?** A: To store a customer’s credit card with their record: 1. Open the customer record and click the Transactions tab. 2. In the Payments section, click the plus sign ( + ) next to the **PE Store Payment** field. 3. On the PE Stored Payment pop-up, fill in the required fields. 4. Click the **Save** button on the pop-up to save and close the pop-up. 5. Select the **PE Get Authorization** checkbox. 6. Click the **Save** button at the bottom of the screen. The following video demonstrates these steps: **Q: How do I perform a sales order (PreAuth/AuthOnly/Capture)?** A: To process a sales order: 1. Open the customer record and click the Transactions tab. 2. In the Items section, add as many items as necessary. 3. In the Payment section, type in the credit card information. 4. Select the **PE Get Authorization** checkbox. 5. Click the **Save** button. At the top of the screen, the system displays a message that confirms the transaction was saved. Below this is the message "Pending Approval." 6. Click the **Approve** button. The system displays the message "Pending Fulfillment." 7. Click the **Fulfill** button. The system displays the Item Fulfillment screen. 8. Under the text "To Be Generated," click the **Save** button. At the top of the screen, the system displays a message that confirms the transaction was saved. 9. Click the **Bill** button. The system displays the Cash Sale screen. 10. Under the text "To Be Generated," click the **Save** button. The following video demonstrates these steps: **Q: How do I process a cash sale?** A: To process a cash transaction: 1. Open the customer record and click the Transactions tab. 2. In the Items section, add as many items as necessary. 3. In the Billing section, enter information in the following fields\ \- **Payment Method**\ \- **Expires**\ \- **Name on Card** 4. Type the card number into the **PE Credit Card Number** field. 5. Click the **Save** button. The following video demonstrates these steps: **Q: How do I process a cash refund?** A: Open the cash refund transaction that needs to be refunded. In the upper left of the screen, click the **Refund** button. The following video demonstrates this step: **Q: How do I process a customer deposit?** A: To process a customer deposit: 1. Open the Customer Deposit screen. 2. In the **Customer** field, choose the customer. 3. Type in an amount in the **Payment Amount** field. 4. In the **PE Stored Payment** field, select the payment method. 5. Click the **Save** button. At the top of the screen, the system displays a message that confirms the transaction was saved. The following video demonstrates these steps: **Q: How do I process a customer payment?** A: To process a customer payment for an invoice: 1. Open the invoice for which you will accept payment. 2. Click the Accept button. NetSuite opens the Payment screen. 3. Scroll down to the Payment Method section. 4. In the **PE Payment Method** field, select the payment method. 5. Click the **Save** button. At the top of the screen, the system displays a message that confirms the transaction was saved. The following video demonstrates these steps: {% file src="/files/-MbwDrfRNgOtAlkf61q0" %} Customer Payment Video {% endfile %} # WooCommerce ## Overview Our WooCommerce plugin is an easy integration that allows users to accept payments online through their WooCommerce online site. ## Installing the Plugin Our official WooCommerce plugin can be found here: After installing and activating the plugin, navigate to the plugin settings and enter your API Key and iFields Key. There are several additional optional settings available. You can hover over each setting to view a brief description of its functionality.
If you plan to enable **Apple Pay** or **Google Pay**, please ensure that your checkout page uses the shortcode `[woocommerce_checkout]` rather than the block-based checkout.
Before activating the Sola plugin, please deactivate any other payment methods or processors to avoid conflicts. {% hint style="info" %} Please note that after installation, the plugin may still appear in your plugin list under our former name, Cardknox. {% endhint %} ## Customer Usage ### New transaction: 1. Go to the checkout page. 2. Select Credit Card (or the title that was specified for Sola in the settings page). ### New card: 1. Select "use a new payment method." 2. Enter the card data. 3. Select "save to account" if you would like to save the card for future use. ### Card on file: 1. Select the card you would like to use. 2. Select "place order." ### Add payment method (card on file): 1. Select my account > payment methods. 2. Click "add payment method." 3. Enter card data. 4. Click "add payment method." Add payment method image: ![](/files/-Me-pXZS0s-9xvkkaaFd) ### Delete payment method: 1. Select my account > payment methods. 2. Click "delete" on the right of the payment method. Delete payment method: ![](/files/-Me01n3YlX5-m15n9ReF) ### New subscription: 1. Select subscription item. 2. Pay the same as with a regular transaction. ### Change subscription: 1. Go to my account > select subscriptions. 2. Click "view" on the subscription. 3. Apply modifications. Edit subscription image: ![](/files/-Me01sJ4JSE6mCJZi5h6) ## Merchant ### Refund a transaction: This will refund the transaction. You can specify the amount to refund.\ Refund images: ![](/files/-Me01x8_HYnFdJSZDdil) ### Change order status from on hold to processing: If the plugin is set to not capture the transaction, this will capture the transaction. ### Change order status from on hold to completed: If the plugin is set to not capture the transaction, this will capture the transaction. ### Change order status from on hold to canceled: If the order is not yet captured, this will void the auth only transaction. ### Change order status from on hold to refunded: If the order is not yet captured, this will void the auth only transaction. Change order status image: ![](/files/-Me02_zfHZxjq85HiL8o) ### Recurring / Subscriptions: **Process Renewal:**\ Charge the subscription instead of waiting. **Add / Update Token Manually:**\ Click on the pencil near "payment details." Update the token masked card number and card type. # Magento Plugin The Magento Sola plugin will allow you to charge credit cards via the Sola gateway. Sola enables credit card payments for both customers on the storefront and for merchants in the Admin portal. The plugin supports Authorize Only, Capture, Void, Cancel, and Refund transactions. As a merchant, your web servers remain out of scope of the transaction, keeping card data secure and simplifying PCI compliance. ## Installation #### **Install the plugin** Install the plugin from . #### Install the Sola Plugin To install the Sola plugin: 1. Unzip the folder to app/code/CardknoxDevelopment/Cardknox (create the directories if needed) 2. Run the below commands in the Magento root directory (bash). {% hint style="info" %} If you are using versions 2.0 – 2.1, contact cardknox for a compatible version. For 2.1.0 - 2.1.3, comment out lines 278 – 282 in Cardknox/etc/di.xml. On higher versions, no changes are needed. {% endhint %} **Enable the module** ``` php bin/magento module:enable CardknoxDevelopment_Cardknox --clear-static-content php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy ``` **Optionally flush the cache** ``` php bin/magento cache:clean php bin/magento cache:flush ``` ## Setup Navigate to Stores > Configuration > Payment Methods > Sola which will bring you to the configuration page (see below). ## Configuration Options | **Item** | **Description** | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Enabled | This enables the Sola / Cardknox Module. Set to ‘Yes’ to enable Sola payments. | | Title | Name of payment method. This will appear to users when selecting a payment method. We recommend selecting ‘Credit Card.’ | | Vault Enabled | This enables the customer to save cards for later use on the site. | | Vault Title | Name of vault payment method. This will appear to users when selecting a card on file. We recommend selecting ‘Stored Cards.’ | | Sola Transaction Key | Your Sola API transaction Key. | | Sola Token Key | Your Sola token key (iFields key). | | Debug | Logs transaction data for troubleshooting purposes. | | Payment Action | Sets the transaction payment mode. If ‘Authorize’ is selected, all transactions will need to be captured when invoicing an order. | | Enable Split Capture For Credit Card | When Payment action is set to Authorize, this will allow you to [split capture](https://docs.cardknox.com/cardknox-products/split-capture) when capturing (invoicing) a transaction. | | Payment from Applicable Countries | Select ‘Specific Countries’ to only allow payment from the ‘Payment From Specific Countries’ whitelist. | | Payment from Specific Countries | Select countries you wish to whitelist. | | Sola Gateway Endpoint | Sola URL to which transactions are routed (this setting should not be modified unless advised to do so by Sola Support). | | Google reCAPTCHA V2 Enable | This enables Google reCAPTCHA V2 | | Google API Key V2 | Your Google reCaptcha Site Key V2 | | Google API Secret Key V2 | Your Google reCaptcha Secret key V2 | | Sort Order | Priority of Sola in list of payment methods. | {% hint style="info" %} If you do not have a key, you can obtain it by signing into your account in the Sola portal and navigating to Key Management. {% endhint %} ## Sola Google Pay | **Item** | **Description** | | -------- | --------------- | | **Item** | **Description** | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Enabled |

This enables Sola Google Pay . Set to ‘Yes’ to enable Google Pay. Please ensure that your Sola account is configured for Google Pay.
Please contact Sola support to confirm

| | Title | Name of payment method. This will appear to users when selecting a payment method. We recommend selecting ‘Google Pay’ | | Merchant Name | Enter the merchant name (DBA) | | Environment | Sets the Google Pay environment. This must match the environment set on the Sola account. Please contact [Sola support](mailto:gatewaysupport@solapayments.com) to confirm | | GooglePay Payment Action | Sets the transaction payment mode. If ‘Authorize’ is selected, all transactions will need to be captured when invoicing an order. | | Enable Split Capture For GooglePay | When Payment action is set to Authorize, this will allow you to [split capture](https://docs.cardknox.com/cardknox-products/split-capture) when capturing (invoicing) a transaction. | | Button Style | This sets the Google Pay button style | | Payment from Applicable Countries | Select ‘Specific Countries’ to only allow payment from the ‘Payment From Specific Countries’ whitelist. | | Payment from Specific Countries | Select countries you wish to whitelist. | | Sort Order | Priority of Google Pay in list of payment methods. | ## Sola Apple Pay {% hint style="info" %} Please complete the Apple Pay Domain Registration [here ](https://portal.solapayments.com/account-settings/payment-methods)prior to enabling Cardknox Apple Pay {% endhint %} | **Item** | **Description** | | -------- | --------------- | | **Item** | **Description** | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enabled |

This enables Sola Apple Pay. Set to ‘Yes’ to enable Apple Pay. Please ensure that your Sola account is configured for Apple Pay.
Please contact Sola support to confirm

| | Title | Name of payment method. This will appear to users when selecting a payment method. We recommend selecting ‘Apple Pay’ | | Merchant Identifier | The default value is merchant.cardknox.com | | Environment | Sets the Apple Pay environment. | | Apple Pay Button Style | This sets the Apple Pay button style | | Apple Pay Button Style | This sets the Apple Pay button style | | Payment Action | Sets the transaction payment mode. If ‘Authorize’ is selected, all transactions will need to be captured when invoicing an order. | | Payment from Applicable Countries | Select ‘Specific Countries’ to only allow payment from the ‘Payment From Specific Countries’ whitelist. | | Payment from Specific Countries | Select countries you wish to whitelist. | | Sort Order | Priority of Apple Pay in list of payment methods | ## Usage ### New Order Select Credit Card as the payment method in the Payment & Shipping Information section (see Title in the Configuration Options section of this document). ### Capture If ‘Authorize’ is selected as the Payment Action in the Sola module settings (see Payment Actions in the Configuration Options section of this page), select ‘Capture Online’ to capture the transaction before submitting the invoice. Please note that previously voided transactions cannot be captured and will result in an error. ### Void Use ‘Void’ to cancel transactions on orders that have not yet been invoiced. This is only available if ‘Authorize’ is selected as the Payment Action in the Sola module settings (see Payment Actions in the Configuration Options section of this document). Once an order has been invoiced, use ‘Credit Memo’ to refund the transaction. Please note that ‘Void’ cancels the credit card transaction but does not cancel the order. To cancel the order as well, see the Cancel section below. ### Cancel Use Cancel to void an un-captured transaction and cancel the associated order. ### Credit Memo Issue a Credit Memo to refund an order that has already been invoiced. ### Retrieving Sola Reference Number Sola transaction reference numbers can be found in the Transaction History section of any order page and are listed as **Transaction ID**. This can be useful when viewing your transactions on the Sola Gateway portal or when contacting Sola Support regarding specific transactions. # RMH (Retail Management Hero) ## Setup * Download the Updater. * When prompted for program name, enter “PaymentEngineRMH” * Follow the installation instructions: * The default download location is **C:\Program Files (x86)\Retail Hero\RMH POS\Extensions\PaymentEngineRMH** * In the POS Manager **Setup > Financial > Tender Types**: * A type with the description “Credit Card” is required. * For Gift Card, a type with the description “Gift Card” is required. * Add the Custom POS buttons (see below) * Restart the POS. ## Custom Buttons * In the POS Manager **Setup > Hardware > Custom POS Buttons** * For Settings Management, add a custom button with the following information: 1. Style : Internal Command 2. Caption : Settings 3. Command: `CustomActionCommand "paymentenginemanager65b4fe30-6fa4-4e71-af5b-71c9c1a07802"` * There should be two options: * **Change Key**: This allows changing the xKey stored in the database. * **Change Settings**: This allows modifying the settings. Changing the key from the settings window will update the xKey stored in the database. * For **Gift Card:Balance**, add a custom button with the following command: 1. Style: Internal Command 2. Caption: Gift Balance 3. Command: `CustomActionCommand "giftcardgetbalancee62227dd-ee9b-41b0-8390-161226f95436"` ## EBT **Step 1: Configure or create EBTFS and EBTCB as tender types** **EBT Tender** 1. Open the store Store Operations Manager and go to Financial > Tender Types. 2. If “EBTFS” is listed as an existing tender type, select it, click on Properties, and continue to the next step. If it is not listed: 1. Click **New** 2. Set Description: “EBT Food Stamp” 3. Set Tender Code: `EBTFS` 3. For tender type, select “Food Stamp” **EBT Cash Tender** 1. Open the store Store Operations Manager and go to Financial > Tender Types. 2. If “EBTCB” is listed as an existing tender type, select it, click on Properties, and continue to the next step. If it is not listed: 1. Click **New** 2. Set Description: “EBT Cash Benefit” 3. Set Tender Code: EBTCB 3. For tender type, select “Debit Card” **Step 2: Setting EBT Balance Custom Button** **EBT Balance Command** For EBT Balance, add a custom button with the following information: 1. Style: Internal Command 2. Caption: EBT Balance 3. Command: `CustomActionCommand ebtBalance_0586D912-FC34-401B-A55E-0B977C7F47B0` {% hint style="info" %} To enable the saved card feature, open the Sola settings >> RMH settings and choose **Enable Tokenization.** To enable Device Display Items, open the Sola settings >> RMH settings and choose **Device Display Items.** {% endhint %} ## Receipts #### Viewing Receipt Information To display receipt of payments made with Sola extension supported tender types (Credit/Debit card, EBT, Gift etc.), the application uses RMH's `Tender.Data` property to populate the custom receipt data string for these mentioned tender types. To display this value on the receipt, the property should be included in the tender iteration block. Receipt will show in POS as shown below. The highlighted area is `Tender.Data` value.

#### **Displaying additional data such as Balance, AuthCode for EBT, EBTCS, Gift** Sales receipts can show card info with balances for EBT and gift cards. The details can be displayed at the highlighted area.

To display **Balance**, **AuthCode** of RMH plugin uses the `Tender.Data2` variable. which can be used in receipt file as below. The highlighted block for including `Tender.Data2` is added just below the the "`Tendered`" line. This will print the additional tender details (card number, auth code, balance) for each tender if it contains additional details (such as custom payment methods like Credit Card, EBT, or Gift Card).

A sample receipt is shown below, which shows tender details. The receipt below shows a split payment example, containing a credit card and EBT payment. The credit card transaction displays Card Number and Auth Code. The EBT payment displays Card Number, Auth Code and the remaining balance on the card.

**NOTE**: `Tender.Data2` is not limited to EBT. It can contain additional details for other Cardknox payment methods such as EBTFS, Gift Card, and more. # RMS (Retail Management Systems) ## System Requirements .Net Framework 4 and above ## Installation Instructions for Credit Cards Enable Sola payment processing on RMS point-of-sale systems. **PART 1: Prepare each computer** 1. Run a Z Report: 1. Open the Store Operations POS. 2. Press **F5**. 3. Select **Print Z Report**. 2. Close the Store Operations POS. 3. Go to the Store Operations Administrator and click\ **File > Configuration > EDC**. 4. Select **Do not use electronic capture draft software** and click **OK**. 5. Repeat steps 1 and 2 on each register. **PART 2: Download and run the software** 1. Download the Sola Updater plugin:\ 2. Right-click on the downloaded program (Updater.exe), then click **Run as administrator** and choose **Yes** when prompted. 3. An input box will appear. Type fidelipayrms and click **Enter**. 4. You will be prompted to enter your Sola key and Merchant ID. (Developers\ should use their Sola test key and 123456 for the MID for testing.) ## Installation Instructions for Other Payment Types The following steps will enable additional payment types on the Sola\ gateway. ### **Installing Credit Card Capabilities** 1. Open the Store Operations Manager and go to **Database > Tender Types**. 2. If **Credit Card** is not listed: 1. Click on **New**. 2. Type Credit Card in the **Description** field. 3. Set the **Tender Code** and **Display Order** values. 3. Click **OK**. 4. Click **Close**. ### **Installing EBT Capabilities** **PART 1: Configure or create EBTFS as a tender type** 1. Open the Store Operations Manager and go to **Database >** **Tender Types**. 2. If **EBTFS** is listed as an existing tender type, select it, click on **Properties**, and continue to the next step. If it is *not* listed: 1. Click on **New**. 2. Type EBTFS in the **Description** field. 3. Set the **Tender Code** and **Display Order** values. 3. In the **Tender Type** dropdown, select **Food Stamps**. 4. Click **OK**. 5. **PART 2: Add an EBTFS button** 1. Go to **Database** **> Registers > Custom POS Buttons**. 2. Click **New**. 3. On the popup window, fill in several fields: 1. For the **Style** box, choose **COM OBJECT (Session Object)**. 2. For **Caption**, type EBT Balance. 3. For **Command**, type\ FidelipayRMS.GetEBTFSBalance. 4. Click **OK**. 5. Click **Close**. ### Installing Gift Card Capabilities \ **PART 1: Configure or create gift cards as a tender type** 1. Open the Store Operations Manager and go to **Database >** **Tender Types**. 2. If **Gift Card** is listed as an existing tender type, select it and click **Properties**. Continue to the next step. If it is *not* listed: 1. Click on **New**. 2. Type Gift Card in the **Description** field. 3. Type GC as the **Tender Code**. 4. Set the **Display Order** value you desire. 3. In the **Tender Type** dropdown, select **Other**. 4. Click **OK**. **PART 2: Add a Gift Card button** 1. Navigate to **Database > Registers > Custom POS Buttons**. 2. Click **New**. 3. In the window the pops up, you’ll need to fill in several fields: 1. For the **Style** box, choose **COM OBJECT (Session Object)**. 2. For **Caption**, type Gift Card Balance. 3. For **Command**, type\ FidelipayRMS.GetGiftBalance. 4. Click **OK**. **PART 3: Set option to enter the price at POS** 1. Navigate to **Database > Items**. 2. Check if the Gift Card item exists. The description for the item should be\ Gift Card. If it is listed, select the item and click on **Properties** and continue to the next step. If it is not listed: 1. Click on **New**. 2. Select on **Standard Item** and click **OK**. 3. Set **Item Lookup Code** as gc. 3. Select the **Inventory** tab and enter the appropriate\ information. 4. Select the **Options** tab. 5. Enable **Must enter price at the POS**. 6. Click **OK**. ## Installing Tokens The following steps will enable you to securely save cardholder information for future use. **PART 1: Enable tokens on your POS** 1. Run C:\FPS\_RMS\_Plugin\FidelipayRMS.exe. 2. Go to the **FidelipayRMSSettings** tab: 1. EnableTokenization, 1 2. DB\_Database, \[*YourDatabaseName*] 3. DB\_Username, \[*YourDatabaseUserName*] 4. DB\_Server, \[*YourServerIpAddress*] 5. DB\_Password \[*YourPassword*] 6. Click **Test Connection**. 3. Close and save the Settings file. \ **PART 2: Add a Tokens button** 1. Open the Store Operations Manager and go to\ **Database > Registers > Custom POS Buttons**. 2. Click **New**. 3. On the popup window, fill in several fields: 1. For the **Style** box, choose\ **COM OBJECT (Session Object)**. 2. For **Caption**, type Save Card. 3. For **Command**, type FidelipayRMS.SaveCard. 4. Click **OK**. 5. If Store Operations POS is currently running, restart it. If not, open it. 6. Click on **Saved Card** to test. ## Connecting a Credit Card Pin Pad **PART 1: Download the device drivers**\ For VeriFone Mx devices: 32 bit:\ [cdn.cardknox.com/pe/drivers/verifone/verifone\_unified\_driver\_installer\_32.msi](https://cdn.cardknox.com/pe/drivers/verifone/verifone_unified_driver_installer_32.msi) 64 bit:\ [cdn.cardknox.com/pe/drivers/verifone/verifone\_unified\_driver\_installer\_64.msi](https://cdn.cardknox.com/pe/drivers/verifone/verifone_unified_driver_installer_64.msi) **PART 2: Connect your terminal to RMS** 1. Navigate to C:\FPS\_RMS\_Plugin\FidelipayRMS.exe. 2. Complete the form with the appropriate device settings. 3. Restart RMS and run a test transaction. ## Add Sola variables to receipt To show the Sola information on the RMS receipt, you need to add **Session.Variable1** in the XML receipt. It includes the information below. Card number\ Card Type\ Auth Code\ Tender Amount\ Transaction Type\ Response **XML to add:** ```xml Len(Session.Variable1) tbNone "<" PageWidth Session.Variable1

``` **Update existing receipt in RMS** **PART 1: Locate the receipt currently in use** 1. In Store Operations Manager, go to **Database > Registers > Register List**. 2. Select a register that is currently used and on which you wish to base the receipt. 3. Click **Properties**. 4. Click on the **Receipt Printer 1** tab. 5. The receipt currently in use can be found in the **Receipt Format** field. \ **PART 2: Save the current receipt** 1. In the Store Operations Manager, go to **Database > Registers > Receipt Formats**. 2. Select the sales receipt that is currently used. 3. Click **Properties.** 4. Use the **Save As** command to save the receipt as\ CurrentReceipt to the following location:\ C:\Program Files\Microsoft Retail Management System\StoreOperations\ReceiptTemplates **PART 3: Add Session.Variable1 to the receipt** 1. Open the receipt in a text editor. 2. Choose the SUB in the XML receipt where you want to display the Cardknox information. 3. Copy paste the XML to add as listed in the “Add Cardknox variables to receipt“ section above and save it.
**PART 4: Update RMS through the desktop icon** 1. Open Store Operations Manager and go to **Database > Registers > Receipt Formats**. 2. On the right side of the window, click **New**. 3. Type plugin\_receipt into both the **Title** and **Description** fields. 4. In the **Sales** field, click the magnifying glass. 5. Go to the following plugin folder:\ C:\Program Files\Microsoft RetailManagementSystem\StoreOperations\ReceiptTemplates\Plugin 6. Select the current receipt name and click **Open**. 7. When you are prompted to update all transaction types, click **Yes**. 8. The **Report** box will still not have a file. Click the magnifying glass, select **XReport.xml**, and click **Open**. 9. Click **OK** and close the Receipt Formats window. \ **PART 5: Select the receipt format for each register** 1. Go to **Database > Registers > Register List** and complete the following steps for each register: 1. Select the register and click **Properties**. 2. Choose the **Receipt Printer 1** tab. 3. In the **Receipt Format** box, click the magnifying glass. 4. Select **plugin\_receipt** and click **OK**. 2. After this has been completed for all of the registers, close the Registers window and restart the POS. ### Display EBT Balance on Receipt To display the EBT balance on the RMS receipt:
1. In the Cardknox plugin advanced settings set `EBTFSBalanceVariable` to a number from 1-9. Note: Ensure that the (`EBTFSBalanceVariable`) variable doesn't conflict with the following variables in the settings: "GiftCardBalanceVariable", "ReceiptHookVariable", and "RetailPointBalanceVariable". 2. Add `Session.Variable{x}` to the receipt. For example, `Session.Variable1` . The number, in this case "1", should match the number entered in step 1 above. Sample receipt snippet: ``` Len(Session.Variable1) "Available EBTFS Balance|" Session.Variable1 "|" ``` To display the GIFT balance on the RMS receipt: 1. In the Cardknox plugin advanced settings set `GiftCardBalanceVariable` to a number from 1-9. Note: Ensure that the `GiftCardBalanceVariable` variable doesn't conflict with the following variables in the settings "EBTFSBalanceVariable", "ReceiptHookVariable" and "RetailPointBalanceVariable". 2. Add `Session.Variable{x}` to the receipt. For example `Session.Variable2` The number, in this case "2", should match the number entered in step 2 above Sample receipt snippet: ``` Len(Session.Variable2) "Available EBTFS Balance|" Session.Variable2 "|" ``` ## Additional Features ### Enable Cashback #### Cashback Prompt on device 1. Navigate to **Advanced Settings** and set **Allow Cashback** = True 2. Set **Enable Cashback** = True #### Add Cashback as an item 1. Navigate to **FidelipayRMSSettings** tab 2. Set **Cashback Fee Item** to a non inventory item 3. Navigate to **Advanced Settings**. Set **CashbackAmountIncludedInAmount** to True ### Offline Transactions #### Enable Offline transaction 1. Enable Offline Transactions in the **FidelpayRMS Settings** panel 2. Click **“Display Prompt Before Continue”**: This will bring a pop up on RMS before continuing to Offline mode. 3. Selecting **"Require Customer Selection"** will require a customer selected for offline. 4. Designate the max amount allowed for Offline transactions. 5. Select the Transaction Type allowed in Offline mode. {% hint style="warning" %} RMS database Version minimum SQL 2005 {% endhint %} ### eWIC **Step 1: Create a new tender** 1. Navigate to the RMS Manager > Database > Tender Types 2. Click on NEW 3. Set **Description** as eWIC 4. Set **Tender Code** as EBTW **Step 2: Enable eWIC** 1. Enable **eWIC** in the **FidelipayRMS Settings** panel 2. "Secondary UPC Field Name": This can be used to use the Sub description for the UPC or PLU for eWIC. 3. "Discount item": Set a non-inventory item to be used for eWIC partial auth 4. "Discount reason code": Set a reason code to be used for eWIC partial auth 5. Ensure that your items lookup code matches the expected eWIC UPC or PLU code # Frequently Asked Questions ### Question: Is there a way to specify that only numbers can be entered into a credit card number field or a CVV iFields field? Or can the system generate an error message if the format is not valid? **Answer:** As of the v2.6.1912.1301-beta, you can specify an event to trigger a callback-based on events in the iField using the function `addIfieldCallback (event, callback)`. This callback will receive some data about events in the iField, such as whether the card number and/or CVV are valid. The card number validation is based on minimum and maximum lengths and whether it passes the Luhn check. The CVV validation is based on the length, depending on the card issuer. You can use a callback to prevent the call to get tokens. We recommend you perform the least client-side validation necessary because a mistake in the validation logic could prevent a transaction from being processed when it would otherwise have been approved. See the iField Key Pressed Callback section in the iFields documentation for an example of a callback being used to change the iField style based on whether the data in it is valid. ### Question: How do I obtain an API key? **Answer:** You can generate an API directly from your Merchant Portal Settings, please see Key Managment in the Sola Merchant Portal guide for more information. ### Question: What devices are supported for in-store payments? **Answer:** Sola supports a wide variety of terminals and card readers from manufacturers such as IDTech, Verifone, and more. See the complete list at Supported EMV Equipment. ### Question: How do I close a batch so I can get funded? **Answer:** Sola closes batches automatically, so there is no need for you to manually close a batch. Learn more about Sola batch processing at Batch Processing. ### Question: When integrating with the Sola transaction API, how can I ensure that the customer receives a receipt of the transaction details when they place an order on a merchant’s website? **Answer:** You can do this by setting the `xCustReceipt` field to True along with the transaction request to send a receipt to the customer via the email address specified in the xEmail field. ### Question: Does Sola support Magento 2? **Answer:** Yes, there is a Sola plugin for Magento 2 that connects to Sola directly. See Magento Payment Gateway for more information about the Sola Magento 2 plugin. ### Question: Does Sola support Magento 1? **Answer:** Yes. You can do this by setting up Magento 1 with the Authorize.Net AIM option available in the Magento settings and then changing the endpoint URL to Sola. ### Question: What is the Sola mobile app? **Answer:** Sola Mobile is an app you can download to your mobile device to securely accept credit card transactions on your Sola account. [Android App](https://play.google.com/store/apps/details?id=com.gateway.cardknox.android)\ [iOS App](https://apps.apple.com/us/app/cardknox-payments/id1358857120) ### Question: Does the Sola mobile app work with an external credit card device? **Answer:** No, not at this time. We are working toward achieving this goal in 2024. ### Question: What is Sola iFields? **Answer:** Sola iFields technology uses iframe fields to replace credit card and CVV data on the website and sends the card information directly to Sola. Since sensitive card information bypasses the merchant’s server, this solution enables merchants to remain out of PCI scope. In addition, this Sola solution allows developers to fully customize how payment forms are designed. Learn more about Sola iFields technology at Sola iFields. ### Question: Does Sola support contactless payments? **Answer:** Yes, Sola has several terminals that support near-field communication (NFC) technology for contactless payments. See the complete list of EMV terminals. # How to Build POS Integration Flows When you build integrations for different POS devices, there are three distinct types of credit card processing flows. Read on to better understand each integration method. ### **Credit Card Processing Flow 1** **Payment Engine → Cardknox Gateway → Bank**\ The credit card device is used to obtain card information, but the transaction flows from Payment Engine to the Cardknox Gateway and then to the bank.

1. The **POS software** communicates the intended transaction to **Payment Engine**. 2. **Payment Engine** prompts the user for their card information via the **credit card device**. 3. The **credit card device** transfers transaction data to **Payment Engine**. 4. **Payment Engine** transfers transaction data to the **Cardknox gateway**. 5. The **Cardknox gateway** transfers transaction data to the **bank** for processing. 6. The **bank** communicates the transaction response (approval or decline) to the **Cardknox gateway**. 7. The **Cardknox gateway** communicates the bank’s transaction response to **Payment Engine**. 8. **Payment Engine** communicates the bank's transaction response to the **POS software**. ### Credit Card Processing Flow 2 **Payment Engine → Credit Card Device → Cardknox Gateway → Bank**\ The credit card device plays an active role in the transaction flow, with the transaction passing from Payment Engine, to the device, to the Cardknox Gateway, and then to the bank.

1. The **POS software** communicates the intended transaction to **Payment Engine**. 2. **Payment Engine** communicates the intended transaction to the **credit card device**. 3. The **credit card device** prompts the user for their card information. 4. The **credit card device** transfers transaction data to the **bank** for processing. 5. The **bank** communicates the transaction response (approval or decline) to the **credit card device**. 6. The **credit card device** provides the bank’s transaction response to **Payment Engine**. 7. **Payment Engine** communicates the bank's transaction response to the **POS software**. 8. **Payment Engine** notifies the Sola **gateway** of the transaction so that the data is recorded in the Merchant’s Sola account. ## Ways to Integrate – Considerations ### SDK (Payment Engine) [Payment Engine SDK](/sdk/payment-engine-sdk) **Supported devices:** * All Sola supported devices **Benefits:** * Supports all Sola devices **Limitations:** * Only supported on Windows ### BBPOS [BBPOS](/products/bbpos) **Supported devices:** * All Sola supported devices **Benefits:** * Supports all Sola devices **Limitations:** * Only supported on Windows and Mac (The installation on Mac can be difficult) * Requires the BBPOS application to be installed and needs to run in the background all the time ### API + Keyboard Emulator [Transaction API](/api/transaction) **Supported devices:** * ID Tech Augusta and VP8300 **Benefits:** * Minimal integration * Plug n Play Devices **Limitations:** * Supports a limited number of devices * Does not support PIN entry * Augusta does not support tap * The US Only # Card Present Integration Guide ### Payment Engine .NET SDK [Payment Engine SDK](/sdk/payment-engine-sdk) **Supported Devices:**\ All Sola-supported devices **Benefits:** * Seamless integration with all Sola-supported devices. **Limitations:** * Only compatible with Windows operating systems. ### BBPOS [BBPOS](/products/bbpos) **Supported Devices:**\ All Sola-supported devices **Benefits:** * Works with all Sola-supported devices. **Limitations:** * Compatible only with Windows and Mac. * Installation on Mac can be challenging. * Requires the BBPOS application to be installed and actively running in the background.\
### Cloud IM [CloudIM Developer Guide | Cardknox](https://docs.cardknox.com/cardknox-products/cloudim-developer-guide) **Supported Devices:**\ PAX A77, A35, A80, A920, and A920 Pro **Benefits:** * API-driven integration with minimal setup. * No installation required for operation. **Limitations:** * Supports a limited range of devices. * Some commands and features are not yet fully supported. ### API + Keyboard Emulator [Transaction API](/api/transaction) **Supported Devices:**\ ID Tech Augusta and VP8300 **Benefits:** * Simple integration through API. * Plug-and-play devices for quick setup. **Limitations:** * Only supports a limited number of devices. * Lacks support for PIN entry. * Augusta does not support tap functionality. * Only supported in the US
# Supported Currencies | **AlphaCode** | **NumericCode** | | ------------- | --------------- | | USD | 840 | | AED | 784 | | AFN | 971 | | ALL | 008 | | AMD | 051 | | ANG | 532 | | AOA | 973 | | ARS | 032 | | AUD | 036 | | AWG | 533 | | AZN | 944 | | BAM | 977 | | BBD | 052 | | BDT | 050 | | BGN | 975 | | BHD | 048 | | BIF | 108 | | BMD | 060 | | BND | 096 | | BOB | 068 | | BOV | 984 | | BRL | 986 | | BSD | 044 | | BTN | 064 | | BWP | 072 | | BYN | 933 | | BZD | 084 | | CAD | 124 | | CDF | 976 | | CHE | 947 | | CHF | 756 | | CHW | 948 | | CLF | 990 | | CLP | 152 | | CNY | 156 | | COP | 170 | | COU | 970 | | CRC | 188 | | CUC | 931 | | CUP | 192 | | CVE | 132 | | CZK | 203 | | DJF | 262 | | DKK | 208 | | DOP | 214 | | DZD | 012 | | EGP | 818 | | ERN | 232 | | ETB | 230 | | EUR | 978 | | FJD | 242 | | FKP | 238 | | GBP | 826 | | GEL | 981 | | GHS | 936 | | GIP | 292 | | GMD | 270 | | GNF | 324 | | GTQ | 320 | | GYD | 328 | | HKD | 344 | | HNL | 340 | | HRK | 191 | | HTG | 332 | | HUF | 348 | | IDR | 360 | | ILS | 376 | | INR | 356 | | IQD | 368 | | IRR | 364 | | ISK | 352 | | JMD | 388 | | JOD | 400 | | JPY | 392 | | KES | 404 | | KGS | 417 | | KHR | 116 | | KMF | 174 | | KPW | 408 | | KRW | 410 | | KWD | 414 | | KYD | 136 | | KZT | 398 | | LAK | 418 | | LBP | 422 | | LKR | 144 | | LRD | 430 | | LSL | 426 | | LYD | 434 | | MAD | 504 | | MDL | 498 | | MGA | 969 | | MKD | 807 | | MMK | 104 | | MNT | 496 | | MOP | 446 | | MRU | 929 | | MUR | 480 | | MVR | 462 | | MWK | 454 | | MXN | 484 | | MXV | 979 | | MYR | 458 | | MZN | 943 | | NAD | 516 | | NGN | 566 | | NIO | 558 | | NOK | 578 | | NPR | 524 | | NZD | 554 | | OMR | 512 | | PAB | 590 | | PEN | 604 | | PGK | 598 | | PHP | 608 | | PKR | 586 | | PLN | 985 | | PYG | 600 | | QAR | 634 | | RON | 946 | | RSD | 941 | | RUB | 643 | | RWF | 646 | | SAR | 682 | | SBD | 090 | | SCR | 690 | | SDG | 938 | | SEK | 752 | | SGD | 702 | | SHP | 654 | | SLL | 694 | | SOS | 706 | | SRD | 968 | | SSP | 728 | | STN | 930 | | SVC | 222 | | SYP | 760 | | SZL | 748 | | THB | 764 | | TJS | 972 | | TMT | 934 | | TND | 788 | | TOP | 776 | | TRY | 949 | | TTD | 780 | | TWD | 901 | | TZS | 834 | | UAH | 980 | | UGX | 800 | | USN | 997 | | UYI | 940 | | UYU | 858 | | UZS | 860 | | VEF | 937 | | VND | 704 | | VUV | 548 | | WST | 882 | | XAF | 950 | | XCD | 951 | | XDR | 960 | | XOF | 952 | | XPF | 953 | | XSU | 994 | | XUA | 965 | | YER | 886 | | ZAR | 710 | | ZMW | 967 | | ZWL | 932 | # Glossary of Terms Navigating through a sea of technical terms, phrases, and acronyms can be confusing, even for someone familiar with the payment processing industry. Here is a list of some of the most commonly used payment processing terms to help you. *** [A](#account-number) [B](#bank-card) [C](#card-association) [D](#dcc) [E](#ebt) [F](#federal-reserve-bank) [G](#gateway-only-provider) [H](#holdback) [I](#ifields-technology) [K](#kyc) [L](#loyalty-program) [M](#magnetic-stripe) [N](#nfc) [O](#omnichannel-processing) [P](#payfac) [S](#sdk) [T](#transaction) [V](#var) [Z](#zip-code) [#](#3d-secure-technology) *** ### Account number A unique sequence of numbers assigned to a cardholder account that identifies the issuer and type of financial transaction card. *** ### Account Updater A tool that, in conjunction with tokenization, automatically keeps credit cards in the Sola data vault updated to ensure subsequent transactions are not declined. *** ### ACH Automated Clearing House – Electronic network used to transfer money and payment information between bank accounts. See for more information. *** ### Acquirer A licensed member that maintains the merchant relationship and acquires the data relating to a transaction from the merchant or card acceptor and submits that data into interchange, either directly or indirectly. *** ### AFT Automatic Funds Transfer – A transaction in which funds are securely transferred from one bank account to another via electronic or telecommunications technology. *** ### AML Anti-Money Laundering – A set of laws, regulations, and procedures intended to prevent criminals from disguising illegally obtained funds as legitimate income. See KYC for more information. *** ### Annual fee A yearly fee charged by some independent sales organizations (ISOs) and acquirers to maintain a merchant’s account. This is also called a renewal fee, subscription fee, or membership fee. *** ### API Application Programming Interface – A technological interface or communication protocol between a client and a server intended to simplify the building of client-side software. See for more information. *** ### ATM Automated Teller Machine – An unattended, magnetic stripe-reading or EMV (Europay, Mastercard®, and Visa®) chip-enabled terminal that dispenses cash, accepts deposits and loan payments, enables a bank customer to order transfers among accounts, and make account inquiries. *** ### Authorization A process defined in operations regulations whereby a transaction is approved by or on behalf of an issuer; commonly understood to be receiving of a sales validation by the merchant, telephone, or authorization terminal. *** ### Authorization code A code notifying you that you have obtained the authorization for a specific card transaction. *** ### AVS Address Verification System – Also referred to as Address Verification Service, AVS is a system used to verify whether the billing address given by the customer matches the credit card used for the transaction. This system checks the billing address of the credit card provided by the user with the address on file at the credit card company. If a merchant chooses not to use AVS, Visa and Mastercard will not support their transactions and will charge an additional percentage on those sales. *** ### AVS Precheck Sola feature that enables the AVS response to occur before the authorization so that if the transaction is declined, there is no temporary hold on the customer’s card. *** ### Bank card A debit or credit card issued by an issuing bank. Also referred to as “bankcard.” *** ### Batch A collection of credit card transactions saved for submitting at one time, usually each day. Merchants who do not have real-time verification systems must submit their transactions manually through a point-of-sale (POS) terminal. Batch fees are charged to encourage a merchant to submit his or her transactions at one time, rather than throughout the day. *** ### BBPOS Browser-Based POS – Sola application that allows a POS running in a browser to accept EMV payments while remaining out of PCI scope. *** ### Billing Cycle The interval between periodic billings for goods sold or services rendered, typically sent on a monthly basis. *** ### BIN Bank Identification Number – The first 6 digits of a credit or debit card number. Also referred to as Issuer Identification Number (IIN) *** ### Card association A payment card industry governing body that sets rules and interchange rates. Visa, Mastercard, Discover, and American Express are the four largest card associations in North America. *** ### Cardholder The customer to whom a card has been issued, or the individual authorized to use the card. *** ### Chargeback A chargeback occurs when a cardholder disputes a credit card transaction with his or her credit card issuer. The card issuer initiates a chargeback against the merchant account. The amount of the disputed transaction is immediately withdrawn from the merchant’s bank account, and the merchant has 10 days in which to dispute the chargeback with supporting documentation such as proof of purchase, customer signature, proof of delivery, etc. A chargeback is ultimately decided and resolved by the card association. A chargeback fee is usually assessed to the merchant on top of the actual transaction. See also Retrieval request. *** ### Check A bill of exchange or draft on a bank drawn against deposited funds to pay a specified sum of money to a specified entity (e.g., a person or business) on demand. A check is considered cash and is negotiable when endorsed. *** ### Clear The collection of funds on which a check is drawn and payment of those funds to the holder of the check. *** ### Clearing The process of exchanging financial transaction details between an acquirer and an issuer to facilitate posting of a cardholder’s account and reconciliation of a customer’s settlement position. *** ### Clearing House Funds Funds represented by checks or drafts that pass between banks through the Federal Reserve system. *** ### CNP Card Not Present – A transaction made with a payment card in which the customer does not physically present the card to the merchant at the time of the transaction. Examples include online, mobile, and MOTO transactions. *** ### Code 10 authorization A voice authorization code that you might initiate when you suspect a card is stolen or counterfeit, or when a customer is acting suspiciously. *** ### Contactless A payment method that uses near field communication (NFC) technology to enable purchases using an NFC-enabled EMV chip card, or other payment-enabled device such as a mobile phone, at the point of sale without having physical contact with the payment terminal. See NFC for more information. *** ### Credit A refund or return of goods by a consumer to the merchant. *** ### Credit card A transaction card bearing an account number assigned to a cardholder with a credit limit that can be used to purchase goods and services and to obtain cash disbursements on credit. The cardholder is subsequently billed by an issuer for repayment of the credit extended at once or on an installment basis. *** ### Credit card processors Merchant services providers that handle the details of processing credit card transactions between merchants, issuing banks, and merchant account providers. Also referred to as “third-party processors.” *** ### Currency conversion The process by which the transaction currency is converted into the currency of settlement or the currency of the issuer for the purpose of facilitating transaction authorization, clearing, and settlement reporting. The currency of transaction is determined by the acquirer; the currency of the issuer is the preferred currency used by the issuer, and most often, the currency in which the cardholder will be billed. *** ### CVV Card Verification Value – Security feature used with card-not-present transactions. The CVV is a 3- or 4-digit code either printed or embossed on a credit or debit card. Also known as Card Security Code (CSC). Issuer variations: • American Express, Discover – CID\ • Mastercard – CVC,CVC2\ • Visa – CVV, CVV2 *** ### DCC Dynamic Currency Conversion – A credit card processing solution that allows merchants to offer international customers the choice to pay with Visa and Mastercard in either their local currency, or the merchant’s base currency. The exchange rate includes a 3% margin which is displayed on the receipt along with the conversion. By paying in their local currency, tourists and business travelers can make informed decisions about their purchases and feel confident knowing the exact amount they are paying. In addition, cardholders have the choice of opting out and paying without converting the sale to avoid being charged international fees when their issuer does not charge. Revenue split is available to merchant. *** ### Debit card A transaction card used to initiate a debit transaction. In general, these transactions are used primarily to purchase goods and services and to obtain cash, for which the cardholder’s asset account is debited by the issuer. *** ### Debit fees Fees based on the debit network that issues the debit card. Debit fees are comprised of network fees and transaction fees, and usually consist of a flat fee and a statement fee. *** ### Decline re-routing Sola feature that enables a transaction to be re-routed to an alternate processor if the transaction was initially declined. *** ### Digital wallet A consumer account set up to allow e-commerce transactions through a particular credit card processing system. Before the consumer can make a purchase, he or she must first establish an account with the credit card processor, who provides an identification number and password. The consumer can then make purchases at any Web site that supports the digital wallet system. *** ### Discount rate The rate charged to a merchant for payment processing services on debit and credit card transactions. *** ### EBT Electronic Benefits Transfer – An electronic system used in the United States that allows state welfare departments to issue benefits via a magnetically encoded payment card. See for more information. *** ### E-commerce The buying and selling of goods and services, or the transmitting of funds or data, over an electronic network, primarily the Internet. These business transactions occur either as business-to-business (B2B), business-to-consumer (B2C), consumer-to-consumer, or consumer-to-business. *** ### EDC Electronic draft capture – A system in which the transaction data is captured at the merchant location for processing and storage. *** ### EFT Electronic funds transfer – A paperless transfer of funds initiated from a terminal, computer, telephone instrument, or magnetic tape. *** ### EMV Europay, MasterCard and Visa – EMV is a global standard created by Europay, Mastercard, and Visa for authenticating payment card transactions. See for more information. *** ### EMV card A credit or debit card with an embedded microchip and associated technology designed to enable secure payments at compatible point-of-sale terminals. Also referred to as “chip card,” “PIN-and-chip,” and “smart card.” See for more information. *** ### ERP Enterprise Resource Planning – Software application used to integrate all of the processes needed to run a company with a single system. *** ### eWIC card WIC (Women, Infants, and Children) – WIC is a federal grant program designed to provide supplemental nutritious food and nutrition education to low-income pregnant, breastfeeding, and non-breastfeeding postpartum women, and to infants and children up to age five who are found to be at nutritional risk. An eWIC card is WIC’s electronic payment card issued to participants in the program used to obtain nutrition benefits. See also “EBT card.” See for more information. *** ### Federal Reserve Bank A bank that, along with its branches, is one of 12 banks that make up the Federal Reserve System. The role of each Federal Reserve Bank is to monitor the commercial and savings banks in its region to ensure that they follow Federal Reserve Board regulations. The reserve banks act as depositories for member banks in their regions, providing money transfer and other services. *** ### Financial Institution An institution that collects funds from the public to place in financial assets such as stocks, bonds, money market instruments, bank deposits, or loans. Depository institutions such as banks, savings and loans, credit unions, and savings banks, pay interest on deposits and invest the deposit money mostly in loans. *** ### Floor limit A specific dollar limit used to determine which card transactions you must authorize. For example, if your business has a floor limit of $1,000, you must get authorization for any transaction over that amount. Note: All airline, telephone, and mail order transactions must be authorized, even if the amount is under your floor limit. *** ### Fraud A wrongful or criminal deceptive activity used to obtain money, assets, or other property. *** ### Gateway-only provider Option that enables a merchant the flexibility to process transactions under their own merchant account. The Sola gateway-only option also offers pre-processing functions such as fraud screening and processor routing. *** ### Holdback A portion of the revenue from a merchant’s credit card transactions held in reserve by the merchant account provider to cover possible disputed charges, chargeback fees, and other expenses. Also referred to as a “reserve.” After a predetermined time, holdbacks are turned over to the merchant. Note: merchant account providers almost never pay interest on holdbacks. *** ### iFields technology A Sola technology solution that integrates into your payment forms, enabling you to design and customize the look and feel of your payment and checkout flows. You can process transactions without having sensitive card data touch your server, keeping you out of PCI scope. *** ### Intelligent routing Sola's proprietary Interchange Qualification Monitoring (IQM) technology that gathers transaction data and routes every transaction to the payment processing platform that can process the payment for the lowest cost. *** ### Interchange fee The fee that the card association charges the merchant to get the funds into the merchant’s bank (acquiring bank) and to get the billing information to the cardholder’s bank (issuing bank). Interchange fees are determined based on credit card regulations and how the appropriate data is captured, including card swipe or dip, address, and electronic signature as needed. These fees are also based on the timeliness of the settlement of transactions. *** ### ISO Independent Sales Organization – A company that sells credit card processing services independently from a financial firm or bank, allowing a business to accept credit card payments. *** ### Issuer The member bank that enters into a contractual agreement with card associations to issue cards. *** ### Issuing bank The bank that maintains the consumer’s credit card account and which must pay out to the merchant’s account in a credit card purchase. The issuing bank bills the customer for the debt. *** ### ISV Independent Software Vendor – An individual or organization that develops, markets, and sells software products that run on third-party software and hardware platforms. *** ### IVR Interactive Voice Response – Technology that allows a computer to interact with humans through the use of voice and dual tone multi-frequency (DTMF) signal input using a touch tone keypad. In telecommunications, IVR allows customers to interact with a company’s host system via a telephone keypad or by speech recognition. See for more information. *** ### KYC Know Your Customer – The process of a business identifying and verifying the identity of its clients and assessing their suitability, along with the potential risks of illegal intentions towards the business relationship. The term is also used to refer to the bank regulations and anti-money laundering regulations which govern these activities. *** ### Loyalty program A rewards program a merchant offers to its customers who meet certain criteria, such as making frequent purchases. *** ### Magnetic stripe The magnetically encoded stripe on the bank card that contains information pertinent to the cardholder account. The physical and magnetic characteristics of the magnetic stripe are specified in ISO Standards 7810, 7811, and 7813. *** ### Magnetic stripe reader A device that reads information recorded on the magnetic stripe of a card. Also known as a “card swipe reader.” *** ### MCP Multi Currency Pricing – An e-commerce solution that converts the merchant’s base currency into the customer’s foreign currency. Merchants are funded in US currency at a guaranteed rate without any fluctuation risk. *** ### Member An institution that participates in the programs offered by card associations such as issuers and acquirers. *** ### Merchant A retailer, or any other person, firm, or corporation that (pursuant to a merchant agreement) agrees to accept credit cards, debit cards, or both, when properly presented. *** ### Merchant account A specialized bank-approved and issued account to process credit card transactions. It is one of three parts needed to accept credit cards. The other required parts are a local bank checking account (to deposit funds) and a processing solution (to access the merchant account) such as a terminal or gateway. *** ### Merchant bank A bank that has entered into an agreement with a merchant to accept deposits generated by bank card transactions; also referred to as the “acquirer” or “acquiring bank.” *** ### Merchant Identification Number The number that a financial institution assigns to a merchant to identify the business. *** ### Mobile payment Payment made with a mobile payment application using a mobile device such as a smartphone or tablet. Examples include Apple Pay, Cash App, Google Pay, Venmo, and Zelle. *** ### Monthly minimum The minimum amount in fees and percentages charged by a merchant services provider in a given month. If account activity does not generate the monthly minimum, the account holder must make up the difference. *** ### MOTO The discount rate charged by the merchant account provider for credit card transactions in which the actual credit card was not available to the merchant. MOTO discount rates are generally higher than swipe discount rates to account for the increased chance of fraud or nonpayment. *** ### NFC Near Field Communication – A set of communication protocols that enable two electronic devices, one of which is usually a portable device such as a smartphone, to establish communication by bringing them within 1 to 2 inches of each other. *** ### Omnichannel processing Technical solution enabling a merchant to accept cashless payments across all channels, including online, in-store, mobile, e-wallet, and MOTO. *** ### PayFac Payment Facilitator – Merchant service provider that simplifies the merchant account enrollment process by enabling a business to sign up as a sub-merchant under the payment facilitator’s merchant account. *** ### Payment aggregator A service provider that allows merchants to process mobile or e-commerce payments. Payment aggregators enable businesses to accept credit and debit card payments without setting up a merchant account through a bank. *** ### PCI DSS Payment Card Industry Data Security Standard – The PCI information security standard for organizations that handle branded credit cards from the major card issuers. The PCI Standard is mandated by the card brands but is administered by the Payment Card Industry Security Standards Council (PCI SSC). The standard was created to increase controls around cardholder data to reduce credit card fraud. Validation of compliance is performed annually or quarterly, either by an external Qualified Security Assessor (QSA) or by a firm specific Internal Security Assessor (ISA) that creates a Report on Compliance for organizations handling large volumes of transactions, or by Self-Assessment Questionnaire (SAQ) for companies handling smaller volumes. *** ### PCI DSS Level 1 Compliance A set of requirements developed by the PCI SSC to ensure that companies that store, transmit, or process credit card data comply with the highest standards of security. Within the PCI DSS standards, there are 4 levels of PCI compliance. These levels are based on the annual number of transactions for any given merchant. PCI DSS Level 1 is the highest level of compliance and is defined as follows: Processing greater than 6 million Mastercard or Visa transactions annually, OR,\ A merchant that has experienced an attack resulting in compromised card data, OR,\ A merchant deemed Level 1 by a card association *** ### PCI SSC Payment Card Industry Security Standards Council – Global forum that brings together payments industry stakeholders to develop and drive adoption of data security standards and resources for safe payments worldwide. *** ### Payment gateway The code that transmits a customer’s order to and from a merchant’s bank’s transaction-authorizing agent, usually a merchant account provider. See also “real-time processing.” See for more information about the Sola payment gateway. *** ### Payment gateway provider A company that provides code and/or software for an e-commerce site enabling it to transfer information from its shopping cart to the acquiring bank, and on through the rest of the credit card transaction process. See also “payment gateway.” *** ### PIN Personal Identification Number – A four-to-twelve character secret code that allows an issuer to positively authenticate the cardholder for the purpose of approving an ATM or terminal machine transaction occurring at a point-of-interaction device. *** ### PIN debit Secure PIN debit card processing feature which results in the lowest processing fees. *** ### Plugin A software component, also called an extension, that adds a specific feature to an existing program to enable customization. *** ### POS Point of Sale – A location where a transaction takes place between a merchant and a customer when a product or service is purchased, commonly using a point-of-sale system to complete the transaction. POS can also refer to point-of-sale hardware and software, such as electronic cash register systems, touch-screen displays, barcode scanners, and receipt printers. *** ### POS terminal A device that allows a customer to swipe, tap, or insert a credit card to make a charge. Also known as a “terminal machine.” See for more information. *** ### Postal code A 6-digit alphanumeric string of characters that form part of a postal address in Canada that follows the province or territory abbreviation. *** ### Processing solution A device, software, or virtual product that allows a merchant to connect to a merchant account. Without a processing solution like a credit card terminal, there would be no way to verify, approve, and deposit credit card transactions. *** ### PSP Payment Service Provider – A company that combines the functions of both a payment gateway and a payment processor, and can connect to multiple acquiring and payment networks. *** ### P2PE Point-to-Point Encryption – a security standard created by the Payment Card Industry (PCI) to ensure payment card data remains secure from the beginning to the end of the transaction process. *** ### Real-time processing The process of having a customer’s credit card information validated and processed automatically and in real-time. The credit card will be charged and the money will be deposited into your bank account all automatically. *** ### Receipt A hardcopy document representing a transaction that took place at the point of sale, with a description that usually includes the transaction date, merchant name/location, primary account number, amount, and reference number. *** ### Recurring fees Regularly occurring charges for maintaining a merchant account. Recurring fees include the discount rate, transaction fees, statement fee, and monthly minimum. *** ### Recurring payment Regularly scheduled customer payments that occur over time at specific intervals, such as daily, weekly, monthly, quarterly, or annually. *** ### Refund Money returned to a customer in exchange for the return of purchased goods or services, or when the purchased goods or services were unsatisfactory or unfulfilled. *** ### Reserve See “Holdback.” *** ### Retrieval request A retrieval request occurs when a cardholder cannot remember a credit card transaction, or when the bank wants order information. The card issuer initiates the retrieval request, and the merchant has 10 days to respond with the order information or the retrieval request will turn into a chargeback. Retrieval requests usually include a fee issued against the merchant. *** ### Routing number A 9-digit number established by the American Bankers Association (ABA) used to identify a bank or financial institution when clearing funds or processing checks. Also referred to as a routing transit number. *** ### SDK Software Development Kit – A collection of software used for developing applications for a specific device or operating system. SDKs typically include a compiler, which is used to create applications from source code files, and an integrated development environment (IDE) enabling a developer to write source code, fix program errors, and edit a program’s graphical user interface (GUI). See for more information. *** ### SSL Secure Socket Layer – A system for encrypting data sent over the Internet, including e-commerce transactions and passwords. With SSL, client and server computers exchange public keys, allowing them to encode and decode their communication. *** ### Settlement The process by which merchant and cardholder banks exchange financial data and value resulting from sales transactions, cash disbursements, and merchandise credits. *** ### Setup fees Fees charged for establishing a merchant account, including application fees, software licensing fees, and equipment purchases. *** ### Smart card A payment transaction card that contains an embedded computer chip (either a memory chip or a microprocessor) that stores and transmits data. This data is usually associated with either value, information, or both and is stored and processed within the card’s chip. *** ### Stored-value card A transaction card, such as a gift card or prepaid card, containing a computer chip that can store electronic “money.” Unlike a credit card, a stored-value card can only spend out the dollar amount its owner has already put into the card account. It is similar in function to a prepaid calling card but is available for all purchases. *** ### Subscription A recurring payment that occurs on a regular, fixed schedule. Examples include memberships, charitable donations, and rent. *** ### Swipe discount rate The discount rate charged by a merchant account provider for transactions in which a credit card is available for inspection by the merchant. Swipe discount rates are generally lower than MOTO discount rates because the merchant can match signatures and perform other checks for fraud or misuse. *** ### Transaction An exchange or transfer of goods, services, or funds between a customer and a merchant. *** ### Transaction date The date on which a cardholder effects a card purchase of goods, services, or other things of value, or effects a cash disbursement. *** ### Transaction fee A charge for each credit card transaction, collected by the merchant account provider or ISO. *** ### Tokenization A process that replaces sensitive cardholder data with a string of unique characters to safeguard payment card information during a transaction. *** ### VAR Value Added Reseller – A company that adds features or services to an existing product, then resells it (usually to end-users) as an integrated product or complete turnkey solution. *** ### Void Identifies a transaction canceled by a merchant before it settles through a customer’s payment card account. *** ### ZIP code A 5- to 9-digit numeric code used by the United States Postal Service (USPS) to identify a particular postal delivery area in the United States. The 9-digit code is referred to as “ZIP+4” with the last 4 digits identifying a specific delivery route within a delivery area. *** ### 3D Secure technology A set of fraud prevention protocols that enables a real-time, secure, information-sharing connection between merchants, payment networks, and financial institutions to authenticate customers more accurately and reduce fraud in card-not-present transactions. Each card network (Visa, Mastercard, American Express, and Discover) has their own version of 3-D Secure. * 3D Secure version 2.0 improvements over version 1.0: Stronger authentication methods – Biometric and risk-based authentication methods replace static passwords * Improved customer experience – No need to enter a password or complete a sign-up form * Browser-based and in-application support for more devices – Enables mobile, in-app, and digital wallet payment applications


Function	Description	Sample data
StartScanningWithTimeout	Starts the “scan for nearby bluetooth devices” process. If the timeout value is 0 or a negative number, the scanning never times out. A card reader event similar to “waiting for device response” will be raised once the scanning starts. This usually means that the user needs to press the physical button in order for the card reader device to be visible to nearby scanners.	`// Indefinite scan until stopped CardknoxSDK.create().getCustomUIBluetooth().startScanningWithTimeout(0); // Scan with a timeout CardknoxSDK.create().getCustomUIBluetooth().startScanningWithTimeout(20);`
StopScanning	Attempts to stop the bluetooth device scanning process. Raises a “stop scan” card reader event. Doesn’t do anything if scanning is not in progress. If the method stops the scanning process, the SDK reports all scanned devices via a callback.	`CardknoxSDK.create().getCustomUIBluetooth().stopScanning();`
ConnectWithName	Accepts a device name. Configures the SDK to be ready to establish a Bluetooth connection with the nearby VP3300 device with a name equal to the provided name. After the call: the card reader & the app are not connected immediately but rather the SDK notifies the developer about various card reader events taking place after this method is called; such as “connecting” and “waiting for device response” if the VP3300 devices’ bluetooth is not asleep when this method is called, the card reader auto connects to the app	`String deviceName = "IDTECH-VP3300-12345"; CardknoxSDK.create().getCustomUIBluetooth().connectWithName(deviceName);`
ConnectWithAddress	Accepts a MAC address. Configures the SDK to be ready to establish a Bluetooth connection with the nearby VP3300 device with the internal MAC address equal to the provided value.	`String addr = "00:1C:97:1D:EA:50"; CardknoxSDK.create().getCustomUIBluetooth().connectWithAddress(addr);`
DisconnectFromCurrentDevice	Attempts to break the connection between the application & the card reader. If the card reader is not connected to the app, a card reader event similar to “disconnected already” is raised. Otherwise, the SDK attempts to disconnect the card reader. If successful, the “disconnected” card reader event is raised.	`CardknoxSDK.create().getCustomUIBluetooth().disconnectFromCurrentDevice();`
StartTransaction	Starts a transaction between an already connected application & the card reader. Once the transaction starts, the card reader is ready to accept cards, either via swipe, tap or insert. This method can timeout. Default value is 10 seconds. Developers can override this value via the “parameters” object.	`Activity activity = null; // Provide this TransactionParameters prms = new TransactionParameters(); prms.SetxAmount(1.23); prms.SetxInvoice("1234"); prms.SetxCommand("cc:sale"); prms.SetVP3300TransactionTimeout(13); CardknoxSDK.create().getCustomUIBluetooth().startTransactionWithArgs(prms);`
CancelTransaction	Attempts to cancel an already started transaction between the application & the card reader. If no transactions are started when this function is called, the function does not do anything.	`CardknoxSDKCustomUI customUI = null; /\* created object beforehand \*/ customUI.cancelTransaction();`