iPOS - Hosted Payment Page

Table of Contents


Write to us

devsupport@denovosystem.com


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

Top 600-300-40

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 devsupport@denovosystem.com

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 devsupport@denovosystem.com 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

token AuthToken (can get from portal settings)
JSON Content-Type application/json

Request Parameters Body

merchantAuthentication object

Variable Name Description
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

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 notified.

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 sends or posts 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 a customer wants to skip or cancel the payment and return to the 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 respond 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 respond the payment status to the given merchant mobile number.

*If merchants have a web server 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.

Personalization object – Optional

merchantName Merchant / DBA name to be display in payment input page.

Type: String

Length: 35 characters

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

Type: String

Format: Logo image Url should be a http / https

themeColor Hosted payment input page theme colour

Type: String

Example values: #808080

Format: #xxxxxx

Length: 7 chars

description Merchant descriptions to be displayed in payment input page.

Type: String

Length: 150 characters

payNowButtonText Pay now button text.

Type: String

Example Value: ‘Pay Now’

Length: 15 characters

buttonColor Hosted payment button color

Type: String

Example values: #808080

Format: #xxxxxx

Length: 7 chars

cancelButtonText Cancel now button/link text.

Type: String

Example Value: ‘Pay Now’

Length: 15 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 Name Description
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 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

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

* 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

        },

        "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)

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": 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

        },

        "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”

}

"txReferenceTag2": {

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

"tagValue": "Tag-2 value" 

},

"txReferenceTag3": {

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

"tagValue": "Tag-3 value"

}

        },

        "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

        },

        "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"

        },

}

Post Response Parameters – JSON Sample

Upon Form Token Generated URL success / failure response

Success Response


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

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

Authorization API Key

Request Query Params

Variable Name Description
tpn* TPN number
transactionReferenceId* Merchant unique transaction reference id

Response Params

iPOSHPResponse object

Variable Name Description
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 – 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-HPP 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

Query API – Request Sample

https://api.ipospays.tech/v1/queryPaymentStatus?tpn=<tpn number>&transactionReferenceId=<Merchant Transaction Reference Id>

Query API – JSON Response 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-card validation >,
	      "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 / card validation transaction

                   getHostedPaymentPage 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/2    // 1 - Sale / 2 - Card Validation
. . . //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-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"

        }

}




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.

How to request for card validation transaction

getHostedPaymentPage API allows merchants to validate the card to use it for further transactions like Sale & Recurring Payments.

In request payload, if transactionType is set to 2, and amount value is set to 0, iPOS-HPP API will validate the card input by the customer in the payment page form.

Card validation – Request Payload – Sample

{

        "merchantAuthentication": {

. . .  //merchant auth key & values

        },

        "transactionRequest": {

"transactionType": 2   // Card Validation

. . . //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   // to receive card token in API response 

        },

        "personalization": {

. . .  //personalization request key & values

        },

}





RESPONSE - SAMPLE

Success Response

{

    "message": "Url generated successfully",

    "information": "https://payment.ipospays.tech/api/v1/externalPay?t=<token-value>"

}





Failure Response

{

    "errors": [

        {

            "field": "merchantAuthentication.merchantId",

            "message": "Invalid Merchant Id"

        },

{

            "field": "transactionRequest.transactionType",

            "message": "Invalid Transaction Type"

        }, ...

    ]

}




CARD VALIDATION - RESPONSE- SAMPLE  [ Upon given transaction success / failure from payment processor ]




{

        "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": 2,

      "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": "0",

      "tips": "",

      "customFee": "",

      "localTax": "",

      "stateTax": "",

      "totalAmount": "total amount charged",

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

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

      "cardToken": "card-token-response-value"

        }

}


		

Error Response Code & Message - Upon Payment Form Generate URL request

Error Response Code Error Response Message
   
  Merchant Auth request errors
merchantAuthentication[object] Merchant authentication cannot be null
merchantAuthentication.merchantId Merchant Id cannot be null
merchantAuthentication.merchantId Invalid merchant id
merchantAuthentication.transactionReferenceId Invalid transaction reference id
merchantAuthentication.transactionReferenceId Transaction reference id cannot be null
   
  Transaction request errors
