Hosted Payment Page

Revision History

Date

Version

Details

 

1.0

Initial release

29/12/2022

1.1

Added Tags Mandate

13/01/2023

1.2

Disclaimer option in personalization is added

16/03/2023

1.3

Enabling CARD VALIDATION transaction  with $0 amount to validate the card

About Hosted Payment Page URL

Hosted Payment Page (HPP) is a secure payment URL that can be integrated into e-Commerce portal, Billing solution, CRM, Cash register and mobile applications. HPP is hosted in the PCI-DSS certified environment. Hence it obviates the need for integrator’s infrastructure to go thru PCI-DSS certification. HPP URL supports credit cards, PayPal, Venmo, Buy Now Pay Later using Klarna and crypto currency as payment methods.

Response from HPP is passed on to the calling entity either using redirection URL, POST method or through SMS notification. HPP supports cash discounting and tipping. HPP can be customized to match the theme of calling entity – merchant e-commerce website, CRM or billing solution.

Calling entity can use the HPP URL in many different ways to accept payment.

Few of the scenarios include

  • Show the URL as a new page or light box overlay or as an i-frame in the e-commerce portal
  • Send SMS or Email to customers with the link to collect payment
  • Embed the URL into a QR code and print it on invoice, pre-sale ticket, cash register receipts

HPP - Use cases

E-Commerce

e-Commerce website can integrate the PAY button with iPOSPays using getHostedPaymentPage API. URL received in the response can be shown on a separate page or within the website as iframe or as a light box. HPP URL will show all payment options enabled for the merchant – Card, wallet, crypt etc., Once payment is done, HPP will call the redirection URL mentioned in the API. Thru this redirection URL merchant website will know all information like approval code, card brand used, masked PAN etc., in case of approval. In case of decline, decline error code and Reason are sent back.

Merchant portal can add Fee and indicate HPP thru a flag not to add any Fee or leave it to HPP to add the fee.

MOTO websites

MOTO website or Restaurants taking order over the phone can integrate with iPOSPays using getHostedPaymentPage API. URL received in the response can be sent to merchant’s customers via email or SMS. Customers can click on the link and complete payment from their mobile phone. Payment receipt will be sent thru SMS.

HPP can notify merchant upon payment either using POST method specified while calling HPP or by receiving an SMS. In addition, merchant also has queryPaymentStatus API to check the status on a proactive basis.

CRM and Billing solutions

CRM and billing solutions that need to raise monthly invoice to their customers can integrate with getHostedPaymentPage API. URL received in the response can be send to customer via SMS or Email. As an alternative the URL can be embedded into QR code and printed on the paper invoice. Customers can click on the link and pay from their mobile phone from anywhere.

HPP can notify merchant upon payment either using POST method specified while calling HPP or by receiving an SMS. In addition, merchant also has queryPaymentStatus API to check the status on a proactive basis.

TILL, Cash Registers and POS

In a customer present environment, cash registers can print QR code embedded with HPP URL on the itemized bill. Customer can pay for the bill at their convenience without leaving the card on the tab. Customers can add tip on the HPP URL which eliminates the need for tip adjustment at a later time. Servers in restaurants can avoid multiple run from the table to the back office while serving the merchant.

queryPaymentStatus API will allow the TILL to check the payment made from time to time. Tags like service id, table number and employee number can be added to the transactions for easy tracking.

Mobile application

Merchant facing Mobile application like billing, collection, ordering etc., can integrate with HPP. URL received in the response can be embedded into a QR code and displayed on Merchant phone. Customer can scan the QR code and pay for the service from their own phone,

After flashing the QR code, merchant application can use queryPaymentStatus API to check the status of payment. As soon as customer makes payment status check API returns with success or failure objects.

Payment Options Supported in HPP

  • Credit card payment. Card acceptance form is shown in the URL.
  • Paypal, Venmo, Buy-Now-Pay-Later Klarna. QR code is shown for customer to scan and pay.
  • DejaBit Crypo payment. QR code is shown for the customer to scan and pay.

How to get developer merchant account and generate authorization token

  • Step 1: Send an email to [email protected]
  • Step 2: iPOSpays will create a merchant account and send you an activation email along with TPN.
  • Step 3: Activate your iPOSpays merchant account
  • Step 4: Login merchant account & go to setting on the left side menu, select Generate ECOM token
  • Step 5: Select the TPN and generate the token.
  • Step 6: Use the generated TOKEN and the TPN for your HPP integration.

HPP URL to request payment page

List of HPP API’s

getHostedPaymentPage API – to get the hosted payment page Url

queryPaymentStatus API – to check the payment status

iPOS HPP APIs are completely RESTful, and all our responses are returned in JSON. Note that the URL will be different for production. Once integration has been completed, please write email to [email protected] to get production credentials.

HPP - getHostedPaymentPage API reference

Request Parameters

getHostedPaymentPage API request contains 6 primary objects

Objects

Descriptions

token

Required, AuthToken information to be sent in the header of the request

merchantAuthentication

Required, contains information about the merchant authentication details like TPN number, unique transaction reference id, etc…

transactionRequest

Required, contains information about the transactions like Type, Amount, Calculate Fee, Tips prompt, etc…

notificationOption

Required, contains information about the Notify options to be enabled to the merchants

preferences

Required, contains information about the avsVerification enabling or not, e-Receipt notify to customer enabling or not

personalization

Optional, contains parameters that control the payment form theme & color for that transaction

Request Method

HTTP Request Method : POST

getHostedPaymentPage – Post API Endpoint

Sandbox URL:https://payment.ipospays.tech/api/v1/external-payment-transaction
Production Live URL:https://payment.ipospays.com/api/v1/external-payment-transaction

Request Parameters : Header

tokenAuthToken (can get from portal settings)
JSON Content-Typeapplication/json

Request Parameters Body

merchantAuthentication object
Variable NameDescription
merchantId*

TPN Number registered in iPOS portal database.

Type: Number

Example Value: 139322815010

Length: 12 digits

transactionReferenceId*

Merchant unique transaction reference id, which can be used to status check later

Type: String

Format: Alphanumeric

Length: <=20 chars required

 

transactionRequest object

Variable Name

Description

transactionType*

Type of transactions to be processed.

Type: Number

Default: 1

Values: 1 – SALE, 2 – CARD VALIDATION 

Note: 

1 – refer SALE transaction 

2 – refer CARD VALIDATION (PREAUTH) transaction to validate the given card with amount 0 value

amount*

(USD) Amount to be charged from customer card / account.

USD amount to be multiplied by 100

Type: String

Length: 8 characters

Format:  12525 (125.25 $ X 100)

Note: amount value to be set to “0” in the case of transactionType = 2 (i.e. card validation)

calculateFee*

Fees to be calculated and added with the given amount in the payment input page, to charge from the customer.

Values: true or false

Default: true

Note

