Signature Usage
There are two main methods of a cardholder’s verification in transaction processing:
- PIN code - is provided using a terminal keypad;
- Signature - is provided on a receipt or via terminals that have touch screen functionality.
In most cases, PIN code is required when making EMV-transactions, while signature is required in the following cases:
- When a payment card is swiped through a terminal;
- When an EMV card requires both PIN and signature;
- When an EMV fallback occurs and a card must be swiped;
- When a technical fallback occurs.
When a signature is provided via touch screen terminal in a context of a transaction, it gets automatically uploaded to the gateway. A signature provided with the transaction can be received within an offline callback. To receive a signature via callback, format field with a respective value has to be included in sale or sale-auth API request, as well as notifyURL field. See integration notes for more information. A signature can also be uploaded or downloaded manually. If it is necessary to re-upload a signature for a transaction (e.g. when signature upload has failed due to an error) or to upload a signature that was received without using a touch screen terminal, upload-resource API call is used. To download a signature associated with a particular transaction from the gateway, download-resource API call is used.
There are situations when a signature should be provided by a cardholder without submitting a transaction, e.g. when a cardholder has to sign a particular agreement. In such case, capture-signature API call can be used to receive a signature. When this API call is submitted, a terminal renders a respective screen requesting a signature (available for touch screen terminals only). For this operation, a provided signature is not saved automatically within the gateway. It needs to be uploaded to the gateway manually using upload-resource API call.
Valid Values for extendedAccountType
Value | Description |
---|---|
VC | Visa credit card |
VD | Visa debit card |
MC | MasterCard credit card |
MD | MasterCard debit card |
DC | Discover credit card |
DD | Discover debit card |
AC | AmEx credit card |
NC | Dinners credit card |
BD | Bank debit Card |
BC | Checking account |
BS | Savings account |
VP | Visa prepaid card |
VS | Visa fleet card |
MP | MasterCard prepaid card |
MF | MasterCard fleet card |
EF | EBT food stamp |
EC | EBT cash benefit |
GG | General gift card |
FL | Fleet One card |
GF | Fuelman or FleetWide card |
VF | Voyager fleet card |
WX | WEX fleet card |
CA | Cash (Sale-Info, Credit-Info Request) |
CK | Check (Sale-Info, Credit-Info Request) |
VE | Visa debit checking account |
VV | Visa debit saving account |
UC | UnionPay credit card |
UD | UnionPay debit card |
Submission Type
Value | Description |
---|---|
all (default) | All submission types will be exported. |
realtime | Only real-time transactions will be exported. |
batch | Only batch transactions will be exported. |
rebill | Only transactions that are in rebill status will be exported. |
retry | Only transactions that are in retry status will be exported. |
Terminal Screen Content
There are operations in the terminal API that allow a user to show custom prompt dialog messages on a terminal screen. The text shown to the cardholder is submitted to a terminal via the content field as formatted text.
Thecontent
field may include up to 10,000 characters. The number of text lines per message is not limited and in cases when a message exceeds free space available on a terminal screen, it can be scrolled using a scrollbar.
It is required to use <root> </root>
tags at the beginning and end of the text submitted in content
field.
Text within the content field can be also formatted using the following HTML tags:
Value | Description |
---|---|
<b> </b> | Bold Text |
<i> </i> | Italic Text |
<u> </u> | Underlined Text |
<p> </p> | Paragraph (block of text) |
<p/> | Line Break |
The following attributes can be added to the text above to specify additional properties of the text formatting:
- size="name of the size" - available values are xxsmall, xsmall, small, medium, large, xlarge, xxlarge;
- color="number of the color" - follow the link to review the full list of available colors.
content=<root><b><u size="large">Title of the page</u></b> <p size="medium"> Text of the agreement<p/>
agreement</p>
<p/><u>underline</u>
<p/><b>bold</b>
<p/><i>italic</i>
<p/><p color="4D" size="medium">Test Message</p></root>
officer.title
Owner |
Partner |
Director |
President |
CEO |
CFO |
Chairman |
Comptroller |
General Manager |
Office Manager |
Treasurer |
Vice President |
business.taxId
Onboarding Test Values
Test Value | Response Received |
---|---|
Final Status Testing | |
xxxxxxxx1 | A01 -- Approved |
xxxxxxxx2 | A02 -- Approved with warnings |
xxxxxxxx3 | D01 -- Declined |
Intermediate Status Testing | |
xxxxxxx0x | Use this option if you wish to test the Final Statuses above.Ex: if you use xxxxxxx01, you will get the Approved status. |
xxxxxxx1x | A12 -- In Review |
xxxxxxx2x | D02 -- Needs Correction |
Failure/Error Status Testing | |
xxxxxxx30 | D04 -- Processsor Error |
xxxxxxx40 | D03 -- Timeout Failed |
xxxxxxx50 | D03 -- Failed |
Submission Type
Value | Description |
---|---|
batch | Batch Transaction |
realtime | Real-time transaction |
Format
Value | Description |
---|---|
signature | Signature of the cardholder |
Account Type Group
Value | Description |
---|---|
PC | Payment card transaction |
Direct Debit | Direct debit transaction |
Transaction Type
Value | Description |
---|---|
<blank> | All transactions |
sale | Transaction used to withdraw a specific amount of money from a payment card or bank account |
sale-auth | Sale transaction that requires an explicit capture in order for money to be transferred to a merchant |
credit | Transaction used to deposit (return) a specific amount of money to a payment card or bank account |
credit-auth | Credit transaction that requires an explicit capture in order for money to be transferred to a merchant |
refund | Transaction used to deposit (return) a specific amount of money associated with a particular transaction |
void | Sale/credit transaction that has been reverted. No further action can be taken for a voided sale transaction |
decline | Sale/credit transaction that has been declined |
blacklist | Sale/credit transaction that has not been processed as the account is in the blacklist due to the previous hard decline |
return | Direct debit transaction that has not been honored by a bank |
chargeback | Transaction used to reverse a prior outbound transfer of funds from a customer's bank account or payment card |
reversal | Transaction used to reverse a payment card chargeback (i.e money is given back to a merchant or customer) |
split-in | Transaction used to deposit a specific amount of money provided in a split transaction; applicable for sale transactions only |
split-out | Transaction used to withdraw a specific amount of money provided in a split transaction; applicable for sale transactions only |
pull-in | Transaction used to deposit a specific amount of money based on the instructions specified in the original sale transaction that has been split; applicable for credit/chargeback/return transactions only |
pull-out | Transaction used to withdraw a specific amount of money based on the instructions specified in the original sale transaction that has been split; applicable for credit/chargeback/return transactions only |
Batch Transaction Type
Value | Description |
---|---|
S | Sale (operation used to withdraw specific amount of money from the supplied credit card or bank account) |
C | Credit (operation used to deposit (return) specific amount of money to the supplied credit card or bank account) |
D | Sale decline (sale transaction that got declined) |
X | Credit decline (credit transaction that got declined) |
E | Error (transaction that did not go through an internal validation of the gateway and was not sent for further processing) |
B | Blacklist (transaction, which has not been processed, as the account is in the blacklist due to the previous hard decline) |
N | Return (represents direct debit payment that is not honored by a bank) |
G | Chargeback (operation of reversal of a prior outbound transfer of funds from a customer's bank account or credit card) |
R | Reversal (operation where credit card chargeback is reversed - money is given back to the merchant or customer) |
U | Notice of change (represents direct debit transaction that is returned by the customer's bank as a notification that some details of the transaction were corrected) |
J | Reject (direct debit payment that is rejected by the bank due to insufficient funds or errors in payment order) |
Void Reason Code Type
Value | Description |
---|---|
CI | Customer initiated |
TR | Timeout reversal |
SM | System malfunction |
SF | Suspected fraud |
PR | Premature card removal |
CD | Chip decline |
Payment Option Type
Value | Description |
---|---|
AC | Amex |
DC | Discover Credit |
DD | Discover Debit |
MC | MasterCard Credit |
MD | MasterCard Debit |
VC | Visa Credit |
VD | Visa Debit |
BC | Checking |
BS | Savings |
NC | Dinners |
MP | MasterCard Prepaid |
MF | MasterCard Fleet |
VP | Visa Prepaid |
VF | Visa Fleet |
GG | General Gift |
FL | Fleet One |
GF | Fuel Man Fleet Wide |
VF | Voyager |
WX | Wright Express |
BD | Bank Card Debit |
FU | Fuel Lynk |
UC | China UnionPay Credit |
UD | China UnionPay Debit |
EF | Food Stamp |
EC | Cash Benefit |
Transaction Account Type
Value | Description |
---|---|
L - Allowance | Indicates that the payment is based on complimentary charge. |
K - Cash | Indicates a payment made with cash. |
H - Check | Indicates a payment made with a check. |
E - External | Indicates an external payment (PayPal, etc) |
P - Payment Plan | Indicates that the payment is a customer debt write-off due to a payment plan. |
T - Settlement | Indicates that the payment is a settlement. |
W - Writeoff | Indicates a revenue offsetting transaction which means that the revenue had never been collected and the transaction was written off the books. |
AC | Amex |
DC | Discover Credit |
DD | Discover Debit |
MC | MasterCard Credit |
MD | MasterCard Debit |
VC | Visa Credit |
VD | Visa Debit |
BC | Checking |
BS | Savings |
NC | Dinners |
MP | MasterCard Prepaid |
MF | MasterCard Fleet |
VP | Visa Prepaid |
VF | Visa Fleet |
GG | General Gift |
FL | Fleet One |
GF | Fuel Man Fleet Wide |
VF | Voyager |
WX | Wright Express |
BD | Bank Card Debit |
FU | Fuel Lynk |
UC | China UnionPay Credit |
UD | China UnionPay Debit |
EF | Food Stamp |
EC | Cash Benefit |
Subscription Status
Value | Description |
---|---|
C | Current (default) - Indicates that the payment plan is active. |
D | Deferred - No invoice will be generated in the upcoming billing associated with a payment plan. |
F | Freeze - Indicates that the payment plan is terminated. |
N | Cancelled - Indicates that the payment plan is cancelled. |
E | Expired - Indicates that all payments for the payment plan have concluded and the plan no longer is being billed. |
U | Unbilled - Indicates that no billing occurred since the payment plan was created. |
P | Paused - Indicates that the payment plan is on hold. |
Pending Adjustment Type
Value | Description |
---|---|
F | Freeze |
C | Cancel |
P | Pause |
Subscription Type
Value | Description |
---|---|
F | Fixed Indicates a certain payment amount is agreed upon, and the number of payments is limited (fixed) by the agreement/contract. For example, $10 per month for 12 months. If this option is used, you must use the length parameter in the request. |
P | Perpetual (default) - Indicates that the payment plan is agreed upon to be paid until the agreement is cancelled. |
Billing Cycle Type
Value | Description |
---|---|
W | Weekly |
M | Monthly |
Q | Quarterly |
S | Semi-Annually |
A | Annually |
Billing Cycle Length
Value of billingCycleType |
Maximum length value allowed |
---|---|
W - Weekly | 153 |
M - Monthly | 36 |
Q - Quarterly | 12 |
S - Semi-Annually | 6 |
A - Annually | 3 |
~create
Transaction Type
Value | Description |
---|---|
RI - Invoice | Represents an invoice (recording of a customer's debt to a merchant) |
RC - Credit | Represents a transaction opposite to an invoice (reduction in a customer's debt to a merchant) |
RF - Service Fee | Represents generic fee applied to the customer's account |
~process
Transaction Type
Value | Description |
---|---|
AP - Payment | Represents a real-time payment collected on the customer's account |
AR - Refund | Represents a partial or a full reversal of a previous payment |
~reverse
Transaction Type
Value | Description |
---|---|
RR - Reversal | Represents full reversal of an existing invoice |
AV - Void | Represents void of an existing payment |
AX - Cancel Refund | Represents a reversal of a previously posted refund. |
RX - Cancel Credit | Represents a reversal of a previously posted credit. |
Transaction Type
Value | Description |
---|---|
RI - Invoice | Respresents an invoice (recording of a customer's debt to a merchant) |
RC - Credit | Represents a transaction opposite to an invoice (reduction in a customer's debt to a merchant) |
RR - Reversal | Represents full reversal of an existing invoice |
RF - Service Fee | Represents generic fee applied to the customer's account |
RL - Late Fee | Represents a fee applied because of a late payment |
RA - Access Fee | Represents a fee applied to the customer's account because access to restricted digital assets (paperless copies of contracts) was granted |
AP - Payment | Represents a real-time payment collected on the customer's account |
AV - Void | Represents void of an existing payment |
AR - Refund | Represents a partial or a full reversal of a previous payment |
AC - Claim | Represents a batch payment, collected on the customer's account. It is conceptually similar to real-time payment, but has a likelihood of subsequent decline within three-day period (on average) after its effective date (due to batch processing and reprocessing). |
AD - Decline | Represents a decline of payment, either real-time or batch |
AG - Chargeback | Represents a credit card chargeback of a previously processed payment or claim. |
AA - Adjustment | Represents automatic write off of the existing debt due to the age of this debt. |
AX - Cancel Refund | Represents a reversal of a previously posted refund. |
RX - Cancel Credit | Represents a reversal of a previously posted credit. |
AS - Chargeback Reversal | Represents a reversal of a previously posted chargeback. |
RO - Collections Fee | Represents a fee applied to an account when it is sent to a 3rd party for collections. |
RN - Reinstatement | Represents a fee applied to an account when it is reinstated following 3rd party collections. |
Processing Info
Value | Value or Format | Description |
---|---|---|
id | Int (20) | Identifier of the object used for references; auto-incremented integer value. |
createDate | Date yyyy-MM-dd | Date when the record was created. In the response, the date is returned with hour, minute, and second values as well, formatted like yyyy-MM-dd HH:mm:ss |
holderName | String (150) | Name of bank account or credit card holder. |
accountNumber | String (20) | Credit card or bank account number. |
accountAccessory | String (10) | Card expiration date or bank routing number. This field is required even if it is used with a token . |
token | String (40) | Token associated with the payment card or bank account. Can be used to process future transactions. |
street | String (128) | The street address of the card holder. |
city | String (50) | The city of the card holder. |
state | String (2) | The state of the card holder. |
zipCode | String (15) | The zip code of the card holder. |
phone | String (20) | Phone number associated with a payment card or bank account holder. |
String (100) | Email associated with a payment card or bank account holder. | |
gatewayTransactionId | String (20) | Identifier of the transaction in the gateway. |
approvalCode | String (100) | Authorization number given by a cardholder's bank account. Often shown on a credit card receipt. |
responseDate | yyyy-MM-dd hh:MM:ss | The date when the gateway received the response for processing the transaction. |
responseCode | String (5) | Response code returned for the transaction. See Response Codes for more information. |
responseMessage | String (255) | Response message returned for the transaction. See Response Codes for more information |
address | String(100) | Address associated with a payment card or bank account holder. The value is a concatenation of the street1 , street2 , city , state , zipCode and countryCode field values. |
Affiliate Minimum Fields
The following are the minimum required data fields to create/onboard a merchant of type affiliate. You will still need to includeAuthentication and Context
and Appearance and Control
sections.
Value | Description |
---|---|
officer.firstName | First name of business owner |
officer.lastName | Last name of business owner |
officer.street1 | Line 1 of owner's address |
officer.city | City of owner's address |
officer.state | State of owner's address |
officer.zipCode | Zip code of owner's address |
officer.phone | Phone number of owner |
officer.email | Email address of owner |
officer.birthDate | Birth date of owner (yyyyMMdd) |
officer.socialSecurity | Social Security number of owner |
officer.countryCode | Country Code for owner's address |
officer.stakePercentage | Percentage of officer ownership in the company |
business.businessName | Common business name |
business.street1 | Line 1 of the business address. |
business.city | City of business address |
business.state | State of business address |
business.zipCode | Zip code of business address |
business.taxId | Tax ID of the business of SSN of the owner |
business.ownershipStructureType | Business structure. See business.ownershipStructureType in the general onboarding section for an enumerated list of values |
deposit.bankName | Bank name of deposit account |
deposit.holderName | Holder name of the deposit account |
deposit.accountType | Type of deposit account: S = Savings, C = Checking |
deposit.routingNumber | Routing number for deposit account. If this is incorrect the affiliate will not receive deposits |
deposit.accountNumber | Deposit account number. If this is incorrect the affiliate will not receive deposits |
Transaction Status
Value | Description |
---|---|
N | Pending; indicates the transaction is part of a batch that has been submitted and is pending closure of that batch. |
P | Processed; indicates that the transaction is processed |
R | In Rebill; indicates that the transaction is in rebill |
C | Cancelled; indicates that transaction processing is cancelled |
Format
Value | Description |
---|---|
P | Indicates that tax information is provided |
N | Indicates that tax information is not provided |
E | Indicates that payment card or bank account holder is exempted from paying taxes |
Format
Value | Description |
---|---|
online | Indicates that the transaction is processsed online |
offline | Indicates that the transaction is processed offline, i.e. it is pre-processed (in case of swiped transactions) or it has been approved by the chip (in case of EMV transactions) |
holderVerificationModeType
Value | Description |
---|---|
NN | No verification |
II | Ink Signature verification |
DD | Digital signature verification |
PP | PIN verification |
PI | PIN and ink signature verification |
PD | PIN and digital signature verification |
queueingMode
Value | Description |
---|---|
R | Required, indicates that the report is put in the queue. |
A | Allowed; indicates that the report is put in the queue if not generated within three minutes. |
N | Not Allowed; indicates that the report is not allowed to be put in the queue. |
statementBasis
Value | Description |
---|---|
depositDate | Indicates that the report will include deposit statements for the selected month. |
endDate | Indicates that the report will include statements in Posted or Adjusted status generated within the selected month. |
statement.type
Value | Description |
---|---|
Deposit | Indicates that a deposit statement has been generated. |
Reconciliation | Indicates that a reconciliation statement has been generated. |
settlementStatus
Value | Description |
---|---|
settled | The transactions with close cycle are available in the report |
unsettled | The transactions with no close cycle are available in the report |
all | The transactions with close cycle and without close cycle are available in the report |
reportBasis
Value | Description |
---|---|
authorizationDate | Authorization date will be used as the basis for transaction selection. |
settlementDate | Settlement date will be used as the basis for transaction selection. |
Transaction List Conditional Parameter Usage
Parameter | If fromDate/toDate are used |
If transactionId is used |
If batchId is used |
---|---|---|---|
fromDate |
R | N | N |
toDate |
R | N | N |
accountId |
O | N | N |
batchId |
N | N | R |
status |
O | N | O |
type |
O | N | O |
transactionId |
N | R | N |
settlementStatus |
O | O | O |
Split Subrecord
Name | Value or Format | Description |
---|---|---|
accountId | Reference | Reference to an account that has received funds because of a split payment processing. |
amount | Integer | Expressed as a fixed amount or a percentage rate that is going to be split to a third party.
Note: Amount is expressed in cents. Rate should be preceded by an
R and is submitted as an integer value with four decimal places. See Split Transactions for more information. |
Transaction Status Type
Value | Description |
---|---|
N | Pending - indicates that the transaction is waiting for approval within a batch file. |
P | Processed - indicates that the transaction has been processed. |
C | Cancelled - indicates that the transaction was cancelled. |
R | In rebill - indicates that the transaction was submitted for retry. |
Valid Values for transactionCategoryType
Value | Description |
---|---|
B | Bill payment. |
R | Recurring. |
I | Installment. |
H | Healthcare. |
Valid Values for cscIndicator
Value | Description |
---|---|
P | Indicates that CSC is provided in the API request. |
N | Indicates that CSC is not provided in the API request. |
I | Indicates that CSC is illegible. |
X | Indicates that CSC is not present on the payment card. |
Valid Values for accountType
R | Payment Card (debit or credit) |
S | Bank savings account (ACH) |
C | Bank checking account (ACH) |
Valid Values for accountType
VX | Visa Credit, Visa Debit, Visa Prepaid, Visa Fleet |
MX | MasterCard Credit, MasterCard Debit, MasterCard Prepaid, MasterCard Fleet |
DX | Discover Credit, Discover Debit |
AX | Amex |
BX | Includes Checking and Savings account types |
UX | China Union Pay Credit, China UnionPay Debit |
XX | All other account types |
transactionIndustryType
Credit Card Values | |
DM | Use DM in situations where the card information is communicated by the cardholder to the merchant over the phone, online or some other method where the cardholder is not physically present. |
RE | Use RE in situations where the cardholder is present and the transaction is being processed through a physical card reader. |
RS | Restaurant |
LD | Lodging |
PT | Petroleum |
Direct Debit/ACH Values | |
CCD | Corporate Credit or Debit is used when charging a corporate bank account. |
C21 | Check 21 |
PPD | Prearranged Payment and Deposit is used when charging an individual consumer bank account. |
POP | Point of Purchase entry. |
TEL | Telephone initiated transactions, used when the ACH transaction is initiated over the phone with the account holder. |
WEB | WEB transactions occur online, via the internet, or mobile device, between a business entity and a consumer. NACHA rules require merchants running ACH transactions of type WEB to run an account-verification prior to the bank account numbers first use by the merchant. The purpose is to verify that the account number to be used is a legitimate, open account. Once a bank account number has been verified subsequent transactions on an existing ACH account (account on file) do not require account-verification . Please see Account Verification for more details. |
Subrecord Format
A subrecord is an entry within a primary record. Usually, the primary record has a list of subrecords. The following subrecords are currently supported within the system:
items
(for transactions with items);extraCharges
(for lodging and car rental transactions);petroleumItems
(for petroleum transactions);
The following formatting rules are applied to the fileds with subrecords:
- Each subrecord must be enclosed by brackets
- An equal sign (=) is used to separate a field's name and value and a semicolon (;) is used to separate fields.
- To submit multiple subrecords list them one after another.
For example, if the following item information is needed to be submitted:
Item 1:- code=001
- quantity=1
- description=t-shirt
- totalAmount=50000
- code=002
- quantity=1
- description=jeans
- totalAmount=70000
The items
field value must be formatted as shown below:
items=(code=001;quantity=1;description=t-shirt;totalAmount=50000)(code=002;quantity=1;description=jeans;totalAmount=70000);s
Cross-reference Fields
If needed you have the ability to specify values for certain parameters that can be used to cross-reference information between your system or platform and Zift.
In some cases, an external system is going to have two different identifiers for a given transaction: one, shown to the end user on the UI, and the other one a system identifier (very often a database-generated artificial ID).
In such cases, the user-visible ID should be submitted in the transactionCode
or customerAccountCode
fields while the internal ID (artificial ID) should be submitted in the transactionInternalCode
or customerAccountInternalCode
fields respectively.
Valid Values for merchantProfile
Value | Description |
---|---|
MSMMM (default) | Represents a merchant with multiple locations. Underwriting is done with a single tax ID. Processing is done with multiple MIDs (one MID per descriptor). Money is deposited in a separate bank account for each merchant account. Recurring fees are charged only once. |
SSSSM | This is our most typical scenario. Represents a merchant with a single location with a single tax ID, processing and deposit settings. Recurring fees are charged only once. |
MSSSM | Represents a merchant with multiple locations. Underwriting is done with a single tax ID. Processing is done with a same MID. Money is deposited in a same bank account for all locations. Recurring fees are charged only once. |
MMMMM | Represents a merchant with multiple locations. Underwriting is done with a separate tax ID for each merchant account. Processing is done with multiple MIDs (one MID per descriptor). Money is deposited in a separate bank account for each merchant account. Recurring fees are charged only once. |
MMMMA | Represents a merchant with multiple locations. Underwriting is done with a separate tax ID for each merchant account. Processing is done with multiple MIDs (one MID per descriptor). Money is deposited in a separate bank account for each merchant account. Recurring fees are charged per each merchant account. |
MSMMA | Represents a merchant with multiple locations. Underwriting is done with a single tax ID. Processing is done with multiple MIDs (one MID per descriptor). Money is deposited in a separate bank account for each merchant account. Recurring fees are charged per merchant account. |
MSSMM | Represents a merchant with multiple locations. Underwriting is done with a single tax ID. Processing is done with a same MID. Money is deposited in a separate bank account for each merchant account. Recurring fees are charged only once. |
MSSMA | Represents a merchant with multiple locations. Underwriting is done with a single tax ID. Processing is done with a same MID. Money is deposited in a separate bank account for each merchant account. Recurring fees are charged per each merchant account. |
MSMSM | Represents a merchant with multiple locations. Underwriting is done with a single tax ID. Processing is done with multiple MIDs (one MID per descriptor). Money is deposited in a same single bank account for all locations. Recurring fees are charged only once. |
Valid Values for merchantType
Value | Description |
---|---|
M (default) | Merchant |
A | Affiliate Note: Affiliates can only receive funds. Affiliates cannot process transactions. |
Valid Values for merchantCreationPolicy
Value | Description |
---|---|
A (default) | Merchant is created on approval only.
|
R | Merchant is created on approval or in review .
|
Valid Values for isEmbedded
Value | Description |
---|---|
0 | (default) Show page header and footer |
1 | hide page header and footer |
Valid Values for returnURLPolicy
Value | Description |
---|---|
page | (default) When the onboarding process is completed a button is displayed linking to the returnURL. |
redirect | When the onboarding process is completed the user is automatically taken to the returnURL. |
Valid Values for notificationPolicy
Value | Description |
---|---|
A | (default) Indicates that all notifications are enabled. |
X | Indicates that all notifications are disabled. |
Valid Values for business.ownershipStructureType
Value | Description |
---|---|
C | Public Corporation |
GA | Government Agency |
GP | General Partnership |
LLC | Limited Liability Company |
NP | Nonprofit Corporation |
PC | Private Corporation |
SP | Sole Proprietorship |
Valid Values for deposit.accountType
Value | Description |
---|---|
C | Checking Account |
S | Savings Account |
Onboarding FAQ
To help the government fight financial crime, Federal regulation 31 CFR 1010.230 requires certain financial institutions to obtain, verify, and record information about the beneficial owners of legal entity customers. Legal entities can be abused to disguise involvement in terrorist financing, money laundering, tax evasion, corruption, fraud, and other financial crimes. Requiring the disclosure of key individuals who own or control a legal entity (i.e., the beneficial owners) helps law enforcement investigate and prosecute these crimes.
A beneficial owner is defined as one of the following:
- Any individual who owns directly or indirectly, 25 percent or more of the equity interests of the legal entity registering for a merchant account; AND/OR
- An individual with significant responsibility for managing the legal entity (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer).
For more information on Beneficial ownership please see the links below:
- https://www.fincen.gov/resources/statutes-and-regulations/cdd-final-rule
- https://www.govinfo.gov/content/pkg/FR-2016-05-11/pdf/2016-10567.pdf
- https://www.fincen.gov/sites/default/files/2018-04/FinCEN_Guidance_CDD_FAQ_FINAL_508_2.pdf
Why are Social Security Numbers and/or Tax IDs required?
This information is required to verify the identity of the beneficial owners registering for the account and to verify the EIN of the legal entity to comply with IRS regulations.
What if there are no beneficial owners that meet the 25% ownership criteria?
If there are no owners with 25% or greater equity in the legal entity only the officer section needs to be completed with information on an individual who has significant responsibility for managing the legal entity.
What if the merchant is a sole proprietorship?
If the merchant is a sole proprietorship only the officer section needs to be completed.
Allowed Characters for business.businessName
Alpha | Aa-Zz |
Numeric | 0-9 |
Space | |
Comma | , |
Period | . |
Fwd Slash | / |
Dash/Hyphen | - |
At Symbol | @ |
Asterisk | * |
L/R Parentheses | () |
Apostraphe | ' |
Pound Sign | # |
Underscore | _ |
Plus | + |
Allowed Characters for business.legalName
Alpha | Aa-Zz |
Numeric | 0-9 |
Space | |
Comma | , |
Period | . |
Fwd Slash | / |
Dash/Hyphen | - |
At Symbol | @ |
Asterisk | * |
L/R Parentheses | () |
Apostraphe | ' |
Pound Sign | # |
Underscore | _ |
Plus | + |
Allowed Characters for deposit.bankName
Alpha | Aa-Zz |
Numeric | 0-9 |
Space | |
Comma | , |
Period | . |
Fwd Slash | / |
Dash/Hyphen | - |
At Symbol | @ |
Asterisk | * |
L/R Parentheses | () |
Apostraphe | ' |
Carrot | ^ |
Underscore | _ |
Equals Sign | = |
Acute/Backtic | ` |
Partial Authorizations
During the sale authorization process (sale-auth
and sale
operations) when the full transaction amount is not available on the card partial authorization can occur if this feature is enabled (debit cards and gift cards only). Instead of getting a decline (Insufficient funds), you will receive a partial approval for the amount of available funds.
The authorized amount will be present in the response message within the amount
field while the originally requested authorization amount will be present within the originalAmount
field. Optionally, the balance
field may be returned in the response (depending on the card issuing bank) indicating the remaining balance on the card.
If a partial authorization is indicated as not supported on a client's side (isPartialAuthorization = 0
), then the authorization will be reversed and a decline code (D03, Insufficient funds) will be returned.
accountData Usage
1) for payment cards:
- track data (unencrypted/encrypted)
- EMV data (unencrypted/encrypted)
- MICR data
The system supports submission of track data in two ways - encrypted and unencrypted. Both are submitted within accountData field. When the accountData field contains unencrypted track data, it has to be encoded before it is sent to eliminate any issues with special characters. Use standard URL encoding procedure for that.
If track data is encrypted, generally, encoding is not required (but it may be needed if non-alpha-numeric characters are present). The system accepts track data encrypted by both external and internal encryption methods. If an internal encryption method is used, the system will decrypt track data with a key registered within the system and submit decrypted value for processing. If an external encryption method is used, the data will be passed to the processor as it was received by the gateway i.e. without modifications. To identify that submitted data is encrypted, its value has to be preceded by tilde sign (~). Otherwise, the system assumes that data is unencrypted. For example, ~021301000F3D0000%*4111.....
Currently, three encryption algorithm are supported for track data encryption:- TDES - a symmetric algorithm that requires one key for both encryption and decryption. Used by ID Tech devices.
- AES - a symmetric algorithm that requires one key for both encryption and decryption. Used by ID Tech devices.
- RSA - an asymmetric algorithm that requires two different keys for encryption (public key) and decryption (private key). Used by a native terminal application.
EMV Data
When the accountData field contains unencrypted EMV data, its value has to be preceded by exclamation mark (!). For example, !4F07A00.....To identify that submitted EMV data is encrypted, its value has to be preceded by exclamation mark and tilde sign (!~ or ~!). For example, !~021301000F3D0000%*4111.....
EMV processing requires various tags to be included into receipt. These tags are also included in account data associated with a particular EMV card. Tags in transaction response come in random order, so the format can start from any available tag. Account data in transaction response includes both required and optional tags. The tag 0x91 is a required tag. It is always present in the transaction response. The tag 0x8A allows to check the status of the transaction. It is optional and whether it is present or not in the response depends upon the processor. Full list of EMV tags is available here.
Canada EFT Integration Notes
Additionally, Payments Canada network rules requires all businesses that process EFT transactions to obtain a Pre-Authorized Debit Agreement (PAD) from their clients prior to processing any EFT transactions through the network for the client.
You must incorporate our sample PAD agreement, or a similar version based on your business requirements, as long as they adhere to the Payments Canada network rules, into your workflow.
Version 9.2.7
Sandbox: 3/11/2025
Production: 4/8/2025
Transaction API
- Duplicated Transactions on S20 or 302 response codes.(537)
Fixed an error that rarely caused transactions to be duplicated if the system responded with an S20 responseCode or gateway 302 response code. - Expiration date on API Requests(1430)
If an invalid/past expiration date is provided on an API request, the request will result in an error.
Onboarding API
- Maximum Estimate Values(937)
The estimate fields maximum value has been increased to two billion (2000000000000).
Version 9.2.6
Sandbox: 12/3/2024
Production: 12/20/2024
Merchant Console
- Password Change Prompt(1290)
Corrected the text prompt when changing passwords to show 11 character minimum as the requirement rather than 8 characters.
- Statements Tab Display(1125)
Fixed a display error on the statements tab to occasionally not show all the statements available for download or showing statements out of order.
Statements
- Bank Account on Monthly Statement(765)
Fixed an issue causing the wrong bank account to display on the monthly statement for merchants who have a secondary fee-only bank account set up. The monthly statement will now properly show the fee-only bank account and deposit statements will show the deposit bank account.
Transaction API
- Duplicated Transactions on S20 or 302 response codes.(537)
Fixed an error that rarely caused transactions to be duplicated if the system responded with an S20 responseCode or gateway 302 response code. - Changes in Void Behavior(754)
We've updated our system to handle cases where the issuing bank declines a void request. Previously if an issuing bank declined a void request our system would respond withresponseCode=S26
and the void would fail. Going forward, if a void is declined by the issuing bank our system will prevent the transaction from settling, although the initial authorization will still remain. For successful void requests we now have two response messages:
responseCode=A03
- "Void Posted (Auth Reversed)": The void is processed, and the authorization is reversed.responseCode=A06
- "Void Posted (Auth Not Reversed)": The void is processed, but the authorization is not reversed. In this case, the pending charge on the customer's card will be removed, but may take longer to fall off than if the authorization was reversed. This still prevents the need for a refund after settlement.
Onboarding API
- Apostrophe Characters(1103)
Corrected the validation for the onboarding API to properly allow all apostrophe characters. EX:'
,ʼ
,`
Webhooks
-
ACH Notification of Change (NOC) Handling Updates(1103)
We've upgraded our NOC webhooks to deliver more detailed and actionable NOC information. For a comprehensive understanding of NOCs please refer to our help article.
Account Number Updates- Token Management: When an account number is updated, a new token is generated.
- Webhook Details:
- Integrators can access the new token via the
tokenUpdated
field in the NOC webhook. - The original token will be available in the
originalToken
field for reference.
- Integrators can access the new token via the
- NACHA Compliance: The original token will be disabled to prevent outdated account number usage.
- Recommended Action: Replace the current token with the updated token for future transactions.
- The updated routing number will be available in the NOC webhook under the
accountAccessoryUpdated
field. - Recommended Action: Store the updated routing number for use in future transactions as the value in the
accountAccessory
field.
- The updated account type (checking of savings) will be provided in the NOC webhook via the
accountTypeUpdated
field. - Recommended Action: Store the updated account type for future transactions as the
accountType
.
Version 9.2.5
Sandbox: 10/15/2024
Production: 11/12/2024
Merchant Console
- iPad Card Number Error(354)
Fixed an issue that caused the card number field to be pre-filled with 9s that could not be removed on iPads, preventing the transaction from completing.
- Login Exception Page(475)
Fixed an issue causing the merchant console login page to show an exception/error occasionally.
Statements
- Duplicated Stats(497)
Fixed an issue that occasionally caused statistics to be duplicated on statement PDFs.
- Franchise Fee Column Name Changed(--)
Changed the column name for Franchise Fees to Platform Fees.
Hosted Payment Pages
- CVV Code for AMEX(601)
Fixed an error causing Amex 4 digit CVV codes to not allow a hosted payment page to complete.
Transaction API
- Removal of failureCode/failureMessage fields(--)
ThefailureCode
andfailureMessage
fields will officially removed from the transaction API. See the deprecation notices tab of the changelog for details.
Recurring Billing API
- Chargeback Allocations on invoices(499)
Fixed an issue causing chargebacks to deallocate funds on the original invoice, causing the customer record to have an invalid balance.
Version 9.2.4
Sandbox: 7/31/2024
Production: 8/13/2024
Terminals
- Signature on Receipts(81)
Receipts will now show on the receipt regardless of the entry mode for the transaction. (Swipe, contactless, etc.)
Merchant Console
- Unified Customer Search(122791)
Made improvements to the search feature on the customers tab. You may now search immediately for customer name, organization, or email address.
Statements
- Deposit Statement Flat Fees(814)
The flat fee amount on the deposit statement has been fixed to show the correct amount.
- Monthly Statement Fee Amounts(777)
Fixed an issue that would intermittently cause some fees to not show properly on the monthly statement.
Hosted Payment Pages
- Enhanced Error Clarity(--)
Errors will now be displayed on the confirmation screen for Hosted Payment Pages invoked via the invoicing feature.
Version 9.2.3
Sandbox: 3/26/2024
Production: 5/14/2024
Transactions
- Dates on Transaction Receipts(478)
The date on transaction receipts has been fixed to correctly show the date the transaction took place.
Terminals
- D36T Error Codes(386009)
Fixed an issue that would sometimes cause a terminal to respond with a D36T Decline error code when the transaction was successfully processed. Now the D36T error code will be returned only if the transaction also fails to run.
Admin Console
- Franchise Fees removal(602121)
The admin console will now allow for franchise fees to be removed properly.
- Merchant Configuration (Tax Rate)(358013/71)
Merchants can now be configured to have a default tax rate from within the Admin UI. This tax rate is taken into consideration when franchise fees (if configured) are calculated.
Merchant Console
- Sale-Auth Display(107)
Fixed an issue causingsale-auth
calls to be showing aspayment request
in the UI.
- Invalid Token Error(--)
Fixed an issue on the New Sale form causing an invalid token to respond with an S20 error code instead of the more accurate F22 error code.
Statements
- Monthly Statement Franchise Fee(--)
The Monthly Statement has been updated to include a subsection for Franchise Fees.
Real-Time API
- transaction-list and transaction-summary-by-day calls added to the Real-Time API(--)
Thetransaction-list
andtransaction-summary-by-day
calls have been added to the Real-Time API.
Billing API
- transaction~process Invoice List(358013/71)
Thetransaction~process
call has been updated to include a parameter calledinvoiceIds
which allows multiple invoice IDs to be passed. EX:{ invoiceIds:"1234,5678,9101" }
The response will contain the allocations to the specified invoices. EX:{ allocatedAmounts:"2000,2000,1400" }
.
- transaction~create Tax Amount(358013/71)
Thetransaction~create
call has been updated to include a parameter calledtaxAmount
which allows a tax amount to be specified. EX:{ taxAmount:1050 }
The response will also contain thetaxAmount
.
Reporting API
- Batch ID added to Deposit List(907427)
The deposit list call has been updated to include thebatch.id
field.
- transaction-list not returning correct results when using recordsLimit(757142)
Thetransaction-list
call has been fixed to contain the correct amount of records when using therecordsLimit
parameter.
- transaction-list fromDate and toDate adjustments(424738)
Thetransaction-list
call has been updated to allow usage of thefromDate
andtoDate
parameters more intuitively. For example, specifying afromDate
of20240501
will yield all results from May 1st, 2024 and forward.
- transaction-list accountType parameter updates(839478)
TheaccountType
parameter has been updated for thetransaction-list
call. See Transaction List for more details.
- transaction-list terminalId parameter(839478)
TheterminalId
parameter has been added for thetransaction-list
call. See Transaction List for more details.
- Merchant Statement accountId adjustments(712394)
Themerchant-statement
call has been updated to allow usage of either the Merchant ID or Account ID (83000, or 83001) as a valid value for theaccountId
field.
Webhooks
- Enhanced Response Parsing(--)
Webhook response parsing has been updated to allow either a string or integer for thenotificationId
parameter. Examples of both formats:{"notificationId":272638}
and{"notificationId":"272638"}
Version 9.2.2
Sandbox: 2/13/2024
Production: 3/19/2024
Terminals
- Company Name on idle screen(--)
The Company name on the terminal idle screen should now properly be shown as 'Thank you for choosingcompanyName
.'
Merchant Console
- Holder Name Display(--)
TheholderName
field should contain more accurate values on the UI, transaction-list, and transaction summary locations for payments made with contactless cards
- Non-Financial Transaction Filter(--)
Non-financial transactions such as chargebacks, authorizations, etc. can now be filtered on the merchant console using the "Transaction Type" filter.
- Currency Display(267843)
Fixed an issue causing Canada transactions to be shown in USD. They should now be shown in the proper currency code, CAD.
Users
- S20 Error for expired Users(851156)
Fixed an issue causing expired users to receive a generic S20 error code instead of an error referencing the expired status of the user.
- User Scope(670650)
Users should now properly be able to see all reseller/merchant level accounts their user is assigned to see.
Statements
- Updated values for Fee fields(--)
Statements and deposit detail forms have been updated to contain a more clear representation of fees charged.
Hosted Payment Pages
- Line break characters in the Street field(--)
Hosted Payment Pages have been fixed to properly process the transaction if a line break character is found within the street field.
Billing API
- Unexpected Field Name Change in Payment Option~find response (token/tokenCode)(601075)
Thetoken
andtokenCode
fields will now contain the payment method's tokenized value.
Version 9.2.1
Sandbox: 11/21/2023
Production: 12/12/2023
Transaction API
- Capture call returns amount(--)
Thecapture
API call now will return theamount
from the originalsale-auth
request as part of its result set.
- Deprecating the
failureCode
andfailureMessage
fields.(290625)
ThefailureCode
andfailureMessage
fields are being deprecated. Please see the deprecation notices tab found at changelog for more details.
Terminals
- E24 Error Message(--)
The E24 error message has been changed from "Referenced Terminal is not found within Cloud or not accessible to the current user" to "Referenced Terminal is offline or not accessible to the current user."
Account Updater
- Account Updater Logic Improvements(512028)
The account updater logic has been changed. Now the current payment method is updated if only the expiration date has been updated, and create a new payment method if the account number is updated.
Merchant Console
- Invoicing(580260)
Added functionality to create a payment request and send an invoice with a payment link to customers.
- Card Number Validation Improvements(--)
The card number field will now allow card numbers with lengths of 19 numbers to accommodate certain card types.
- Transaction Summary(--)
It is now possible to view non-financial transactions on the transactions tab of the merchant console.
- Device Summary(--)
The Device Summary tab has been updated to include more information for each device.
- User Interface Improvements(--)
Numerous elements of the user interface have been improved for clarity.
- Disabled merchant selectors when viewing the customer details page.
- Renamed sections and buttons on the Billing Activity Summary form and updated the section expansion.
- Display a menu with items and text corresponding to each form when clicking the three dots at the end of records. Enlarged the close button.
- Modified logo display, added a scrolling "Processing" indicator during data loading on forms, and improved item navigation in the left menu.
- Save Button(--)
When creating a new payment method for a bank account, the 'save' button will no longer be clickable unless all required fields are filled.
Fees
- Franchising Fees(--)
Added functionality to allow for franchise fees.
Hosted Payment Pages
- Convenience Fees(916805)
Convenience Fees now work properly when Hosted Payment Pages are used to process the transaction.
- Added business name to the payment page(--)
Functionality has been added to display a text box saying 'Payment for {{business name}}' on Hosted Payment Pages by passingM
in thepageFormat
parameter.
- Mobile Display(--)
Mobile view of Hosted Payment Pages has been improved.
- Proxy Number Caching(--)
An issue causing the proxy number to be cached if an account number is deleted then re-entered has been fixed.
- Continue Button Disabled Error(--)
An issue causing the continue button to be disabled and unable to be clicked has been fixed.
Onboarding API
- Validation of the business.descriptorPhone Field via UI and API(--)
Added correct validation for Saudi Arabia phone numbers.
Version 9.1.7
Sandbox: 9/5/2023
Production: 10/3/2023
Billing API
- nextBillingDate functionality fixes(767890)
ThenextBillingDate
parameter can now be modified if the subscription status is current, unbilled or deferred. You cannot modify thenextBillingDate
when a subscription is expired, cancelled, frozen, or paused.
Merchant Console
- Fixed Masking of Card Number(--)
The card masking has been fixed for the Card Number field in the user interface.
- Home Display Improvements(336131)
The merchant console home screen has been improved.
- Reseller level view of users(595806)
The user list view has been updated for reseller level users. Reseller users can now view all users underneath their reseller.
- Users view improvements(395251)
Merchant console users will be able to see other merchant console users that share access to the same merchant accounts. For example, a console user attached to multiple accounts can now view other console users associated with those merchant accounts.
Statements
- Clarifying note for large reports(967165)
Statements with more than 400 contributing transactions will now include this note: "Only 400 transactions are listed in this report. To see the entire list of transactions please log into web portal."
Version 9.1.6
Sandbox: 7/11/2023
Production: 8/15/2023
Webhooks
- Webhook JSON response syntax fixed(943472)
Responses will now be parsed correctly to acknowledge webhook notification receipt
Transaction API
- Canadian Credit Card Payment Option(804655)
US and Canadian based Merchant Accounts can now add a Canadian Credit Card payment option.
Billing API
- Modify subscription error message(542187)
Users will now be able to modify or cancel subscriptions recently unfrozen or unpaused.
Merchant Console
- Reprocess Transaction Button(899085)
The options for a transaction will now include a 'reprocess' option.
- Error Downloading Monthly Statements(394249)
Users will no longer experience an error message when attempting to download monthly statements.
- Displaying Active Payment Options(627141)
When creating a new payment for a customer, the options will now only contain active payment options.
- Username/Password Invalid in Safari Error(886900)
The merchant console will now allow users to access it via Safari without errors when logging in.
- New User ZIP Validation(--)
When creating a new user for the console or API, the ZIP code will now be validated properly to ensure the user is in the correct country.
Statements
- Corrected Statement Totals(689394)
Statement totals will now properly match the totals found on the merchant console.
Version 9.1.5
Sandbox: 5/25/2023
Production: 6/20/2023
General Changes
- Expired API Users Error Message(--)
When running API requests using a deactivated service user you will now receive ‘L01 Username+or+password+is+invalid’.
Billing API
- Paused subscription error message(--)
Changed the description for the error message to ‘V32 Unable to complete action. Subscription is already in paused state.' when attempting to modify a subscription in a paused state.
- Ampersand in organization name(931252)
The ampersand&
character is now allowed in the organization name on customer records.
Merchant Console
- Removal of New Customer/Plan buttons for Read-only access(--)
The merchant console buttons for the new customer and new plan have been removed for users with read-only access.
- Error on New Sale Form(--)
The sale form error that occurred when switching payment methods has been fixed.
- Error downloading ACH Statements(--)
Admin users in the console will no longer receive errors when attempting to download ACH statements.
- Long loading times for deposit statement downloads(--)
Improved the loading time for downloading deposit summaries.
- Deposit list form(433740)
The deposit list PDF export button is now working properly.
- Customer history error(--)
Fixed the error that occurred when loading the customer history section of the Customer Details page.
Convenience Fees
- Direct Debit (ACH) Errors(364439)
ACh transactions will now properly charge the convenience fee through the fee processor account.
Terminals
- New Terminals(--)
Added support for two new terminal types, the P2 SE and P2 SmartPad.
Version 9.1.4
Sandbox: 3/28/2023
Production: 4/25/2023
General Changes
- Webhooks(545952)
Web hooks have been added to specific Transaction, Reporting, and Recurring Billing API calls
Billing API
- Freezing Subscription Error(154948)
In some instances the system would response with an error when attempting to freeze a previously frozen subscription. This has been fixed.
Merchant Console
- Transaction ID filter(512225)
The merchant console would not allow you to filter your transaction searches by transaction ID. Users can now filter based on transaction ID.
- S20 Error when resetting password(--)
There was an issue occasionally causing an S20 error when attempting to reset your own password in the console. This has been fixed.
Statements
- Merchant Statement and Deposit List(557749)
thesale-auth
andcapture
calls were not properly reporting information for blacklisted transactions. This has been fixed in the console, and in statement exports. - Decline/Return Details(495024)
Merchant statements now contain details about returns, declines, chargebacks and reversals.
Hosted Payment Pages
- Payment Method selection(--)
The option to select a different payment method has been added to hosted payment pages.
Version 9.1.3
Sandbox: 2/7/2023
Production: 3/14/2023
Billing API
- Voiding transactions(403776)
There was an issue causing transactions run via the billing API to not void properly. This has been fixed. - Invalid JSON response format(710808)
When submitting an invalid field in a JSON request the system the system would return a non-standard JSON response. The response is now formatted correctly.
Transaction API
- Duplicate Convenience Fees(853192)
There was an issue calculating the convenience fees when running asale-auth
request followed by acapture
request. This has been fixed to no longer duplicate the fee.
Statements
- Merchant Statement and Deposit List(860890)
The merchant-statement-list and thedeposit-list
calls now work with either the account ID (EX: 4550001) or the merchant ID (EX: 4550000). - Decline/Return Details(495024)
Merchant statements will now contain details about returns, declines, chargebacks and reversals.
Version 9.1.2
Sandbox: 11/15/2021
Production: 1/17/2023
Merchant Console
- Copy/Paste Issues(571356)
When pasting values from your clipboard, the value no longer duplicates. - Downloading Statements(357441)
When statements are being downloaded from the console, a pop-up will display indicating that the system is loading the statement.
Billing API
- paymentOption~modify(582050)
The ~modify was occasionally receiving an error when attempting to set a payment option to active status. This has been fixed. - Unique Payment Option(136910)
Payment Methods have been adjusted to allow creation of an additional payment method with the same card number if the original payment method is set to inactive status. - Payment Options - Routing Number(975756)
The routing number is now modifiable on payment options. - Payment Options - Token Creation(375537)
Existing Tokens can now be used in the creation of a new payment option. - Next Billing Date(941151/289777)
The nextBillingDate parameter has been adjusted to allow any date in the future of the subscription as the nextBillingDate. - Billing Cycle - Bi-Weekly(536060)
The billingCycleType parameter has been adjusted to allow Bi-Weekly cycle types. This is indicated by setting billingCycleType to B, and means that the subscription will be charged every two weeks. - Cancelling Subscriptions - Effective Date(431004)
The effectiveDate parameter has been adjusted to allow up to one year in advance for all cycles except annual, and two years in advance for annual cycles. - Transaction~process(572304)
The ~process call has been adjusted to require unique values in the code parameter in order to process transactions. - Invoicing Description(--)
The description given to a claim was incorrect if there was two invoices that were being billed at the same time. This has been corrected and now will show "Multiple Dues" if this is the case.
Statements
- Transaction List(714910)
The transaction~list call has been adjusted to include the transaction.references.userCode and transaction.references.voidUserCode fields. - Statement Period(161159)
The statement period location has been moved to the statement page footer. - Transaction Summary by Day(--)
A new API request for a transaction summary by day to the API list. Refer to Transaction Summary by Day.
Charges
- Effective Date(679185)
The effectiveDate parameter is now being prioritized correctly, and will deposit to charges with the earliest effectiveDate first.
Hosted Payment Pages
- postNotifyURL(--)
Hosted Payment Pages now properly send responses to the postNotifyURL parameter.
Version 8.2.10
Sandbox: 9/27/2022
Production: 10/11/2022
Merchant Console
- Search - Cancel Button(988807)
When attempting to search on the admin console, clicking 'Cancel' had the same effect as clicking 'OK', therefore executing the search. This condition has been fixed. - Processing Refunds Error Message(545359)
The error message shown when attempting to process a refund with an incorrect settlement type now correctly displays the cause of the error. - Processing Partial Refunds(613309)
Partial refunds were not able to be issued multiple times on the merchant console, but were able to be issued multiple times on the admin console. This behavior has been changed to allow multiple partial refunds on the merchant console. - Downloading Receipts(354150)
Receipt PDFs have been update for better clarity.
Billing API
- S20 error - Create and Modify(--)
The ~create and ~modify functions were occasionally receiving an S20 error message. This has been fixed.
Statements
- Deposit Statement Emails(604048)
The body of deposit statement emails has been adjusted for clarity. - Monthly Statements(650624)
Fixed monthly statements to include records based on deposit date instead of transaction date.
Version 8.2.9
Sandbox: 8/23/2022
Production: 9/13/2022
Merchant Console
- Multiple Merchant Access(582048)
Merchant level portal user can now be associated with multiple merchant accounts. - Creating Payment Plans Error(896887)
When creating subscriptions users would sometimes encounter the error "System error. Contact support.". This error condition has been fixed. - Receipt Downloads(409407)
Unifying receipt PDF formats to match transactions.
Onboarding API
- Apostrophe - Business Description(869691)
The Onboarding API will now allow apostrophes to be used in the business description field. - Driver's License Field Deprecated(--)
Driver's Licenses are no longer required for compliance purposes, therefore we are deprecating the use of them going forward in the Onboarding process.
Payment Pages
- Hosted Payment Page Error(631304)
Customers of integrators that utilize Hosted Payment Pages would sometimes be stuck in a loop with the error "invalid account number". This error condition has been fixed.
Version 8.2.8
Sandbox: 7/12/2022
Production: 7/26/2022
Merchant Console
- Receipt Downloads(509686)
This feature will allow you to download receipts from the merchant console for a transaction at any time.
Recurring Billing API
- Billing Notes(200109)
Billing Notes on Annual Subscriptions will now properly reflect as annual in the Billing Notes section. - Charges Effective Date(679185)
Charges applied to an account will now properly take precedence by way of theeffectiveDate
parameter, not the upload order.
Reporting API
- Deposit List(442950)
The deposit-list call in the Reporting API will properly reflect the exact dates shown.
Statements
- Statement Download Error(223839)
Fixed an error encountered when downloading statements on an account that changed their pricing cycle in the same month as the statement being downloaded. Now you can download the statements without any issues. - Statement Amounts(866129)
Fixed an issue where some statements were not reflecting the correct amount when downloaded from the merchant console. Amounts have been fixed to properly reflect the correct amounts.
Version 8.2.7
Sandbox: 6/21/2022
Production: 7/05/2022
Merchant Console
- Auth Limit Response Code(284033)
A new response code has been added to specify when an account's authorization limit has been reached. This code isD50
and states 'Authorization limit is reached for the day' which is a soft decline type.
Onboarding API
- Character Support – Ampersand(114888)
The ampersand&
character is now supported by the business.businessName in the onboarding API.
Statements
- Fees Void Description(966615)
Statements have a fixed description for feeds in the voids section. It will state 'Card Brand (Realtime voids)' instead of '(Realtime Sale)'.
Version 8.2.6
Sandbox: 5/17/2022
Production: 6/07/2022
Batch Transactions
- Batch close without batch ID(167884)
In some instances, the system would attempt to close batches that have not been assigned a batch ID. The system has been corrected to only close batches that have been assigned a batch ID.
Billing API
- Invalid error when modifying nextBillingDate(236486)
Some users would receive an invalid error (System Error. Contact Support) when attempting to modify the nextBillingDate on a subscription. The system now returns the correct error under the correct circumstances. - Invalid nextInvoicingDate Calculation(931687/999138)
Under specific circumstances the value of the nextInvoicingDate would be calculated incorrectly. The system now returns the correct nextInvoicingDate. - Billing failure for deferred subscriptions(378930)
In some instances, deferred subscriptions (frozen/paused) would fail to bill at the end of the deferment. The system now processes the queued deferment event correctly.
Merchant Console
- Unable to set user permissions(817916/754550)
Administrators on merchant accounts were unable to change the rights level for other users associated with the merchant. Administrators can now set any user to any of the available rights levels in the merchant console. - Unable to leave swipe mode in VT(505486)
When using the virtual terminal users could not exit the swipe mode when using the VT in conjunction with a reader. Swipe mode can now be exited before or after user input.
Onboarding API
- Character Support – Apostrophe(114888)
The apostrophe character is now supported by the business.legalName and deposit.holderName parameters in the onboarding API.
Statements
- Statement Transaction List (549200)
Statements will now allow up to 200 transactions for display in the transaction section of the statement. For lists of transactions greater than 200 for a specific statement period a merchant can view the full transaction list in the merchant console.
Version 5.1.2
Sandbox: 4/20/2023
Production: 4/27/2023
Terminals
- Enhanced Logging(242650)
Logging has been improved to better reflect user prompts and actions that are taken. - Auto Void Issue(283405)
Corrected an auto void issue when card brands were not determined correctly. - Initialization Error(182610)
Fixed an issue that was causing terminals to fail initialization. - Duplicate Transaction Error(915610)
Fixed an issue that was rarely causing transactions to duplicate. - Unable to read terminal keys(878303)
Fixed an error dialog regarding an error reading injected keys on kernel 100. - Convenience Fees(627075)
Convenience fees will now be able to be charged to customers. - Decline Issue with EMV(627597)
Corrected an issue that caused invalid EMV tags to decline. - Keyboard Popup(921635)
Fixed an issue that was causing the android keyboard to pop up over the Zift application.
Version 5.1.5
Sandbox: 8/17/2023
Production: 8/28/2023
Terminals
- Terminal Timeout Changes(773550)
Enhanced timeout logic to increase reliability of responses to integrated point of sale systems. - Digital Signature Timeout Changes(340487)
Enhanced results of timeout on the signature screen to keep a transaction approved. - Digital Signature Bypass(340487)
Allows for a digital signature to be bypassed by a customer/merchant and the transaction remains approved. - Custom Tip Amount UI Changes(615259)
The display of the tip entry screen has been updated to adapt to the terminal's usage region: - In USA and Canada - users can input tips separately from the main payment amount. - In Europe - users can enter a total amount, including the main payment and the tip. - P2 Mini Card Entry Animations(276551)
A unique animation for P2 Mini terminals has been created to reflect the correct card entry locations. - P2 Mini Tap Icon(276551)
Tap icon added to the top center of the P2 Mini payment screen to reflect the correct location to hold contactless payment methods.
Version 5.1.6.3
Sandbox: 10/9/2023
Production: 10/31/2023
Terminals
- Account Accessory Field Transaction Responses(715353)
Terminal cloud responses will now include the account accessory data. - "Void Posted" display screen disabled(--)
The "Void Posted" display screen has been disabled on the terminal when a transaction void is initiated. - Support for P2 Smartpad including screen layout and unique adaptations(--)
Changes to the application have been made to detect P2 Smartpad devices and to use landscape screens when a P2 Smartpad is in use.
Version 5.1.7.1
Sandbox: 11/1/2023
Production: 11/8/2023
Terminals
- Expanded PIN Pad Logging(--)
Added Logging for events related to PinPad operations on Sunmi terminals. - Account Accessory In Response(--)
Implemented processing and sending of the accountAccessory field to the Cloud during payment operation processing. - Fixed S20T On "Enter Card Info" Screen(--)
Resolved the issue that caused the S20T system error to appear on the "Enter Card Info" screen. - Reduced "Updating Terminal" screens(--)
Adjusted from every time the terminal was restarted or a transaction was initiated to once every 4 hours. - Fixed Decline Logic(--)
Fixed issue for transactions that responded with declines to the API, but did not decline in the Zift system.
Version 5.2.4.1
Sandbox: 3/3/2025
Production: 4/1/2025
Terminals
- Convenience Fee Logic(1009)
Introduced a new terminal logic using the "Convenience Fee" profile parameter. This feature allows terminals to display the calculated convenience fee amount and provides a screen for cardholder acceptance. - Enhanced error logging for time synchronization issue on Sunmi terminals(1170)
Added detailed logging to identify the conditions triggering time synchronization errors on Sunmi terminals. - Terminal Reset Logic(218248)
Implemented new logic enabling Zift to reset terminal configurations without removing the injected key. - SPHS & ROM Recorded In UI(--)
The SunmiPay Hardware Service (SPHS) version and OS version (ROM) are now recorded in the user interface. - Adjusted Log Export Logic on Sunmi Terminals(--)
Enhanced the process for exporting terminal logs directly from the terminal, now saving logs to a disk file. - Combine "Approve" and "Sign Below" screens on terminals(--)
Merged "Approve" and "Sign Below" screens into a single user interface to streamline transactions. - Improved Migration Process on Sunmi Terminals(--)
Refined terminal migration logic to increase fault tolerance and ensure the completion of migration steps. - Improved Display Logic for Sunmi Terminals(240)
Optimized screen display logic when folding and unfolding the application on Sunmi terminals. Enhanced the presentation of receipt printing buttons and streamlined data and pages for a smoother UI experience. - Fixed Email Input on P2 SMARTPAD Terminals(--)
Enabled the capability to input email addresses using both physical and on-screen keyboards on P2 SMARTPAD terminals. - Fixed Low Battery Terminal Freeze Issues(--)
Resolved an issue where Sunmi terminals would freeze after indicating "Battery level must be over 50%." - Fixed Terminal Transaction Display Before Batch Close(--)
Adjusted the merchant console to display terminal transactions prior to batch closure. - Fixed P2 Smartpad Manual Transaction Entry(--)
Corrected manual transaction entry on P2 Smartpad terminals, allowing full data entry via the keypad into the application form fields. - Made Changes to the transaction-list (request) Reporting API(--)
Enhanced the transaction-list Reporting API to facilitate the generation of reports specific to a chosen terminal. - Fixed Early API Response On Failed Contactless Entry(1478)
Addressed a bug that caused an early API response on failed contactless card entry while still allowing the transaction to complete.
Deprecation of failureMessage and failureCode
Deprecation Date: 8/2021
Removal Date: 11/2024
Deprecation of failureMessage
and failureCode
in API Responses
Deprecation Schedule
- Version 8.2
- August 2021
Removal Schedule
- Version 9.2.3
- November 2024
Up until now, API requests that encountered an error condition used specific response parameters, necessitating integrators to search for multiple response code fields in their business logic. To streamline integration business logic and enhance clarity, error conditions will now be represented in the standard response fields.
Previous Approach
When an error condition occurred, the following fields were employed:
- failureMessage
- failureCode
Moving forward, error condition details will be consolidated within the following fields:
- responseMessage
- responseCode
At present, API responses incorporate both sets of fields. However, please note that as of the removal date specified the following fields will be retired and no longer supported:
- failureMessage
- failureCode
Deprecation Notice: Updates to Hosted Payment Page (HPP) Templates
Deprecation Date: 7/2023
Removal Date: 4/2025
Deprecation Schedule
- Version 9.1.6
- July 2023
Removal Schedule
- Version 9.2.8
- April 2025
As part of ongoing improvements, we are updating our Hosted Payment Pages (HPP) to incorporate a more modern design, stronger security measures, and optimized workflows.
What's Changing:
- Existing HPP templates will be deprecated in favor of new templates that support these updates.
- The current templates will reach End of Life (EOL) on March 31, 2025.
Action Required:
- Merchants and integrators using HPP pages without the
pageFormat
parameter must update their integration to ensure compatibility with the new templates. Please review documentation for this parameter in our documentation for hosted payment pages.
Our technical team is available to assist with any questions or concerns you may have during the transition. We appreciate your cooperation in adopting these updates to improve security and functionality.