transactionRequest[object] Transaction request cannot be null
transactionRequest.amount Invalid amount
transactionRequest.amount Amount cannot be null
transactionRequest.transactionType Transaction type cannot be null
transactionRequest.transactionType Invalid transaction type
transactionRequest.feeAmount Invalid fee amount
 transactionRequest.feeLabel Invalid fee label
 transactionRequest.lTaxAmount Invalid lTax amount
 transactionRequest.lTaxLabel Invalid lTax label
 transactionRequest.gTaxAmount Invalid gTax amount
 transactionRequest.gTaxLabel Invalid gTax label
  Notify By request errors
notificationOption[object] Notification option cannot be null
notificationOption.postAPI Invalid post API
notificationOption.returnUrl Invalid return URL
notificationOption.failureUrl Invalid failure URL
notificationOption.mobileNumber Invalid mobile number
notificationOption.cancelUrl Invalid Cancel URL
   
  Preference request errors
preferences[object] Preferences cannot be null
preferences.integrationType Integration type cannot be null
preferences.integrationType Invalid integration type
preferences.customerName Invalid customer name
preferences.customerEmail Invalid customer email
preferences.customerMobile Invalid customer mobile
 preferences.customerEmail, preferences.customerMobile Both customer email and customer mobile cannot be empty
  Personalization request errors
personalization.merchantName Invalid merchant name
personalization.logoUrl Invalid logo URL
personalization.themeColor Invalid theme color
personalization.description Invalid description
personalization.payNowButtonText Invalid pay button text
personalization.buttonColor Invalid button color
personalization.cancelButtonText Invalid cancel button text

Error Response Code & Message - Payment Processor

Error Response Code

Error Response Message