If set to true -> iPOS-HPP access Fees details based on STEAM params and add it with

 base amount & display it.

If set to false -> iPOS-HPP, will not consider the fee calculation

tipsInputPrompt*

Whether to ask customers to input the tips in the payment page.

Type: Boolean

Values: ‘true’ or ‘false’

Note: if set to true -> iPOS-HPP will prompt & ask the customer to input the tips while payment and add it with the base amount given in the request. 

If set to false -> iPOS-HPP, will not ask the customer to input the tips.

calcuateTax*

Tax to be calculated and added with the given amount in the payment input page, to charge from the customer.

Values: true or false

Default: true

Note

If set to true -> iPOS-HPP access Taxes details based on STEAM params and calculate the total amount & display it.

If set to false -> iPOS-HPP, will consider the ‘amount’ input field (inclusive of tax) as Total amount to deduct

feeAmount

Optional, (USD) Fee amount to be charged from the customer.

USD amount to be multiplied by 100

Type: String

Length: 8 characters

Format:  12525 (125.25 $ X 100)

if calculateFee is set to false -> Merchant can send fee amount along with this request

feeLabel

Fee label can be mentioned here.

Type: String

Format: Alphanumeric

Length: up-to 32 characters

tipAmount

Optional, (USD) Tip amount to be added.

USD amount to be multiplied by 100

Type: String

Length: 8 characters

Format:  12525 (125.25 $ X 100)

if tipsInputPrompt is set to false -> Merchant can send tip amount along with this request

lTaxAmount

Optional, (USD) Local tax amount to be charged from the customer.

USD amount to be multiplied by 100

Type: String

Length: 8 characters

Format:  12525 (125.25 $ X 100)

if calculateTax is set to false -> Merchant can send local tax amount along with this request

lTaxLabel

Local tax label can be mentioned here.

Type: String

Format: Alphanumeric

Length: up-to 32 characters

gTaxAmount

Optional, (USD) State tax amount to be charged from the customer.

USD amount to be multiplied by 100

Type: String

Length: 8 characters

Format:  12525 (125.25 $ X 100)

if calculateTax is set to false -> Merchant can send state tax amount along with this request

gTaxLabel

State tax label can be mentioned here.

Type: String

Format: Alphanumeric

Length: up-to 32 characters

I am text block. Click edit button to change this text. 

txReferenceTag1† (Obj)
tagLabel

Reference tag-1 label can be mentioned here

Type: String

Format: Alphanumeric

Length: up-to 25

Example value: Vehicle number

Note: if tagLabel input is given, will be reflected in the payment form

tagValue

Reference tag-1 value can be mentioned here

Type: String

Format: Alphanumeric

Length: up-to 25

Example value:  Vehicle number detail

Note: if tagValue input is given, it will be reflected in the payment form. 

if tagLabel input is given and tagValue input is empty, then we will prompt customer to input the tag value in the payment page form

isTagMandate

If isTagMandate is set to true ->  tag field value input will be set to mandate to the customer in the payment page form.

Type: Boolean 

Values: true or false

Default: false

txReferenceTag2† (Obj)
tagLabel

Reference tag-2 label can be mentioned here

Type: String

Format: Alphanumeric

Length: up-to 25

Example value: Vehicle number

Note: if tagLabel input is given, will be reflected in the payment form

tagValue

Reference tag-2 value can be mentioned here

Type: String

Format: Alphanumeric

Length: up-to 25

Example value:  Vehicle number detail

Note: if tagValue input is given, it will be reflected in the payment form. 

if tagLabel input is given and tagValue input is empty, then we will prompt customer to input the tag value in the payment page form

isTagMandate

If isTagMandate is set to true ->  tag field value input will be set to mandate to the customer in the payment page form.

Type: Boolean 

Values: true or false

Default: false

txReferenceTag3† (Obj)
tagLabel

Reference tag-3 label can be mentioned here

Type: String

Format: Alphanumeric

Length: up-to 25

Example value: Vehicle number

Note: if tagLabel input is given, will be reflected in the payment form

tagValue

Reference tag-3 value can be mentioned here

Type: String

Format: Alphanumeric

Length: up-to 25

Example value:  Vehicle number detail

Note: if tagValue input is given, it will be reflected in the payment form. 

if tagLabel is given and tagValue input is empty, then we will prompt customer to input the tag value in the payment page form

isTagMandate

If isTagMandate is set to true ->  tag field value input will be set to mandate to the customer in the payment page form.

Type: Boolean 

Values: true or false

Default: false

notificationOption object
notifyBySMS*

Whether to notify Payment status to the given merchant mobile number by SMS or not.

Type: Boolean

Values: ‘true’ or ‘false’

Note:

if set to ‘true’ -> will send the payment status as SMS to the given merchant mobile number. 

If set to ‘false’ -> no notification will be sent.

mobileNumber

Merchant mobile number to which notification to be sent.

Type: String

Format: +xxxxxxxxxxxx

Example: +918989898989

Length: 13

Note: If notificationBySMS is set to ‘true’ then this field input is mandatory.

notifyByPost*

Payment status will be sent to the given merchant postAPI Url upon requesting notifyByPost is set to ‘true’.

Type: Boolean

Values: ‘true’ or ‘false’

postAPI

Call-back API Url to which the payment status response to be notify.

Type: String

Format: should be a http or https Url

authHeader

postAPI Url auth token key

Type: String

Format: Alphanumeric

Length: <= 50 characters

notifyByRedirect*

If set to ‘true’, to the given call-back or return Url to which iPOS-HP send or post the payment status response payload.

Type: Boolean

Values: ‘true’ or ‘false’

returnUrl

Merchant call-back or return Url, to which the payment status (success or decline) will be notified by iPOS-HP with response payloads.

Type: String

Format: should be a http / https Url

failureUrl

Merchant failure call-back or return, to which the payment (declined or failure) status will be notified.

Type: String

Format: Should be a http/https Url

Note: if this entity input is empty, the payment failure status will be sent to ‘returnUrl’.

cancelUrl

Cancel Url of merchant site. If customer wants to skip or cancel the payment and return to merchant site.

Type: String

Format: should be http / https Url.

Note: About above Payment status notifications

  1. Merchants who want to integrate for e-commerce -> can request notifyByRedirect method to response the payment status to the given call-back Url. Also, can request for notifyByPost
  2. Merchants who want to integrate for Quick Pay / Send Link / QR code / TOP -> can use notifyBySMS method to response the payment status to the given merchant mobile number.

*If merchants have webserver with API, can also request real-time notify by enabling notifyByPost set to ‘true’ to send the payment status to the given post API Url.

preferences(Obj)

integrationType*

It refers the type/source of iPOS-HP integration

Type: Number

Values: 1,2,3,4

Note:

1 – E-Commerce portal

2 – E-Commerce mobile App

3 – Quick pay / Send link 

4 – QR code 

5 – Tap on phone

avsVerification*

If it’s set to ‘true’ ->  Customers will be asked to input the street & zip-code details in the credit card input page in-order to do the address verifications.

Type: Boolean

Values: ‘true’ or ‘false’

eReceipt*

To send payment status notification to customers by Mobile SMS and/or E-Mail.

Type: Boolean

Values: ‘true’ or ‘false’

eReceiptInputPrompt*

Whether to ask the customer to input the mobile number in-order to send the status of the payment.

Type: Boolean

Values: ‘true’ or ‘false’

Note: if set to ‘true’, iPOS-HP will prompt & ask the user to input the mobile and/or email, merchant not required to send the customer’s name, mobile or email on request parameters. 

If it is set to ‘false’ and eReceipt is set to ‘true’, then the merchant must send the customer’s mobile number and/or customer’s email to notify the payment status to customers.

customerName

Customer full-name, will be used as salutation while notifying the payment status to the customer upon request by the merchant.

Type: String

Format: Alphabets, space

Length: 25 characters

Note: This input field is required, if eReceipt set to ‘true’

customerEmail

Customer e-mail id to which payment status will be notified if requested

Type: String

Format: E-mail id

Note: This input field is required, if eReceipt set to ‘true’ and eReceiptInputPrompt is set to false

customerMobile

Customer mobile number to which payment status will be notified if requested.

Type: String

Format: +xxxxxxxxxxxx

Example: +18989898989

Length: 13

Note: This input field is required, If eReceipt set to ‘true’

requestCardToken*

Card token value request, in-order to use it for further consecutive transaction requests.

Type: Boolean

Values: true or false

Note: If set to ‘true’, iPOS-HPP will respond with card token value. If it is set to ‘false’, iPOS-HPP will respond, none.

shortenURL

shorten URL, in-order for the HPP to send a shortened URL instead of the long URL

Type: Boolean

Values: true or false

Note: If set to ‘true’, HPP will send a shortened URL instead of a long URL. If it set to ‘false’, HPP will send a shortened URL instead of a long URL.

Personalization object
merchantNameMerchant / DBA name to be displayed in the payment input page.

 

Type: String

Length: 35 characters

logoUrlLogo image Url to be shown in the hosted payment input page.

 

Type: String

Format: Logo image Url should be a http / https

themeColorHosted payment input page theme colour

 

Type: String

Example values: #808080

Format: #xxxxxx

Length: 7 chars

descriptionMerchant descriptions to be displayed in the payment input page.

 

Type: String

Length: 150 characters

payNowButtonTextPay now button text. 

 

Type: String

Example Value: ‘Pay Now’

Length: 15 characters

buttonColorHosted payment button color

 

Type: String

Example values: #808080

Format: #xxxxxx

Length: 7 chars

cancelButtonTextCancel now button/link text. 

 

Type: String

Example Value: ‘Pay Now’

Length: 15 characters

disclaimerMerchant disclaimer information if any, to be displayed in the payment input page.

 

Type: String

Length: 150 characters

Note:  Above personalization enables merchant to personalize the iPOS-HP payment input page with them logo, theme, Pay Now button colour. If the personalization entities values are not given, iPOS-HP will show the default settings

* Always required

† Optional

Note: All above request fields variable are case sensitive

Response Parameters - Generated URL page request (getHPP)

Generate HPP Url page request – Success
Variable NameDescription
message*URL generated successfully

 

Type: String

information*                            HPP (Hosted Payment Page) form url
Generate HPP Url page request – Failure

errors (Obj)

Variable Name          Description
field*

Error input fields

Type: String

message*

Error message

Type: Sting

Note: All above request fields variable are case sensitive

Response Parameters - Payment Processor Notification Response

iposHPResponse(Obj)

Variable Name

Description

responseCode*

iPOS-HP response code

Type: Number

Values: 200 – Payment success / Generated URL success

400 – Payment failure or declined / Generated URL failure

401 – Cancelled by Customer, 

402 – Rejected by Customer

responseMessage*

iPOS-HP response message

Type: String

Values: Successful, Declined, Cancelled by Customer, Rejected by Customer, GeneratedURL Success, GeneratedURL Failure

errResponseCode**

iPOS-HP error response codeType: Number

Values: PG error response code / payment processor error response code

Note: upon ‘responseCode’ 200, this errResponseCode and errResponseMessage will be in response payload

Type: Alphanumeric

Length: up-to 3 characters

PG Response code ( 3 digits)

Example: 500, 501, 502,…

Processor Response code  (2 characters)

Example: 00, 05, …

# Error code & message details shared in below doc

errResponseMessage**

iPOS-HP error response message

Type: String

Values: PG error response message / Payment processor error response message

Note: upon ‘responseCode’ 200, this errResponseCode and errResponseMessage will be in response payload

# Error code & message details shared in below doc

transactionReferenceId*

Merchant unique transaction reference id

Type: String

Format: Alphanumeric

Length: up-to 20 characters

transactionType*

Type of transactions processed.

Type: Number

Note: 1 – SALE, 2 – CARD VALIDATION

transactionNumber

Invoice of Transaction number 

Type: Number

Length: 4 digits

batchNumber

Batch Number

Type: Number

Length: 3 digits

cardType

Credit / Debit Card Type

Type: String

Values: VISA, MASTERCARD, AMEX, DISCOVER, DINNERS, JCB

cardLast4Digit

Credit card last 4 digits

Type: Number

Length: 4 digits

amount

Base or Total Amount charged from customer

Type: Float

Format: xxxxxx.xx

tips

Tip amount charged from customer

Type: Float

Format: xxxxxx.xx

customFee

Custom Fee charged from customer

Type: Float

Format: xxxxxx.xx

localTax

Local tax amount charged from customer

Type: Float

Format: xxxxxx.xx

stateTax

State tax amount charged from customer

Type: Float

Format: xxxxxx.xx

Length: 8

totalAmount

Total Amount charged from customer

Type: Float

Format: xxxxxx.xx

Length: 8

responseApprovalCode

Response Approval Code

Type: String

Format: Alphanumeric

Length: 6 chars

Example: TAS164

rrn

Unique retrieval reference number

Type: Number

Length: 12 characters

transactionId*

iPOS-HP unique transaction id

Type: Number

Length: 32 characters

cardToken

Card token value, in-order to use it for further consecutive transaction requests.

Type: String

Values: <card-token-value>

Note: if requestCardToken is set to ‘true’, iPOS-HPP will respond with card token value. If requestCardToken is set to ‘false’, it will respond, none.

* Mandatory

** upon only on Error response

† Optional

Note: All above request fields variable are case sensitive

Post Request Parameters – JSON sample

A) notifyByReturn – Request

Post head request (header auth-token request)

				
					{

    "token": "authToken",   //Example: "f0bed899539742309eebd8XXXX7edcf615888XXXXXXXX"

    "content-type": "application/json"

};

Post body request