0 APPROVAL Approved and completed
1 CALL Refer to issuer
2 CALL Refer to issuer-Special condition
3 TERM ID ERROR Invalid Merchant ID
4 HOLD-CALL Pick up card (no fraud)
5 DECLINE Do not honor
6 ERROR General error
7 HOLD-CALL Pick up card, special condition (fraud account)
8 APPROVAL Honor Mastercard with ID
10 PARTIAL APPROVAL Partial approval for the authorized amount returned in Group III version 022
11 APPROVAL VIP approval
12 INVALID TRANS Invalid transaction
13 AMOUNT ERROR Invalid amount
14 CARD NO. ERROR Invalid card number
15 NO SUCH ISSUER No such issuer
19 RE ENTER Re-enter transaction
21 NO ACTION TAKEN Unable to back out transaction
25 NO CARD NUMBER Unable to locate the account number
28 NO REPLY File is temporarily unavailable
30 MSG FORMAT ERROR Transaction was improperly formatted
39 NO CREDIT ACCT No credit account
41 HOLD-CALL Lost card, pick up (fraud account)
43 HOLD-CALL Stolen card, pick up (fraud account)
46 CLOSED ACCOUNT Closed account
51 DECLINE Insufficient funds
52 NO CHECK ACCOUNT No checking account
53 NO SAVE ACCOUNT No savings account
54 EXPIRED CARD Expired card
55 WRONG PIN Incorrect PIN
57 SERV NOT ALLOWED Transaction not permitted-Card
58 SERV NOT ALLOWED Transaction not permitted-Terminal
59 SUSPECTED FRAUD Suspected fraud
61 EXC APPR AMT LIM Exceeds approval amount limit
62 DECLINE Invalid service code, restricted
63 SEC VIOLATION Security violation
65 EXC W/D FREQ LIM Exceeds withdrawal frequency limit
6P VERIF DATA FAILD Verification data failed
75 PIN EXCEEDED Allowable number of PIN-entry tries exceeded
76 UNSOLIC REVERSAL Unable to locate, no match
77 NO ACTION TAKEN Inconsistent, reversed, or repeat data
78 NO ACCOUNT Blocked, first used transaction from new cardholder, and card not properly unblocked
3 TERM ID ERROR Invalid Merchant ID
4 HOLD-CALL Pick up card (no fraud)
5 DECLINE Do not honor
6 ERROR General error
7 HOLD-CALL Pick up card, special condition (fraud account)
8 APPROVAL Honor Mastercard with ID
10 PARTIAL APPROVAL Partial approval for the authorized amount returned in Group III version 022
11 APPROVAL VIP approval
12 INVALID TRANS Invalid transaction
13 AMOUNT ERROR Invalid amount
14 CARD NO. ERROR Invalid card number
15 NO SUCH ISSUER No such issuer
19 RE ENTER Re-enter transaction
21 NO ACTION TAKEN Unable to back out transaction
25 NO CARD NUMBER Unable to locate the account number
28 NO REPLY File is temporarily unavailable
30 MSG FORMAT ERROR Transaction was improperly formatted
39 NO CREDIT ACCT No credit account
41 HOLD-CALL Lost card, pick up (fraud account)
43 HOLD-CALL Stolen card, pick up (fraud account)
46 CLOSED ACCOUNT Closed account
51 DECLINE Insufficient funds
52 NO CHECK ACCOUNT No checking account
53 NO SAVE ACCOUNT No savings account
54 EXPIRED CARD Expired card
55 WRONG PIN Incorrect PIN
57 SERV NOT ALLOWED Transaction not permitted-Card
58 SERV NOT ALLOWED Transaction not permitted-Terminal
59 SUSPECTED FRAUD Suspected fraud
61 EXC APPR AMT LIM Exceeds approval amount limit
62 DECLINE Invalid service code, restricted
63 SEC VIOLATION Security violation
65 EXC W/D FREQ LIM Exceeds withdrawal frequency limit
6P VERIF DATA FAILD Verification data failed
75 PIN EXCEEDED Allowable number of PIN-entry tries exceeded
76 UNSOLIC REVERSAL Unable to locate, no match
77 NO ACTION TAKEN Inconsistent, reversed, or repeat data
78 NO ACCOUNT Blocked, first used transaction from new cardholder, and card not properly unblocked
H7 SERV NOT ALLOWED Contact Merchant Services/Technical Support
H8 SERV NOT ALLOWED Contact Merchant Services/Technical Support
H9 SERV NOT ALLOWED Contact Merchant Services/Technical Support
HV FAILURE HV Hierarchy Verification Error
K0 TOKEN RESPONSE Token request was processed
K1 TOKEN NOT CONFIG Tokenization is not configured
K2 TERM NOT AUTHENT Terminal is not authenticated
K3 TOKEN FAILURE Data could not be de-tokenized
M0 DOM DBT NOT ALWD Mastercard: Canada region-issued Domestic Debit Transaction not allowed
N3 CACHBACK NOT AVL Cash back service not available
N4 DECLINE Exceeds issuer withdrawal limit
N7 CVV2 MISMATCH CVV2 Value supplied is invalid
P0 SERV NOT ALLOWED Contact Merchant Services/Technical Support
P1 SERV NOT ALLOWED Contact Merchant Services/Technical Support
P2 SERV NOT ALLOWED Contact Merchant Services/Technical Support
P3 SERV NOT ALLOWED Contact Merchant Services/Technical Support
P4 SERV NOT ALLOWED Contact Merchant Services/Technical Support
P5 SERV NOT ALLOWED Contact Merchant Services/Technical Support
P6 SERV NOT ALLOWED Contact Merchant Services/Technical Support
P7 MISSING SERIAL NUM The terminal has not yet completed the boarding process. The Serial Number has not been set up.
Q1 CARD AUTH FAIL Card authentication failed
R0 STOP RECURRING Customer requested stop of specific recurring payment
R1 STOP RECURRING Customer requested stop of all recurring payments from specific merchant
R3 STOP ALL RECUR All recurring payments have been canceled for the card number in the request
S0 INACTIVE CARD The PAN used in the transaction is inactive.
S1 MOD 10 FAIL The Mod-10 check failed.
S5 DCLN NO PRE AUTH Decline – no preauthorization found.
S9 MAX BALANCE Maximum working balance exceeded.
SA SHUT DOWN The Authorization Server is shut down.
SB INVALID STATUS Invalid card status – status is other than active
SC UNKNOWN STORE Unknown dealer/store code – special edit.
SD TOO MANY RCHRGS Maximum number of recharges is exceeded.
SE ALREADY USED Card was already used.
SF NOT MANUAL Manual transactions not allowed.
SH TYPE UNKNOWN Transaction type was unknown.
SJ INVALID TENDER An invalid tender type was submitted.
SK CUSTOMER TYPE An invalid customer type was submitted.
SL PIN LOCKED PIN was locked.
SM MAX REDEMPTS The maximum number of redemptions was exceeded.
SP MAX PAN TRIES The maximum number of PAN tries was exceeded.
SR ALREADY ISSUED The card was already issued.
SS NOT ISSUED The card was not issued.
T0 APPROVAL First check is okay and has been converted.
T1 CANNOT CONVERT The check is okay but cannot be converted. This is a declined transaction.
T2 INVALIDABA Invalid ABA number, not an ACH participant.
T3 AMOUNT ERROR Amount greater than the limit.
V1 FAILURE VM Daily threshold exceeded.