{

        "merchantAuthentication": {

                 "merchantId": "TPN_NUMBER",

                 "transactionReferenceId": "Transaction Reference Id"  

        },

        "transactionRequest": {

               "transactionType": 1/2,

               "amount": "Amount-value"   //Example 1000 for 10$ i.e. 10x100

               "calculateFee": true/false,

               "tipsInputPrompt": true/false,

               "calculateTax": true/false,

               "feeAmount": "FEE-Amount-value",   //Example 1000 for 10$ i.e. 10x100

               "feeLabel": "Fee Label",

               "tipAmount": "TIP-Amount-value",   //Example 1000 for 10$ i.e. 10x100

               "lTaxAmount": "L-TAX-Amount-value",   //Example 1000 for 10$ i.e. 10x100

               "lTaxLabel": "Local-Tax-Label",

               "gTaxAmount": "G-TAX-Amount-value",   //Example 1000 for 10$ i.e. 10x100

               "gTaxLabel":  “State Tax label",

               "txReferenceTag1": {

                     "tagLabel": "Tag-label-1",  // Example “Vehicle Number”

                     "tagValue": "Tag-1 value",  // Example “TN43AA445”

                     "isTagMandate": true/false

                }

              "txReferenceTag2": {

                    "tagLabel": "Tag-label-2",

                    "tagValue": "Tag-2 value", 

                    "isTagMandate": true/false

           },

            "txReferenceTag3": {

                  "tagLabel": "Tag-label-3",

                  "tagValue": "Tag-3 value"

                  "isTagMandate": true/false

        }

},

    "notificationOption": {

           "notificationBySMS": false,

           "mobileNumber": "",

    "notifyByPOST": false,

          "authHeader": "", 

          "postAPI": "",  

     "notifyByRedirect": true,

           "returnUrl": "<return url>",  // Example https://www.merchanturl.com/thankyou/success.php

           "failureUrl": "<failure url>",  // Example https://www.merchanturl.com/thankyou/failure.php 

          "cancelUrl": "<cancel url>",  // // Example https://www.merchanturl.com/checkout.php

  },

  "preferences": {

        "integrationType": "HPP integration type", 

        "avsVerification": true/false,    

       "eReceipt": true/false,

       "eReceiptInputPrompt": true/false,

       "customerName": "Customer_Name",    

       "customerEmail": "Customer_Email",    

       "customerMobile": "Customer_mobile_number_with_ISD_code",

       "requestCardToken": true/false

       "shortenURL": true/false

  },

  "personalization": {

       "merchantName": "Merchant / DBS Name"

      "logoUrl": "http or https image url"  //Eg., "https://merchanturl.com/logo/images/logo-name.png",

      "themeColor": "theme colour",    //Example #808080

      "description": "Merchant given description",

      "payNowButtonText": "pay now button text"    //Example "Pay Now"

      "buttonColor": "pay button colour",    //Example #808080

      "cancelButtonText": "cancel button text"  //Example "Go to merchant site"

      "disclaimer": "Disclaimer information can be placed here",  //Example "Only VISA card accepted"

  },

}
				
			

B) notifyBySMS – Request

Post head request (header auth-token request)

				
					{

    "token": "authToken",   //Example: "f0bed899539742309eebd8XXXX7edcf615888XXXXXXXX"

    "content-type": "application/json"

};


Post body request

{
   "merchantAuthentication": {

         "merchantId": "TPN_NUMBER",

         "transactionReferenceId": "Transaction Reference Id"  

    },

   "transactionRequest": {

        "transactionType": 1,

        "amount": "Amount-value" // example 1000 for 10$ i.e. 10x100

        "calculateFee": true/false,

        "tipsInputPrompt": true/false,

       "calculateTax": true/false,

       "feeAmount": "FEE-Amount-value",   //Example 1000 for 10$ i.e. 10x100

       "feeLabel": "Fee Label",

       "tipAmount": "TIP-Amount-value",   //Example 1000 for 10$ i.e. 10x100

       "lTaxAmount": "L-TAX-Amount-value",   //Example 1000 for 10$ i.e. 10x100

       "lTaxLabel": "Local-Tax-Label",

       "gTaxAmount": "G-TAX-Amount-value",   //Example 1000 for 10$ i.e. 10x100

       "gTaxLabel":  “State Tax label",

       "txReferenceTag1": {

            "tagLabel": "Tag-label-1",  // Example “Vehicle Number”

            "tagValue": "Tag-1 value"  // Example “TN43AA445”

           "isTagMandate": true/false

      }

      "txReferenceTag2": {

           "tagLabel": "Tag-label-2",

           "tagValue": "Tag-2 value" 

           "isTagMandate": true/false

     },

     "txReferenceTag3": {

         "tagLabel": "Tag-label-3",

         "tagValue": "Tag-3 value"

         "isTagMandate": true/false

    }
},

"notificationOption": {

     "notificationBySMS": true,

     "mobileNumber": "Merchant Mobile Number Ex +17878787878",

     "notifyByPOST": false,

     "authHeader": "", 

     "postAPI": "",  


     "notifyByRedirect": false,

     "returnUrl": "",   

     "failureUrl": "",      

     "cancelUrl": "",

},

"preferences": {
 
    "integrationType": "HPP integration type",   //Example for e-commerce value is 1

    "avsVerification": true/false,    

    "eReceipt": true/false,

    "eReceiptInputPrompt": true/false,
  
    "customerName": "Customer_Name",    

    "customerEmail": "Customer_Email",    

    "customerMobile": "Customer_mobile_number_with_ISD_code",

    "requestCardToken": true/false

    ""shortenURL": true/false

},
"personalization": {

     "merchantName": "Merchant / DBS Name"   //Example "walmart"

     "logoUrl": "http or https image url"  // Eg., "https://merchanturl.com/logo/images/logo-name.png",

     "themeColor": "theme colour",     //Example #808080

     "description": "Merchant given description",

    "payNowButtonText": "pay now button text"  //Example "Pay Now"

    "buttonColor": "pay button colour",    //Example #808080

     "cancelButtonText": "cancel button text"    //Example "Go to merchant site"
   
     "disclaimer": "Disclaimer information can be placed here",  //Example "Only VISA card accepted"
     },

}
				
			

B) notifyByPOST – Request

Post head request (header auth-token request)

				
					{

    "token": "authToken",   //Example: "f0bed899539742309eebd8XXXX7edcf615888XXXXXXXX"

    "content-type": "application/json"

};



Post body request

{

        "merchantAuthentication": {

"merchantId": "TPN_NUMBER",

"transactionReferenceId": "Transaction Reference Id"  

        },

        "transactionRequest": {

"transactionType": 1/2,

"amount": "Amount-value" // example 1000 for 10$ i.e. 10x100

"calculateFee": true/false,

"tipsInputPrompt": true/false,

"calculateTax": true/false,

"feeAmount": "FEE-Amount-value",   //Example 1000 for 10$ i.e. 10x100

"feeLabel": "Fee Label",

"tipAmount": "TIP-Amount-value",   //Example 1000 for 10$ i.e. 10x100

"lTaxAmount": "L-TAX-Amount-value",   //Example 1000 for 10$ i.e. 10x100

"lTaxLabel": "Local-Tax-Label",

"gTaxAmount": "G-TAX-Amount-value",   //Example 1000 for 10$ i.e. 10x100

"gTaxLabel":  “State Tax label",

"txReferenceTag1": {

        "tagLabel": "Tag-label-1",  // Example “Vehicle Number”

"tagValue": "Tag-1 value"  // Example “TN43AA445”

"isTagMandate": true/false

}

"txReferenceTag2": {

        "tagLabel": "Tag-label-2",

"tagValue": "Tag-2 value" 

"isTagMandate": true/false

},

"txReferenceTag3": {

        "tagLabel": "Tag-label-3",

"tagValue": "Tag-3 value"

"isTagMandate": true/false

}

        },

        "notificationOption": {

"notificationBySMS": false,

"mobileNumber": "",




"notifyByPOST": true,

"authHeader": "API Access token", 

"postAPI": "Merchant post API Url",  Example https://www.merchanturl.com/getResponse.api

"notifyByRedirect": false,

"returnUrl": "",   

"failureUrl": "",      

"cancelUrl": "",

        },

        "preferences": {

"integrationType": "HPP integration type",  // Example for e-commerce value is 1

"avsVerification": true/false,    

"eReceipt": true/false,

"eReceiptInputPrompt": true/false,

"customerName": "Customer_Name",    

"customerEmail": "Customer_Email",    

"customerMobile": "Customer_mobile_number_with_ISD_code",

"requestCardToken": true/false

"shortenURL": true/false

        },

        "personalization": {

"merchantName": "Merchant / DBS Name",    //Example "walmart"

"logoUrl": "http or https image url”  //Ex., https://merchanturl.com/logo/images/logo-name.png",

"themeColor": "theme colour",     //Example #808080

"description": "Merchant given description",

"payNowButtonText": "pay now button text”,    //Example "Pay Now"

"buttonColor": "pay button colour",     //Example #808080

"cancelButtonText": "<cancel button text>"     //Example "Go to merchant site"

"disclaimer": "Disclaimer information can be placed here",  //Example "Only VISA card accepted" 

        },

}
 
				
			
Post Response Parameters – JSON Sample

Upon Form Token Generated URL success / failure response

Success Response for long URL

				
					{
    "message": "Url generated Successful",
    "information": "https://payment.ipospays.tech/api/v1/externalPay?t=< token-value >"
}
				
			

Success Response for Short URL

				
					{
    "message": "URL generated successfully",
    "information": "https://api.denovosystem.tech/v1/sl/344r0Cd101101T312"
}
				
			
				
					Failure Response
{
 
    "errors": [
        {
            "field": "merchantAuthentication.merchantId",
            "message": "Invalid Merchant Id"
        },
	{
            "field": "transactionRequest.transactionType",
            "message": "Invalid Transaction Type"
        }, ...
    ]
}

Upon Payment Success or Failure

{

        "iposHPResponse": {

                     "responseCode": "iPOS-HP response code like 200, 400,...",

                     "responseMessage": "Successful/Declined/Cancelled By Customer/Rejected By Customer",

                     "errResponseCode": "Error response code", 

                     "errResponseMessage": "Error response message",

                     "transactionReferenceId": "merchant unique transaction reference id sent on request",

                     "transactionType": "1-sale/ 2-card validation",

                     "transactionId": "Unique transaction Id of iPOS-HPP"

                     "transactionNumber": "4 digits of transaction number from processor",

                     "batchNumber": "3 digits of batch number from processor",

                     "cardType": "VISA/MASTERCARD/etc...",

                     "cardLast4Digit": "last 4 digit of credit/debit card",

                     "amount": "base amount or total amount charged",

                     "tips": "tip amount",

                     "customFee": "custom fee",
 
                     "localTax": "local tax",

                     "stateTax": "state tax",

                     "totalAmount": "total amount charged",

                     "responseApprovalCode": "response approval code from processor ex: TAS164",

                     "rrn": "retrieval reference number from processor #219313501821",

                     "CardToken": "card-token-value"      

        }

}

				
			
HPP API – Integration References

AngularJs Sample:

				
					{
import { Component, OnInit } from '@angular/core';
import { HttpClient, HttpHeaders } from '@angular/common/http';

//Import HttpClientModule  and add Providers : [HttpClient] in your module.ts file

export interface Payload {
  merchantAuthentication: MerchantAuthentication;
  transactionRequest: TransactionRequest;
  personalization: Personalization;
  notificationOption: NotificationOption;
  preferences: Preferences;
}
export interface MerchantAuthentication {
  merchantId: string;
  transactionReferenceId: string;
}
export interface TransactionRequest {
  transactionType: number;
  amount: number;
  calculateFee: boolean;
  invoiceNumber: string;
}
export interface Personalization {
  logo: string;
  themeColor: string;
  description: string;
  payNowButtonText: string;
  buttonColor: string;
  cancelButtonText: string;
}
export interface NotificationOption {
  returnUrl: string;
  failureUrl: string;
  authHeader: string;
  cancelUrl: string;
  notifyByRedirect: boolean;
  notifyByPost: boolean;
  postAPI: string;
  mobileNumber: string;
  notifyBySMS: boolean;
}
export interface Preferences {
  eReceipt: boolean;
  avsVerification: boolean;
  customerName: string;
  customerEmail: string;
  customerMobile: string;
  integrationType: number;
 requestCardToken: boolean;
}

export interface PaymentSuccessResponse {
  information: string  // this will be the redirect url,
  message: string
}

export interface PaymentFailureResponse {
  errors?: (ErrorsEntity)[] | null;
}
export interface ErrorsEntity {
  field: string;
  message: string;
}


@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})

export class AppComponent implements OnInit {

  generatedTpn: string = ''
  generatedToken: string = ''
  routeUrl: string = 'Your Route Url Here'
  paymentUrl: string = 'Your Route URL'

  // All the urls should be trimmed. No trailing and leading white spaces 

  payload: Payload = {
    merchantAuthentication: {
      merchantId: this.generatedTpn,
      transactionReferenceId: Math.random().toString(36).slice(2)
    },
    transactionRequest: {
      transactionType: 1,
      amount: 100, // Amount (eg : 100 = 1$)
      calculateFee: true,
      invoiceNumber: ""
    },
    personalization: {
      logo: "https://www.example.com/image/img.jpg",  // Logo image url
      themeColor: "#80DEEA",
      description: "Your Description Here",
      payNowButtonText: "Pay Now",
      buttonColor: "#80DEEA",
      cancelButtonText: "Reset"
    },
    notificationOption: {
      returnUrl: this.routeUrl,
      failureUrl: "",
      authHeader: "",
      cancelUrl: "",
      notifyByRedirect: true,
      notifyByPost: false,
      postAPI: "",
      mobileNumber: "",
      notifyBySMS: false
    },
    preferences: {
      eReceipt: false,
      avsVerification: true,
      customerName: "",
      customerEmail: "",
      customerMobile: "",
      integrationType: 1
      requestCardToken: true
    }
  }

  constructor(private httpClient: HttpClient) { }

  async ngOnInit() {

    try {
      const result = await this.getPaymentForm(this.payload) as PaymentSuccessResponse
      const redirectUrl = result.information
      window.open(redirectUrl, '_self')
    }
    catch (err) {
      // handle error here
    }
  }

  getPaymentForm(payload: Payload) {
    const httpOptions = {
      headers: new HttpHeaders({ 'token': this.generatedToken, 'withCredentials': 'false' })
    };

    return new Promise((resolve, reject) => {
      this.httpClient.post(this.paymentUrl, payload, httpOptions).subscribe(
        (data: PaymentSuccessResponse | any) => {
          resolve(data)
        },
        (error: PaymentFailureResponse) => {
          reject(error)
        }
      )

    })
  }

}
}
PHP Sample:


{
<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://payment.ipospays.tech/api/v1/external-payment-transaction',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>' {
        "merchantAuthentication": {
            "merchantId": "",
            "transactionReferenceId": ""
        },
        "transactionRequest": {
            "transactionType": 1,
            "amount": "400",
            "calculateFee": true,
            "txReferenceTag1": {
                "tagLabel": "TEST",
                "tagValue": "TAG"
            },
            "txReferenceTag2": {
                "tagLabel": "TEST1",
                "tagValue": "TAG1"
            },
            "txReferenceTag3": {
                "tagLabel": "TEST2",
                "tagValue": "TAG2"
            }
        },
        "personalization": {
            "logoUrl": "",
            "themeColor": "",
            "description": "",
            "payNowButtonText": "",
            "buttonColor": "",
            "cancelButtonText": ""
        },
        "notificationOption": {
            "postAPI": "",
            "failureUrl": "",
            "returnUrl":"",
            "notifyByRedirect": false,
            "notifyBySMS": false,
            "notifyByPOST": false,
            "authHeader": "",
            "cancelUrl": "",
            "mobileNumber": ""
        },
        "preferences": {
            "integrationType": 1,
            "eReceipt": true,
            "avsVerification": true,
            "eReceiptInputPrompt": true,
            "customerName": "",
            "customerEmail": "",
            "customerMobile": ""
            "requestCardToken":true
        }
    }
',
  CURLOPT_HTTPHEADER => array(
    'token: ',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

$reqjson = json_decode($response, true);
//header("Location:". $reqjson['information']);
				
			
HPP – queryPaymentStatus API
What is Query API

Query API lets merchants “pull” information from the gateway. It allows merchant to query the status of payment. Use same transaction reference id used while calling HPP Request Payment Page API.  This dataset can then be used to create in-house reports and analytics.

Query API Url

Sandbox URL:https://api.ipospays.tech/v1/queryPaymentStatus
Production Live URL:https://api.ipospays.com/v1/queryPaymentStatus

Request Header Info

AuthorizationAPI Key

Request Query Params

Variable NameDescription
tpn*TPN number
transactionReferenceId*Merchant unique transaction reference id
Response Params
iPOSHPResponse object
Variable NameDescription
responseCode*iPOS-HP response code

 

Type: Number

Values: 200 – Payment success 

400 – Payment failure or declined

401 – Cancelled by Customer, 

402 – Rejected by Customer

responseMessage*iPOS-HP response message

 

Type: String

Values: Successful, Declined, Cancelled by Customer, Rejected by Customer

errResponseCode**iPOS-HP error response code

 

Type: Number

Values: PG error response code / payment processor error response code

Note: upon ‘responseCode’ 200, this errResponseCode and errResponseMessage will be in response payload

Type: Alphanumeric

Length: up-to 3 characters

Processor Response code  (2 characters)

Example: 00, 05, …

# Error code & message details shared in below doc

errResponseMessage**iPOS-HP error response message

 

Type: String

Values: PG error response message / Payment processor error response message

Note: upon ‘responseCode’ 200, this errResponseCode and errResponseMessage will be in response payload

# Error code & message details shared in below doc

transactionReferenceId*Merchant unique transaction reference id

 

Type: Number

Length: up-to 255 characters

transactionType*Type of transactions processed.

 

Type: Number

Note: 1 – sale, 2 – void, 3 – refund

transactionNumberInvoice of Transaction number 

 

Type: Number

Length: 4 digits

batchNumberBatch Number

 

Type: Number

Length: 3 digits

cardTypeCredit / Debit Card Type

 

Type: String

Values: VISA, MASTERCARD, AMEX, DISCOVER, DINNERS, JCB

cardLast4DigitCredit card last 4 digits

 

Type: Number

Length: 4 digits

amountBase or Total Amount charged from customer

 

Type: Float

Format: xxxxxx.xx

tipsTip amount charged from customer

 

Type: Float

Format: xxxxxx.xx

customFeeCustom Fee charged from customer

 

Type: Float

Format: xxxxxx.xx

localTaxLocal tax amount charged from customer

 

Type: Float

Format: xxxxxx.xx

stateTaxState tax amount charged from customer

 

Type: Float

Format: xxxxxx.xx

Length: 8

totalAmountTotal Amount charged from customer

 

Type: Float

Format: xxxxxx.xx

Length: 8

responseApprovalCodeResponse Approval Code

 

Type: String

Format: Alphanumeric

Length: 6 chars

Example: TAS164

rrnUnique retrieval reference number

 

Type: Number

Length: 12 characters

transactionId*iPOS-HPP unique transaction id

 

Type: Number

Length: 32 characters

cardTokenCard token value, in-order to use it for further consecutive transaction requests.

 

Type: String

Values: <card-token-value>

Note: if requestCardToken is set to ‘true’, iPOS-HPP will respond with card token value. If requestCardToken is set to ‘false’, it will respond, none.

* Mandatory

** upon only on Error response

† Optional

Query API – Request Sample
				
					https://api.ipospays.tech/v1/queryPaymentStatus?tpn=<tpn number>&transactionReferenceId=<Merchant Transaction Reference Id>
				
			
Query API – JSON Request Sample
				
					{
        "iposHPResponse": {
              "responseCode": < iPOS-HP response code >,	
              "responseMessage": "Successful/Decined/Cancelled By Customer/Rejected By Customer",
	      "errResponseCode": < Error response code >,
	      "errResponseMessage": < Error response message >,
	      "transactionReferenceId": < merchant transaction reference id >,
      "transactionId": < Unique transaction Id of iPOS-HP >
	      "transactionType": < 1-sale/2-void/3-refund >,
	      "transactionNumber": < 4 digits of transaction number from processor >,
	      "batchNumber": < 3 digits of batch number from processor >,
	      "cardType": < VISA/MASTERCARD/etc...>,
	      "cardLast4Digit": < last 4 digit of credit/debit card >,
	      "amount": < base amount or total amount charged >,
	      "tips": < tip amount >,
	      "customFee": < custom fee >,
	      "localTax": < local tax >,
	      "stateTax": < state tax >,
	      "totalAmount": < total amount charged >,
	      "responseApprovalCode": < ex: TAS164 from processor >,
	      "rrn": < retrieval reference number >
              "cardToken":"card-token-value"	      
        }
}
				
			
How to request for card Token in part of sale transaction
  • Get Hosted Payment Page API allows merchants to  get a response of card token value/string to use it for further transactions like Sale & Recurring Payments.
  • In Sale transaction type request payload, if requestCardToken is set to true, iPOS-HPP will respond with card token value as cardToken & consumer id as consumerId. if requestCardToken is set to false, iPOS-HPP will respond, none.
				
					requestCardToken Request Payload - sample

{

        "merchantAuthentication": {

. . .  //merchant auth key & values

        },

        "transactionRequest": {

"transactionType": 1   // Sale

. . . //other transaction request key & values

        },

        "notificationOption": {

. . . //notification option request key & values

        },

        "preferences": {

"integrationType": "HPP integration type", 

"avsVerification": true/false,    

"eReceipt": true/false,

"eReceiptInputPrompt": true/false,

"customerName": "Customer_Name",    

"customerEmail": "Customer_Email",    

"customerMobile": "Customer_mobile_number_with_ISD_code",

"requestCardToken": true   // value can be true or  false 

        },

        "personalization": {

. . .  //personalization request key & values

        },

}




cardToken Value Response - sample




if requestCardToken is set to true,

{

        "iposHPResponse": {

                     "responseCode": "iPOS-HP response code like 200, 400,...",

                     "responseMessage": "Successful/Declined/Cancelled By Customer/Rejected By Customer",

      "errResponseCode": "Error response code", 

      "errResponseMessage": "Error response message",

      "transactionReferenceId": "merchant unique transaction reference id sent on request",

      "transactionType": "1-sale/2-void/3-refund",

      "transactionId": "Unique transaction Id of iPOS-HPP"

      "transactionNumber": "4 digits of transaction number from processor",

      "batchNumber": "3 digits of batch number from processor",

      "cardType": "VISA/MASTERCARD/etc...",

      "cardLast4Digit": "last 4 digit of credit/debit card",

      "amount": "base amount or total amount charged",

      "tips": "tip amount",

      "customFee": "custom fee",

      "localTax": "local tax",

      "stateTax": "state tax",

      "totalAmount": "total amount charged",

      "responseApprovalCode": "response approval code from processor ex: TAS164",

      "rrn": "retrieval reference number from processor #219313501821",

      "responseCardToken": "card-token-value"

        }

}




if requestCardToken is set to false,

{

        "iposHPResponse": {

                     "responseCode": "iPOS-HP response code like 200, 400,...",

                     "responseMessage": "Successful/Declined/Cancelled By Customer/Rejected By Customer",

      "errResponseCode": "Error response code", 

      "errResponseMessage": "Error response message",

      "transactionReferenceId": "merchant unique transaction reference id sent on request",   

      "transactionType": "1-sale/2-void/3-refund",

      "transactionId": "Unique transaction Id of iPOS-HPP"

      "transactionNumber": "4 digits of transaction number from processor",

      "batchNumber": "3 digits of batch number from processor",

      "cardType": "VISA/MASTERCARD/etc...",

      "cardLast4Digit": "last 4 digit of credit/debit card",

      "amount": "base amount or total amount charged",

      "tips": "tip amount",

      "customFee": "custom fee",

      "localTax": "local tax",

      "stateTax": "state tax",

      "totalAmount": "total amount charged",

      "responseApprovalCode": "response approval code from processor ex: TAS164",

      "rrn": "retrieval reference number from processor #219313501821"

        }

}
				
			

Query API

If requestCardToken field is set to ‘true’ in part of the Sale transaction request params (in getHPP API), and upon merchant do request for queryPaymentStatus API call, cardToken value will be a part of the response.

Error Response Code & Message – Upon Payment Form Generate URL request
Error Response CodeError Response Message
  
merchantAuthenticationMerchant Auth request errors
merchantAuthentication[object]Merchant authentication cannot be null
merchantAuthentication.merchantIdMerchant Id cannot be null
merchantAuthentication.merchantIdInvalid merchant id
merchantAuthentication.transactionReferenceIdInvalid transaction reference id
merchantAuthentication.transactionReferenceIdTransaction reference id cannot be null
  
 Transaction request errors
transactionRequest[object]Transaction request cannot be null
transactionRequest.amountInvalid amount
transactionRequest.amountAmount cannot be null
transactionRequest.transactionTypeTransaction type cannot be null
transactionRequest.transactionTypeInvalid transaction type
transactionRequest.feeAmountInvalid fee amount
 transactionRequest.feeLabelInvalid fee label
 transactionRequest.lTaxAmountInvalid lTax amount
 transactionRequest.lTaxLabelInvalid lTax label
 transactionRequest.gTaxAmountInvalid gTax amount
 transactionRequest.gTaxLabelInvalid gTax label
  
 Notify By request errors
notificationOption[object]Notification option cannot be null
notificationOption.postAPIInvalid post API
notificationOption.returnUrlInvalid return URL
notificationOption.failureUrlInvalid failure URL
notificationOption.mobileNumberInvalid mobile number
notificationOption.cancelUrlInvalid Cancel URL
  
 Preference request errors
preferences[object]Preferences cannot be null
preferences.integrationTypeIntegration type cannot be null
preferences.integrationTypeInvalid integration type
preferences.customerNameInvalid customer name
preferences.customerEmailInvalid customer email
preferences.customerMobileInvalid customer mobile
 preferences.customerEmail, preferences.customerMobileBoth customer email and customer mobile cannot be empty
 Personalization request errors
personalization.merchantNameInvalid merchant name
personalization.logoUrlInvalid logo URL
personalization.themeColorInvalid theme color
personalization.descriptionInvalid description
personalization.payNowButtonTextInvalid pay button text
personalization.buttonColorInvalid button color
personalization.cancelButtonTextInvalid cancel button text
personalization.disclaimerInvalid disclaimer

Error Response Code & Message – Payment Processor

Error Response Code

Error Response Message

0APPROVAL Approved and completed
1CALL Refer to issuer
2CALL Refer to issuer-Special condition
3TERM ID ERROR Invalid Merchant ID
4HOLD-CALL Pick up card (no fraud)
5DECLINE Do not honor
6ERROR General error
7HOLD-CALL Pick up card, special condition (fraud account)
8APPROVAL Honor Mastercard with ID
10PARTIAL APPROVAL Partial approval for the authorized amount returned in Group III version 022
11APPROVAL VIP approval
12INVALID TRANS Invalid transaction
13AMOUNT ERROR Invalid amount
14CARD NO. ERROR Invalid card number
15NO SUCH ISSUER No such issuer
19RE ENTER Re-enter transaction
21NO ACTION TAKEN Unable to back out transaction
25NO CARD NUMBER Unable to locate the account number
28NO REPLY File is temporarily unavailable
30MSG FORMAT ERROR Transaction was improperly formatted
39NO CREDIT ACCT No credit account
41HOLD-CALL Lost card, pick up (fraud account)
43HOLD-CALL Stolen card, pick up (fraud account)
46CLOSED ACCOUNT Closed account
51DECLINE Insufficient funds
52NO CHECK ACCOUNT No checking account
53NO SAVE ACCOUNT No savings account
54EXPIRED CARD Expired card
55WRONG PIN Incorrect PIN
57SERV NOT ALLOWED Transaction not permitted-Card
58SERV NOT ALLOWED Transaction not permitted-Terminal
59SUSPECTED FRAUD Suspected fraud
61EXC APPR AMT LIM Exceeds approval amount limit
62DECLINE Invalid service code, restricted
63SEC VIOLATION Security violation
65EXC W/D FREQ LIM Exceeds withdrawal frequency limit
6PVERIF DATA FAILD Verification data failed
75PIN EXCEEDED Allowable number of PIN-entry tries exceeded
76UNSOLIC REVERSAL Unable to locate, no match
77NO ACTION TAKEN Inconsistent, reversed, or repeat data
78NO ACCOUNT Blocked, first used transaction from new cardholder, and card not properly unblocked
3TERM ID ERROR Invalid Merchant ID
4HOLD-CALL Pick up card (no fraud)
5DECLINE Do not honor
6ERROR General error
7HOLD-CALL Pick up card, special condition (fraud account)
8APPROVAL Honor Mastercard with ID
10PARTIAL APPROVAL Partial approval for the authorized amount returned in Group III version 022
11APPROVAL VIP approval
12INVALID TRANS Invalid transaction
13AMOUNT ERROR Invalid amount
14CARD NO. ERROR Invalid card number
15NO SUCH ISSUER No such issuer
19RE ENTER Re-enter transaction
21NO ACTION TAKEN Unable to back out transaction
25NO CARD NUMBER Unable to locate the account number
28NO REPLY File is temporarily unavailable
30MSG FORMAT ERROR Transaction was improperly formatted
39NO CREDIT ACCT No credit account
41HOLD-CALL Lost card, pick up (fraud account)
43HOLD-CALL Stolen card, pick up (fraud account)
46CLOSED ACCOUNT Closed account
51DECLINE Insufficient funds
52NO CHECK ACCOUNT No checking account
53NO SAVE ACCOUNT No savings account
54EXPIRED CARD Expired card
55WRONG PIN Incorrect PIN
57SERV NOT ALLOWED Transaction not permitted-Card
58SERV NOT ALLOWED Transaction not permitted-Terminal
59SUSPECTED FRAUD Suspected fraud
61EXC APPR AMT LIM Exceeds approval amount limit
62DECLINE Invalid service code, restricted
63SEC VIOLATION Security violation
65EXC W/D FREQ LIM Exceeds withdrawal frequency limit
6PVERIF DATA FAILD Verification data failed
75PIN EXCEEDED Allowable number of PIN-entry tries exceeded
76UNSOLIC REVERSAL Unable to locate, no match
77NO ACTION TAKEN Inconsistent, reversed, or repeat data
78NO ACCOUNT Blocked, first used transaction from new cardholder, and card not properly unblocked
H7SERV NOT ALLOWED Contact Merchant Services/Technical Support
H8SERV NOT ALLOWED Contact Merchant Services/Technical Support
H9SERV NOT ALLOWED Contact Merchant Services/Technical Support
HVFAILURE HV Hierarchy Verification Error
K0TOKEN RESPONSE Token request was processed
K1TOKEN NOT CONFIG Tokenization is not configured
K2TERM NOT AUTHENT Terminal is not authenticated
K3TOKEN FAILURE Data could not be de-tokenized
M0DOM DBT NOT ALWD Mastercard: Canada region-issued Domestic Debit Transaction not allowed
N3CACHBACK NOT AVL Cash back service not available
N4DECLINE Exceeds issuer withdrawal limit
N7CVV2 MISMATCH CVV2 Value supplied is invalid
P0SERV NOT ALLOWED Contact Merchant Services/Technical Support
P1SERV NOT ALLOWED Contact Merchant Services/Technical Support
P2SERV NOT ALLOWED Contact Merchant Services/Technical Support
P3SERV NOT ALLOWED Contact Merchant Services/Technical Support
P4SERV NOT ALLOWED Contact Merchant Services/Technical Support
P5SERV NOT ALLOWED Contact Merchant Services/Technical Support
P6SERV NOT ALLOWED Contact Merchant Services/Technical Support
P7MISSING SERIAL NUM The terminal has not yet completed the boarding process. The Serial Number has not been set up.
Q1CARD AUTH FAIL Card authentication failed
R0STOP RECURRING Customer requested stop of specific recurring payment
R1STOP RECURRING Customer requested stop of all recurring payments from specific merchant
R3STOP ALL RECUR All recurring payments have been canceled for the card number in the request
S0INACTIVE CARD The PAN used in the transaction is inactive.
S1MOD 10 FAIL The Mod-10 check failed.
S5DCLN NO PRE AUTH Decline – no preauthorization found.
S9MAX BALANCE Maximum working balance exceeded.
SASHUT DOWN The Authorization Server is shut down.
SBINVALID STATUS Invalid card status – status is other than active
SCUNKNOWN STORE Unknown dealer/store code – special edit.
SDTOO MANY RCHRGS Maximum number of recharges is exceeded.
SEALREADY USED Card was already used.
SFNOT MANUAL Manual transactions not allowed.
SHTYPE UNKNOWN Transaction type was unknown.
SJINVALID TENDER An invalid tender type was submitted.
SKCUSTOMER TYPE An invalid customer type was submitted.
SLPIN LOCKED PIN was locked.
SMMAX REDEMPTS The maximum number of redemptions was exceeded.
SPMAX PAN TRIES The maximum number of PAN tries was exceeded.
SRALREADY ISSUED The card was already issued.
SSNOT ISSUED The card was not issued.
T0APPROVAL First check is okay and has been converted.
T1CANNOT CONVERT The check is okay but cannot be converted. This is a declined transaction.
T2INVALIDABA Invalid ABA number, not an ACH participant.
T3AMOUNT ERROR Amount greater than the limit.
V1FAILURE VM Daily threshold exceeded.