Getting Started

Welcome to Chargezoom Merchant API!

Authentication and Usage Overview

Chargezoom provides a API secret key to each Merchant Account and it can be used to create the access token which will be required in all request(s) as a token key.

Steps to Create Secret Key:
  1. Login to Chargezoom Merchant Dashboard.
  2. Click on the Configuration > "API" link in the left navigation bar.
  3. There is an option to create the API secret key using "Add New" button. When Add New button is clicked then it will ask for the Name and Domain. Please enter any valid name and the merchant subdomain url.
  4. Use "API Key Production" secret as API secretKey in all the API(s).

Authentication

Using our Authentication API endpoint allows you to create your token for login, refresh your token, and gain access to your API controls.

Generate access token.

Header Parameters
Key Description Required Type Default Restrictions
secretKey API secret key Yes String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/authentication/token/create

Response Example

                                                    
                                                        {
                                                          "code": 200,
                                                          "token": "eyJ0eXAiOi.....",
                                                          "message": "Token generated successfully."
                                                        }

Refresh existing access token. (Note: must be done within two hours of existing token's creation.)

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/authentication/token/refresh

Response Example

                                                    
                                                        {
                                                          "code": 200,
                                                          "token": "eyJ0eXAiOi.....",
                                                          "message": "Token regenerated successfully."
                                                        }

Retrieve Merchant/User Login profile information.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/authentication/profile

Response Example

                                                    
                                                        {
                                                          "code": 200,
                                                          "data": {
                                                            "merchID": "2",
                                                            "firstName": "NAP",
                                                            "lastName": "Local",
                                                            "merchantEmail": "nap@cztester.com",
                                                            "companyName": "NAP Local",
                                                            "resellerID": "1",
                                                            "agentID": "0"
                                                          },
                                                          "message": "Merchant profile data"
                                                        }

Payment Gateways

Control your merchant payment gateways. Retrieve gateways, add, or edit your merchant gateway.

Retrieves all supported Payment Gateways.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/gateway/type/list

Response Example

                                                    
                                                        {
                                                          "message": "Gateway list",
                                                          "data": [
                                                            {
                                                              "gatewayTypeID": "1",
                                                              "gatewayName": "NMI",
                                                              "gatewayUniqueId": "NMI_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "nmiUserName",
                                                                "nmiPassword"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card",
                                                                "ACH"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "2",
                                                              "gatewayName": "Authorize.net",
                                                              "gatewayUniqueId": "AUTHORIZE_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "authorizeApiKey",
                                                                "authorizeTransactionKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card",
                                                                "ACH"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "3",
                                                              "gatewayName": "PayTrace",
                                                              "gatewayUniqueId": "PAYTRACE_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "payTraceUserName",
                                                                "payTracePassword"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card",
                                                                "ACH"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "4",
                                                              "gatewayName": "PayPal",
                                                              "gatewayUniqueId": "PAYPAL_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "paypalApiUserName",
                                                                "paypalApiPassword"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "5",
                                                              "gatewayName": "Stripe",
                                                              "gatewayUniqueId": "STRIPE_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "stripePublishableKey",
                                                                "stripeSecretApiKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "6",
                                                              "gatewayName": "USAePay",
                                                              "gatewayUniqueId": "USAEPAY_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "UsaePayTransactionKey",
                                                                "UsaePayPin"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "7",
                                                              "gatewayName": "Heartland",
                                                              "gatewayUniqueId": "HEARTLAND_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "heartlandPublicKey",
                                                                "heartlandSecretKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "8",
                                                              "gatewayName": "CyberSource",
                                                              "gatewayUniqueId": "CYBERSOURCE_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "cyberMerchantId",
                                                                "cyberAPIKeyID",
                                                                "cyberSecretKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "9",
                                                              "gatewayName": "Chargezoom",
                                                              "gatewayUniqueId": "CHARGEZOOM_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "chargezoomUserName",
                                                                "chargezoomPassword"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "10",
                                                              "gatewayName": "iTransact",
                                                              "gatewayUniqueId": "ITRANSACT_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "itransactUserName",
                                                                "itransactApiKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "11",
                                                              "gatewayName": "FluidPay",
                                                              "gatewayUniqueId": "FLUIDPAY_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "fluidPayApiKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "12",
                                                              "gatewayName": "TSYS",
                                                              "gatewayUniqueId": "TSYS_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "tsysApiUserId",
                                                                "tsysApiPassword",
                                                                "tsysGatewayMerchantId"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "13",
                                                              "gatewayName": "BASYS iQ Pro",
                                                              "gatewayUniqueId": "BASYS_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "basysApiKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "14",
                                                              "gatewayName": "CardPointe",
                                                              "gatewayUniqueId": "CARDPOINTE_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "basysApiKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "15",
                                                              "gatewayName": "PayArc Payment",
                                                              "gatewayUniqueId": "PAYARC_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "payarcSecretKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "16",
                                                              "gatewayName": "EPX",
                                                              "gatewayUniqueId": "EPX_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "payarcSecretKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "18",
                                                              "gatewayName": "Intuit",
                                                              "gatewayUniqueId": "INTUIT_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "intuitClientId",
                                                                "intuitClientSecret"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "19",
                                                              "gatewayName": "Tilled",
                                                              "gatewayUniqueId": "TILLED_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "intuitClientId",
                                                                "intuitClientSecret"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "20",
                                                              "gatewayName": "Square Payment",
                                                              "gatewayUniqueId": "SQUARE_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "intuitClientId",
                                                                "intuitClientSecret"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                              ]
                                                            },
                                                            {
                                                              "gatewayTypeID": "25",
                                                              "gatewayName": "Cardknox",
                                                              "gatewayUniqueId": "CARDKNOX_GATEWAY",
                                                              "gatewayRequiredFields": [
                                                                "cardknoxApiKey"
                                                              ],
                                                              "supportedPaymentMethods": [
                                                                "Credit Card"
                                                                "ACH"
                                                              ]
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Retrieves a list of Payment Gateways added.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/gateway/all

Response Example

                                                    
                                                        {
                                                          "message": "Gateway list",
                                                          "data": [
                                                            {
                                                              "gatewayID": "155",
                                                              "gatewayFriendlyName": "NMI",
                                                              "gatewayUsername": "demo",
                                                              "gatewayPassword": "password",
                                                              "gatewaySignature": "",
                                                              "extra_field_1": "",
                                                              "gatewayType": "1",
                                                              "gatewayMerchantID": "NMI-101",
                                                              "defaultGateway": "0",
                                                              "isCC": "1",
                                                              "isACH": "1"
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Retrieves Merchant Gateway details by the Merchant Gateway ID

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/gateway/{gatewayID}

Response Example

                                                    
                                                        {
                                                          "message": "Gateway list",
                                                          "data": {
                                                            "gatewayID": "155",
                                                            "gatewayFriendlyName": "NMI",
                                                            "gatewayUsername": "demo",
                                                            "gatewayPassword": "password",
                                                            "gatewaySignature": "",
                                                            "extra_field_1": "",
                                                            "gatewayType": "1",
                                                            "gatewayMerchantID": "NMI-101",
                                                            "defaultGateway": "0",
                                                            "isCC": "1",
                                                            "isACH": "1"
                                                          },
                                                          "code": 200
                                                        }

Add a new gateway. Each gateway accepts different request parameters. Request Parameters can be found below. You can retrieve the gatewayIdentifier by running the Get Gateway Types endpoint and using the gatewayUniqueId.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

Body Parameters
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
nmiUserName NMI_USER_NAME Yes String - -
nmiPassword NMI_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
authorizeApiKey AUTHORIZE_API_KEY Yes String - -
authorizeTransactionKey AUTHORIZE_TRANSACTION_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
payTraceUserName PAYTRACE_USER_NAME Yes String - -
payTracePassword PAYTRACE_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
paypalApiUserName PAYTRACE_USER_NAME Yes String - -
paypalApiPassword PAYPAL_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
stripePublishableKey STRIPE_PUBLISHABLE_KEY Yes String - -
stripeSecretApiKey STRIPE_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
UsaePayTransactionKey USAEPAY_TRANSACTION_KEY Yes String - -
UsaePayPin USAEPAY_PIN Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
heartlandPublicKey HEARTLAND_PUBLIC_KEY Yes String - -
heartlandSecretKey HEARTLAND_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
cyberMerchantId CYBERSOURCE_MERCHANT_ID Yes String - -
cyberAPIKeyID CYBERSOURCE_API_KEY_ID Yes String - -
cyberSecretKey CYBERSOURCE_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
chargezoomUserName CHARGEZOOM_USER_NAME Yes String - -
chargezoomPassword CHARGEZOOM_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
itransactUserName ITRANSACT_USER_NAME Yes String - -
itransactApiKey ITRANSACT_API_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
fluidPayApiKey FLUIDPAY_API_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
tsysApiUserId TSYS_API_USER_ID Yes String - -
tsysApiPassword TSYS_API_PASSWORD Yes String - -
tsysGatewayMerchantId TSYS_GATEWAY_MERCHANT_ID Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
siteVariable SITE_VARIABLE Yes String - -
cardpointeUsername CP_USER_NAME Yes String - -
cardpointePassword CP_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
payarcSecretKey PAYARC_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
EPXCustNBR EPX_CUST_NBR Yes String - -
EPXMerchNBR EPX_MERCH_NBR Yes String - -
EPXDBANBR EPX_DBA_NBR Yes String - -
EPXterminal EPX_TERMINAL Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
maverickAccessToken MAVERICK_ACCESS_TOKEN Yes String - -
maverickTerminalId MAVERICK_TERMINAL_ID Yes String - -
maverickDba Maverick DBA ID (only required if you use ACH) No String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
cardknoxApiKey CARDKNOX_API_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]

URL

                                                    
                                                        https://merchantapi.payportal.com/gateway/create

Request Example

                                                    
                                                        {
                                                            "gatewayIdentifier": "NMI_GATEWAY",
                                                            "friendlyName": "NMI test",
                                                            "nmiUserName": "chucknorris",
                                                            "nmiPassword": "kittykat123",
                                                            "setAsDefault": "N",
                                                            "isCC": "Y",
                                                            "isACH": "Y"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Gateway added successfully",
                                                            "data": {
                                                                "gatewayId": {
                                                                    "gatewayID": "2468",
                                                                    "gatewayFriendlyName": "NMI test",
                                                                    "gatewayUsername": "chucknorris",
                                                                    "gatewayPassword": "kittykat123",
                                                                    "gatewaySignature": "",
                                                                    "extra_field_1": "",
                                                                    "gatewayType": "1",
                                                                    "gatewayMerchantID": "",
                                                                    "defaultGateway": "0",
                                                                    "isCC": "1",
                                                                    "isACH": "1"
                                                                }
                                                            },
                                                            "code": 200
                                                        }

Modify a merchant gateway. Each gateway requires a unique dataset sent in the request. Refer to below for an example of each dataset. You can retrieve the gatewayIdentifier by running the Get Gateway Types endpoint and using the gatewayUniqueId.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

Body Parameters
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
nmiUserName NMI_USER_NAME Yes String - -
nmiPassword NMI_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
authorizeApiKey AUTHORIZE_API_KEY Yes String - -
authorizeTransactionKey AUTHORIZE_TRANSACTION_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
payTraceUserName PAYTRACE_USER_NAME Yes String - -
payTracePassword PAYTRACE_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
paypalApiUserName PAYTRACE_USER_NAME Yes String - -
paypalApiPassword PAYPAL_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
stripePublishableKey STRIPE_PUBLISHABLE_KEY Yes String - -
stripeSecretApiKey STRIPE_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
UsaePayTransactionKey USAEPAY_TRANSACTION_KEY Yes String - -
UsaePayPin USAEPAY_PIN Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
heartlandPublicKey HEARTLAND_PUBLIC_KEY Yes String - -
heartlandSecretKey HEARTLAND_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
cyberMerchantId CYBERSOURCE_MERCHANT_ID Yes String - -
cyberAPIKeyID CYBERSOURCE_API_KEY_ID Yes String - -
cyberSecretKey CYBERSOURCE_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
chargezoomUserName CHARGEZOOM_USER_NAME Yes String - -
chargezoomPassword CHARGEZOOM_USER_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
itransactUserName ITRANSACT_USER_NAME Yes String - -
itransactApiKey ITRANSACT_API_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
fluidPayApiKey FLUIDPAY_API_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
tsysApiUserId TSYS_API_USER_ID Yes String - -
tsysApiPassword TSYS_API_PASSWORD Yes String - -
tsysGatewayMerchantId TSYS_GATEWAY_MERCHANT_ID Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
siteVariable SITE_VARIABLE Yes String - -
cardpointeUsername CP_USER_NAME Yes String - -
cardpointePassword CP_PASSWORD Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
payarcSecretKey PAYARC_SECRET_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
EPXCustNBR EPX_CUST_NBR Yes String - -
EPXMerchNBR EPX_MERCH_NBR Yes String - -
EPXDBANBR EPX_DBA_NBR Yes String - -
EPXterminal EPX_TERMINAL Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
maverickAccessToken MAVERICK_ACCESS_TOKEN Yes String - -
maverickTerminalId MAVERICK_TERMINAL_ID Yes String - -
maverickDba Maverick DBA ID (only required if you use ACH) No String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]
Key Description Required Type Default Restrictions
gatewayId Gateway ID Yes String - -
gatewayIdentifier GATEWAY_UNIQUE_ID Yes String - -
friendlyName Friendly Name Yes String - -
setAsDefault Set Gateway as Default No String N [Y,N]
cardknoxApiKey CARDKNOX_API_KEY Yes String - -
isCC Is Credit Card Accepted Yes String Y [Y,N]
isACH Is ACH Accepted Yes String N [Y,N]

URL

                                                    
                                                        https://merchantapi.payportal.com/gateway/edit

Request Example

                                                    
                                                        {
                                                            "gatewayIdentifier": "<GATEWAY_UNIQUE_ID>",
                                                            "friendlyName": "<GATEWAY_FRIENDLY_NAME>",
                                                            "gatewayId": "<GATEWAY_ID>",
                                                            "nmiUserName": "<NMI_USER_NAME>",
                                                            "nmiPassword": "<NMI_USER_PASSWORD>",
                                                            "setAsDefault": "N",
                                                            "isCC": "Y",
                                                            "isACH": "Y"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Gateway updated successfully",
                                                          "data": {
                                                            "gatewayId": {
                                                              "gatewayID": "1",
                                                              "gatewayFriendlyName": "<GATEWAY_FRIENDLY_NAME>",
                                                              "gatewayUsername": "<NMI_USER_NAME>",
                                                              "gatewayPassword": "<NMI_USER_PASSWORD>",
                                                              "gatewaySignature": "",
                                                              "extra_field_1": "",
                                                              "gatewayType": "1",
                                                              "gatewayMerchantID": "",
                                                              "defaultGateway": "0",
                                                              "isCC": "1",
                                                              "isACH": "1"
                                                            }
                                                          },
                                                          "code": 200
                                                        }

General Settings

General endpoint calls such as create a payment term, edit a payment term, retrieving payment terms, retrieving invoice prefix, set invoice prefix number, retrieving customer portal, creating a customer portal, and retrieving tax list.

Create a payment term.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
termName Display name for term. Yes String - Unique
termDays Number of days in the term. Yes Int - -
setAsDefault Set Default Yes String N [Y,N]

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/payment_term/create

Request Example

                                                    
                                                        {
                                                            "termName": "NET-12",
                                                            "termDays": "12",
                                                            "setAsDefault": "N"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Payment Term Created Successfully",
                                                          "data": {
                                                            "termID": 654,
                                                            "termName": "NET-12",
                                                            "termDays": "12",
                                                            "setAsDefault": 0
                                                          },
                                                          "code": 200
                                                        }

Edit a payment term.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
termID Term ID Yes Int - -
termName Display name for term. Yes String - Unique
termDays Number of days in the term. Yes Int - -
setAsDefault Set Default Yes String N [Y,N]

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/payment_term/edit

Request Example

                                                    
                                                        {
                                                            "termName": "TERM_NAME",
                                                            "termDays": "12",
                                                            "termID": "2109"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Payment Term Updated Successfully",
                                                          "data": {
                                                            "termID": "126",
                                                            "termName": "Due on Receipt",
                                                            "termDays": "0",
                                                            "setAsDefault": 0
                                                          },
                                                          "code": 200
                                                        }

Retrieve all payment terms available for the merchant.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/payment_term/all

Response Example

                                                    
                                                        {
                                                          "message": "Payment Term Details",
                                                          "data": [
                                                            {
                                                              "termID": "126",
                                                              "termName": "Due on Receipt",
                                                              "termDays": "0",
                                                              "setAsDefault": "0"
                                                            },
                                                            {
                                                              "termID": "127",
                                                              "termName": "Net 10",
                                                              "termDays": "10",
                                                              "setAsDefault": "0"
                                                            },
                                                            {
                                                              "termID": "128",
                                                              "termName": "Net 15",
                                                              "termDays": "15",
                                                              "setAsDefault": "0"
                                                            },
                                                            {
                                                              "termID": "129",
                                                              "termName": "Net 30",
                                                              "termDays": "30",
                                                              "setAsDefault": "0"
                                                            },
                                                            {
                                                              "termID": "654",
                                                              "termName": "NET-12",
                                                              "termDays": "12",
                                                              "setAsDefault": "0"
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Retrieve the invoice prefix & postfix for the invoice reference number.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/invoice_prefix

Response Example

                                                    
                                                        {
                                                          "message": "Merchant Settings",
                                                          "data": {
                                                            "prefix": "CZU",
                                                            "postfix": "107"
                                                          },
                                                          "code": 200
                                                        }

Create a prefix number to generate invoices.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
prefix Invoice Reference Number - Prefix Yes String - -
postfix Invoice Reference Number - Postfix Yes String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/invoice_prefix/edit

Request Example

                                                    
                                                        {
                                                            "prefix": "CZU",
                                                            "postfix": "108"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Merchant Settings",
                                                          "data": {
                                                            "prefix": "CZU",
                                                            "postfix": "108"
                                                          },
                                                          "code": 200
                                                        }

Retrieve the merchant customer portal settings.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/customer_portal

Response Example

                                                    
                                                        {
                                                          "message": "Merchant Settings",
                                                          "data": {
                                                            "prefix": "CZU",
                                                            "postfix": "107"
                                                          },
                                                          "code": 200
                                                        }

Update the merchant customer portal settings.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
enablePortal Setting to Enable/Disable Customer Portal Yes String 0 [ 0,1 ]
portalUrlPrefix Customer Portal URL Prefix Yes String - -
helpText - No String - -
termServiceURL - No String - -
allowEditContact This allows customer to edit the details using customer portal. ( Set 1 to allow the customer to Edit Details. ) Yes Int 0 [ 0,1 ]
showPaymentInfo This allow customer to show and edit the payment details using customer portal. ( Set 1 to allow the customer to Show & Edit Details. ) Yes Int 0 [ 0,1 ]
showSubscriptions This will list customer's subscriptions on landing page. ( Set 1 to allow the customer to Show customer subscriptions. ) Yes Int 0 [ 0,1 ]

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/customer_portal/setup

Request Example

                                                    
                                                        {
                                                            "enablePortal": "1",
                                                            "portalUrlPrefix": "dashboard",
                                                            "helpText": "",
                                                            "allowEditContact": "0",
                                                            "showPaymentInfo": "0",
                                                            "showSubscriptions": "0",
                                                            "termServiceURL": "https:\/\/merchantsite.com\/terms.html"
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": {
                                                            "enablePortal": "1",
                                                            "portalUrlPrefix": "dashboard",
                                                            "helpText": "",
                                                            "allowEditContact": "0",
                                                            "showPaymentInfo": "0",
                                                            "showSubscriptions": "0",
                                                            "termServiceURL": "https://merchantsite.com/terms.html",
                                                            "portalURL": "https://demos.payportal.com/customer/"
                                                          },
                                                          "message": "Merchant Settings",
                                                          "code": 200
                                                        }

Retrieve list of available taxes for the merchant.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/settings/taxes

Response Example

                                                    
                                                        {
                                                          "message": "Merchant Settings",
                                                          "data": [
                                                            {
                                                              "taxID": "4",
                                                              "friendlyName": "Arizona",
                                                              "taxRate": "18",
                                                              "taxStatus": "1"
                                                            },
                                                            {
                                                              "taxID": "5",
                                                              "friendlyName": "Arizona State DEPT",
                                                              "taxRate": "2.5",
                                                              "taxStatus": "1"
                                                            },
                                                            {
                                                              "taxID": "2",
                                                              "friendlyName": "California",
                                                              "taxRate": "8",
                                                              "taxStatus": "1"
                                                            },
                                                            {
                                                              "taxID": "6",
                                                              "friendlyName": "IST",
                                                              "taxRate": "2.5",
                                                              "taxStatus": "1"
                                                            },
                                                            {
                                                              "taxID": "7",
                                                              "friendlyName": "SID",
                                                              "taxRate": "2.3",
                                                              "taxStatus": "1"
                                                            },
                                                            {
                                                              "taxID": "3",
                                                              "friendlyName": "Tucson",
                                                              "taxRate": "9.1",
                                                              "taxStatus": "1"
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Customers

Manage your merchants customers through our customers object. This API endpoint allows you to create customers, get customer data, manage a customer, and their payment methods.

Create a new customer.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
customerFullName Customer Full Name Yes String - -
customerCompanyName Customer Company Name No String - -
externalCustomerId externalCustomerId No String - -
customerFirstName Customer First Name No String - -
customerLastName Customer Last Name No String - -
customerContact Customer Contact Number No String - -
customerEmail Customer Email Address No String - -
bAddress1 Customer Business Address Line1 No String - -
bAddress2 Customer Business Address Line2 No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Customer Business Address Country No String - -
sAddress1 Customer Shipping Address Line 1 No String - -
sAddress2 Customer Shipping Address Line 2 No String - -
sCity Customer Shipping Address City No String - -
sState Customer Shipping Address State/Province No String - -
sZipcode Customer Shipping Address ZipCode No String - -
sCountry Customer Shipping Address Country No String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/create

Request Example

                                                    
                                                        {
                                                            "customerCompanyName": "John Doe LLC",
                                                            "customerFullName": "John Doe",
                                                            "externalCustomerId": "EXT-CUST-123",
                                                            "customerFirstName": "John",
                                                            "customerLastName": "Doe",
                                                            "customerContact": "(123)-456-7890",
                                                            "customerEmail": "john.doe@cztester.com",
                                                            "bAddress1": "",
                                                            "bAddress2": "",
                                                            "bCity": "",
                                                            "bState": "",
                                                            "bZipcode": "",
                                                            "bCountry": "",
                                                            "sAddress1": "",
                                                            "sAddress2": "",
                                                            "sCity": "",
                                                            "sState": "",
                                                            "sZipcode": "",
                                                            "sCountry": ""
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Customer details successfully saved",
                                                          "data": {
                                                            "customerId": "103",
                                                            "customerFirstName": "John",
                                                            "customerLastName": "Doe",
                                                            "customerCompanyName": "John Doe LLC",
                                                            "customerFullName": "John Doe LLC",
                                                            "externalCustomerId": "EXT-CUST-123",
                                                            "customerContact": "(123)-456-7890",
                                                            "customerEmail": "john.doe@cztester.com",
                                                            "customerActiveStatus": 1,
                                                            "customerCreatedAt": "2022-03-28 09:03:42"
                                                          },
                                                          "code": 200
                                                        }

Update a customer information.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
customerFullName Customer Full Name Yes String - -
customerCompanyName Customer Company Name No String - -
externalCustomerId externalCustomerId No String - -
customerFirstName Customer First Name No String - -
customerLastName Customer Last Name No String - -
customerContact Customer Contact Number No String - -
customerEmail Customer Email Address No String - -
bAddress1 Customer Business Address Line1 No String - -
bAddress2 Customer Business Address Line2 No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Customer Business Address Country No String - -
sAddress1 Customer Shipping Address Line 1 No String - -
sAddress2 Customer Shipping Address Line 2 No String - -
sCity Customer Shipping Address City No String - -
sState Customer Shipping Address State/Province No String - -
sZipcode Customer Shipping Address ZipCode No String - -
sCountry Customer Shipping Address Country No String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/edit/{customerID}

Request Example

                                                    
                                                        {
                                                            "customerCompanyName": "John Doe Houses",
                                                            "customerFullName": "John Doe Houses",
                                                            "externalCustomerId": "EXT-CUST-124",
                                                            "customerFirstName": "John",
                                                            "customerLastName": "Doe",
                                                            "customerContact": "",
                                                            "bAddress1": "",
                                                            "bAddress2": "",
                                                            "bCity": "",
                                                            "bState": "",
                                                            "bZipcode": "",
                                                            "bCountry": "",
                                                            "sAddress1": "",
                                                            "sAddress2": "",
                                                            "sCity": "",
                                                            "sState": "",
                                                            "sZipcode": "",
                                                            "sCountry": ""
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Customer details successfully saved",
                                                          "data": {
                                                            "customerId": "1",
                                                            "customerFirstName": "John",
                                                            "customerLastName": "Doe",
                                                            "customerCompanyName": "John Doe Houses",
                                                            "externalCustomerId": "EXT-CUST-124",
                                                            "customerFullName": "John Doe Houses",
                                                            "customerContact": "(123) 123-4567",
                                                            "customerEmail": "john.doe@cztester.com",
                                                            "customerActiveStatus": 1,
                                                            "customerCreatedAt": "2020-08-12 18:48:43",
                                                            "sAddress1": "123 Beach St.",
                                                            "sCity": "Huntington Beach",
                                                            "sState": "CA",
                                                            "sZipcode": "92649",
                                                            "sCountry": "US",
                                                            "bAddress1": "123 Beach St.",
                                                            "bAddress2": "",
                                                            "bCity": "Huntington Beach",
                                                            "bState": "CA",
                                                            "bZipcode": "92649",
                                                            "bCountry": "US"
                                                          },
                                                          "code": 200
                                                        }

Retrieve a list of customers.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
page Page Number (Starting - 0) Yes Int 0 -
limit Listing Limit Count Yes Int 100 -
search *Filter Customer by [ customerFirstName, customerLastName, customerCompanyName, customerFullName, customerEmail, externalCustomerId ] * No String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/get_customer_data

Request Example

                                                    
                                                        { 
                                                            "page": "0",
                                                            "limit": "100"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Customer Detail",
                                                          "data": [
                                                            {
                                                                "customerId": "1",
                                                                "customerFirstName": "John",
                                                                "customerLastName": "Doe",
                                                                "customerCompanyName": "John Doe Houses",
                                                                "externalCustomerId": "SHA-12345",
                                                                "customerFullName": "John Doe Houses",
                                                                "customerContact": "(123) 123-4567",
                                                                "customerEmail": "john.doe@cztester.com",
                                                                "customerActiveStatus": 1,
                                                                "customerCreatedAt": "2020-08-12 18:48:43",
                                                                "sAddress1": "123 Beach St.",
                                                                "sCity": "Huntington Beach",
                                                                "sState": "CA",
                                                                "sZipcode": "92649",
                                                                "sCountry": "US",
                                                                "bAddress1": "123 Beach St.",
                                                                "bAddress2": "",
                                                                "bCity": "Huntington Beach",
                                                                "bState": "CA",
                                                                "bZipcode": "92649",
                                                                "bCountry": "US"
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Retrieve a specific customers information

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/{customerID}

Response Example

                                                    
                                                        {
                                                          "message": "Customer Detail",
                                                          "data": {
                                                            "customerId": "1",
                                                            "customerFirstName": "John",
                                                            "customerLastName": "Doe",
                                                            "customerCompanyName": "John Doe Houses",
                                                            "externalCustomerId": "EXT-CUST-123",
                                                            "customerFullName": "John Doe Houses",
                                                            "customerContact": "(123) 123-4567",
                                                            "customerEmail": "john.doe@cztester.com",
                                                            "customerActiveStatus": 1,
                                                            "customerCreatedAt": "2020-08-12 18:48:43",
                                                            "sAddress1": "123 Beach St.",
                                                            "sCity": "Huntington Beach",
                                                            "sState": "CA",
                                                            "sZipcode": "92649",
                                                            "sCountry": "US",
                                                            "bAddress1": "123 Beach St.",
                                                            "bAddress2": "",
                                                            "bCity": "Huntington Beach",
                                                            "bState": "CA",
                                                            "bZipcode": "92649",
                                                            "bCountry": "US"
                                                          },
                                                          "code": 200
                                                        }

Activate or Deactivate a customer status.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
customerActiveStatus Customer Active Status (Set 1 to Activate the customer) Yes Int 0 [ 0,1 ]

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/status/{customerID}

Request Example

                                                    
                                                        {
                                                            "customerActiveStatus": "1"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Customer Detail",
                                                          "data": {
                                                            "customerId": "83",
                                                            "customerFirstName": "Chargezoom",
                                                            "customerLastName": "Test",
                                                            "customerCompanyName": "Chargezoom Test",
                                                            "customerFullName": "Chargezoom Test",
                                                            "externalCustomerId": "EXT-CUST-123",
                                                            "customerContact": "",
                                                            "customerEmail": "chargezoom.test@cztester.com",
                                                            "customerActiveStatus": "1",
                                                            "customerCreatedAt": "2021-09-07 01:35:47",
                                                            "sAddress1": "10 Street",
                                                            "sAddress2": "",
                                                            "sCity": "Tucson",
                                                            "sState": "CA",
                                                            "sZipcode": "85023",
                                                            "sCountry": "USA",
                                                            "bAddress1": "10 Street",
                                                            "bAddress2": "",
                                                            "bCity": "Tucson",
                                                            "bState": "CA",
                                                            "bZipcode": "85023",
                                                            "bCountry": "USA"
                                                          },
                                                          "code": 200
                                                        }

Create an ACH or Card payment method for a customer.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
defaultCard Flag to set credit card default Yes Int 0 [0,1]
paymentMethod Payment Method Type ( 1 for Credit Card & 2 for ACH) Yes Int - [1,2]
customerId Customer ID Yes String - -
bAddress1 Customer Business Address Line1 No String - -
bAddress2 Customer Business Address Line2 No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Customer Business Address Country No String - -
bPhone Customer Business Phone No String - -
Key Description Required Type Default Restrictions
cardNumber Customer Credit Card Number Yes String - -
cardCvv Customer Credit Card CVV No String - -
expMonth Customer Credit Card Expiry Month Yes String - -
expYear Customer Credit Card Expiry Year Yes String - -
Key Description Required Type Default Restrictions
eaccountName Customer ACH Account Holder Name Yes String - -
eaccountNumber Customer ACH Account Number Yes String - -
erouteNumber Customer ACH Account Routing Number Yes String - -
eaccountType Customer ACH Account Type Yes String - [checking,saving]
eaccountHolderType Customer ACH Account Holder Type Yes String - [business,personal]

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/card/create

Request Example

                                                    
                                                        {
                                                            "defaultCard": "0",
                                                            "paymentMethod": "2", 
                                                            "customerId": "1",
                                                            "eaccountName": "John Doe",
                                                            "eaccountNumber": "123123123",
                                                            "erouteNumber": "123123123",
                                                            "eaccountType": "checking",
                                                            "eaccountHolderType": "business",
                                                            "bAddress1": "87026",
                                                            "bAddress2": "US",
                                                            "bCity": "Dallas",
                                                            "bState": "TX",
                                                            "bCountry": "United States",
                                                            "bPhone": "8745859654",
                                                            "bZipcode": "54781",
                                                            "defaultCard": "0"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Payment Term Created Successfully",
                                                          "data": {
                                                            "cardId": 1244
                                                          },
                                                          "code": 200
                                                        }

Create an ACH or Card payment method for a customer.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
cardId Card ID Yes String - -
defaultCard Flag to set credit card default Yes Int 0 [0,1]
paymentMethod Payment Method Type ( 1 for Credit Card & 2 for ACH) Yes Int - [1,2]
customerId Customer ID Yes String - -
bAddress1 Customer Business Address Line1 No String - -
bAddress2 Customer Business Address Line2 No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Customer Business Address Country No String - -
bPhone Customer Business Phone No String - -
Key Description Required Type Default Restrictions
cardNumber Customer Credit Card Number Yes String - -
cardCvv Customer Credit Card CVV No String - -
expMonth Customer Credit Card Expiry Month Yes String - -
expYear Customer Credit Card Expiry Year Yes String - -
Key Description Required Type Default Restrictions
eaccountName Customer ACH Account Holder Name Yes String - -
eaccountNumber Customer ACH Account Number Yes String - -
erouteNumber Customer ACH Account Routing Number Yes String - -
eaccountType Customer ACH Account Type Yes String - [checking,saving]
eaccountHolderType Customer ACH Account Holder Type Yes String - [business,personal]

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/card/edit

Request Example

                                                    
                                                        {
                                                            "paymentMethod": "1",
                                                            "cardId": "622",
                                                            "customerId": "1",
                                                            "cardNumber": "4111111111111111",
                                                            "cardCvv": "1234",
                                                            "expMonth": "03",
                                                            "expYear": "2025",
                                                            "bAddress1": "87026",
                                                            "bAddress2": "US",
                                                            "bCity": "Dallas",
                                                            "bState": "TX",
                                                            "bCountry": "United States",
                                                            "bPhone": "8745859654",
                                                            "bZipcode": "54781",
                                                            "defaultCard": "1"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Payment Term Created Successfully",
                                                          "data": {
                                                            "cardId": 622
                                                          },
                                                          "code": 200
                                                        }

Retreive a customers Credit Card/ACH information using customerID.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/card/{customerID}

Response Example

                                                    
                                                        {
                                                          "message": "Card details fetched successfully.",
                                                          "data": [
                                                            {
                                                              "cardId": "622",
                                                              "cardFriendlyName": "Echeck - 3124",
                                                              "cardNumber": "",
                                                              "expMonth": "0",
                                                              "expYear": "0",
                                                              "eaccountNumber": "123123124",
                                                              "erouteNumber": "123123123",
                                                              "eaccountName": "John Doe",
                                                              "eaccountType": "checking",
                                                              "eaccountHolderType": "business",
                                                              "bAddress1": "",
                                                              "bAddress2": "",
                                                              "bCity": "Dallas",
                                                              "bState": "TX",
                                                              "bZipcode": "54781",
                                                              "bCountry": "United States",
                                                              "userContact": ""
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Retrieve customer Credit Card/ACH details using the combination of customerID & cardID.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/card/{customerID}/{cardID}

Response Example

                                                    
                                                        {
                                                          "message": "Card details fetched successfully.",
                                                          "data": {
                                                            "cardId": "1112",
                                                            "cardFriendlyName": "Visa - 1234",
                                                            "cardNumber": "5439",
                                                            "expMonth": "1",
                                                            "expYear": "22",
                                                            "eaccountNumber": null,
                                                            "erouteNumber": null,
                                                            "eaccountName": null,
                                                            "eaccountType": null,
                                                            "eaccountHolderType": null,
                                                            "bAddress1": "123 Beach St.",
                                                            "bAddress2": "",
                                                            "bCity": "Huntington Beach",
                                                            "bState": "CA",
                                                            "bZipcode": "92649",
                                                            "bCountry": "US",
                                                            "userContact": "(123) 132-1234"
                                                          },
                                                          "code": 200
                                                        }

Delete customer Credit Card/ACH details using the combination of customerID & cardID. If the cardId exists for a subscription then it cannot be removed.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/card/{customerId}/{cardId}/delete

Response Example

                                                    
                                                        {
                                                          "message": "Card details successfully removed.",
                                                          "data": null,
                                                          "code": 200
                                                        }

Create customer notes.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
customerId Customer ID Yes String - -
noteText Note Text Yes String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/note/create

Request Example

                                                    
                                                        {
                                                            "customerId": "1",
                                                            "noteText": "Invoice related details as a note"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Private Note Created Successfully",
                                                          "data": 32,
                                                          "code": 200
                                                        }

Retrieve customer notes.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/get_notes/{customerID}

Response Example

                                                    
                                                        {
                                                          "message": "Note list",
                                                          "data": [
                                                            {
                                                              "noteText": "NOTE SAMPLE - 1",
                                                              "id": "1"
                                                            },
                                                            {
                                                              "noteText": "NOTE SAMPLE - 2",
                                                              "id": "2"
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Retrieve customer notes.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type
customerId Customer ID you wish to remove the note from Yes String
noteId The Note Id you wish to remove. Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/note/{customerID}/{noteID}/delete

Request Example

                                                    
                                                        {
                                                            "customerId" : "CUS-1234567-PFDYE4",
                                                            "noteId" : "537"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Note deleted Successfully",
                                                            "data": null,
                                                            "code": 200
                                                        }

Manage customer portal.

  1. Activate and send customer portal link to the customer. (customerPortalStatus required to set Activate)
  2. Resend customer portal link to the customer. (customerPortalStatus required to set Resend)
  3. Disable customer portal link for the customer. (customerPortalStatus required to set Deactivate)

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
customerPortalStatus Customer Portal Status Yes String - [Deactivate, Activate, Resend]

URL

                                                    
                                                        https://merchantapi.payportal.com/customer/portal_status/{customerID}

Request Example

                                                    
                                                        {
                                                            "customerPortalStatus": "Activate"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Customer Detail",
                                                          "data": {
                                                            "customerId": "83",
                                                            "customerFirstName": "Chargezoom",
                                                            "customerLastName": "Test",
                                                            "customerCompanyName": "Chargezoom Test",
                                                            "externalCustomerId": "EXT-CUST-123",
                                                            "customerFullName": "Chargezoom Test",
                                                            "customerContact": "",
                                                            "customerEmail": "chargezoom.test@cztester.com",
                                                            "customerActiveStatus": "1",
                                                            "customerCreatedAt": "2021-09-07 01:35:47",
                                                            "sAddress1": "10 Street",
                                                            "sAddress2": "",
                                                            "sCity": "Tucson",
                                                            "sState": "CA",
                                                            "sZipcode": "85023",
                                                            "sCountry": "USA",
                                                            "bAddress1": "10 Street",
                                                            "bAddress2": "",
                                                            "bCity": "Tucson",
                                                            "bState": "CA",
                                                            "bZipcode": "85023",
                                                            "bCountry": "USA"
                                                          },
                                                          "code": 200
                                                        }

Invoices

Manage your customer invoices.

Process payment for the invoice using various input parameters:

  1. Using the saved details.
  2. Using the new credit card details.
  3. Using the new ACH account details.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters

One of the following is needed to process the request: the invoice reference number, the invoice ID, or the invoice external ID.

Key Description Required Type Default Restrictions
invoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
externalInvoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
invoiceRefNo Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
gatewayId Gateway ID Yes String - -
payAmount Amount to be process for the invoice Yes float - -
paymentMethod Payment Method Type ( 1 for Credit Card & 2 for ACH) Yes Int - [1,2]
cardID Card ID Yes String - -
bCountry Country field should have a valid ISO 3166 country code No String - -
applySurcharge Surcharge ( 1 for Enable & 0 for Disable) No boolean - [1,0]
Key Description Required Type Default Restrictions
invoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
externalInvoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
invoiceRefNo Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
gatewayId Gateway ID Yes String - -
payAmount Amount to be process for the invoice Yes float - -
paymentMethod Payment Method Type ( 1 for Credit Card & 2 for ACH) Yes Int - [1,2]
cardID Card ID Yes String new1 new1
cardNumber Customer Credit Card Number Yes String - -
cardCvv Customer Credit Card CVV No String - -
expMonth Customer Credit Card Expiry Month Yes String - -
expYear Customer Credit Card Expiry Year Yes String - -
bAddress1 Customer Business Address Line1 No String - -
bAddress2 Customer Business Address Line2 No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Country field should have a valid ISO 3166 country code No String - -
bPhone Customer Business Phone No String - -
applySurcharge Surcharge ( 1 for Enable & 0 for Disable) No boolean - [1,0]
Key Description Required Type Default Restrictions
invoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
externalInvoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
invoiceRefNo Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
gatewayId Gateway ID Yes String - -
payAmount Amount to be process for the invoice Yes float - -
paymentMethod Payment Method Type ( 1 for Credit Card & 2 for ACH) Yes Int - [1,2]
cardID Card ID Yes String new1 new1
eaccountName Customer ACH Account Holder Name Yes String - -
eaccountNumber Customer ACH Account Number Yes String - -
erouteNumber Customer ACH Account Routing Number Yes String - -
eaccountType Customer ACH Account Type Yes String - [checking,saving]
eaccountHolderType Customer ACH Account Holder Type Yes String - [business,personal]
bAddress1 Customer Business Address Line1 No String - -
bAddress2 Customer Business Address Line2 No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Country field should have a valid ISO 3166 country code No String - -
bPhone Customer Business Phone No String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/invoice/process_payment

Request Example

                                                    
                                                        {
                                                            "invoiceId": "INV-1234567-Z9YEK4",
                                                            "externalInvoiceId": "NOP-5963",
                                                            "invoiceRefNo": "CZs10095",
                                                            "gatewayId": "303",
                                                            "payAmount": "5.00",
                                                            "paymentMethod": "1",
                                                            "cardId": "new1",
                                                            "cardNumber": "4111111111111111",
                                                            "cardCvv": "1234",
                                                            "expMonth": "02",
                                                            "expYear": "2025",
                                                            "bAddress1": "87026",
                                                            "bAddress2": "US",
                                                            "bCity": "Dallas",
                                                            "bState": "TX",
                                                            "bCountry": "United States",
                                                            "bPhone": "8745859654",
                                                            "bZipcode": "54781",
                                                            "customerContact": "",
                                                            "applySurcharge": "1"
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": {
                                                            "transactionID": "1234567896",
                                                            "invoiceData": {
                                                              "invoiceID": "INV-1234567-Z9YEK4",
                                                              "externalInvoiceId": "NOP-5963",
                                                              "refNumber": "CZs10095",
                                                              "BalanceRemaining": "420.00",
                                                              "DueDate": "2022-02-22",
                                                              "IsPaid": "false",
                                                              "AppliedAmount": "-85.00",
                                                              "taxID": "1",
                                                              "totalTax": "40.40",
                                                              "taxRate": "8.00",
                                                              "TimeCreated": "2022-02-07 07:27:28",
                                                              "fullName": "John Doe",
                                                              "firstName": "Doe",
                                                              "lastName": "John",
                                                              "userEmail": "john.doe@cztester.com",
                                                              "phoneNumber": "",
                                                              "companyName": "John Doe",
                                                              "CustomerListID": "CUS-1234567-D01VWE",
                                                              "ship_address1": "10 Street",
                                                              "ship_address2": "",
                                                              "ship_city": "Tucson",
                                                              "ship_state": "AZ",
                                                              "ship_country": "US",
                                                              "ship_zipcode": "85023",
                                                              "address1": "10 Street",
                                                              "address2": "",
                                                              "City": "Tucson",
                                                              "State": "AZ",
                                                              "Country": "US",
                                                              "zipCode": "85023",
                                                              "invoiceItem": [
                                                                {
                                                                  "itemDescription": " aaa    ",
                                                                  "itemQty": "1",
                                                                  "itemPrice": "505",
                                                                  "Name": "PP2",
                                                                  "itemTax": "0"
                                                                }
                                                              ]
                                                            }
                                                          },
                                                          "message": "Payment Successful",
                                                          "code": 200
                                                        }

Pay an invoice using an offline payment (such as a check received).

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters

One of the following is needed to process the request: the invoice reference number, the invoice ID, or the invoice external ID.

Key Description Required Type Default Restrictions
invoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
externalInvoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
invoiceRefNo Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
paymentDate Date must be a string containing an English date format. Such as "2000 September 10", "now", "next Thursday" etc. or ISO 8601 Yes String - -
payAmount The amount the check was for. Yes Float - -
checkNumber The unique check number received. Yes String - Must be unique

URL

                                                    
                                                        https://merchantapi.payportal.com/invoice/process_payment_offline

Request Example

                                                    
                                                        {
                                                            "invoiceId": "INV-1234567-Z9YEK4",
                                                            "paymentDate": "2024-12-03",
                                                            "payAmount": "5.00",
                                                            "checkNumber": "CK123456789"
                                                            "externalInvoiceId": "MAH-1259"
                                                            "invoiceRefNo": "CZs10095"
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": {
                                                            "transactionID": "1234567896",
                                                            "invoiceData": {
                                                              "invoiceID": "INV-1234567-Z9YEK4",
                                                              "externalInvoiceId": "MAH-1259",
                                                              "refNumber": "CZs10095",
                                                              "BalanceRemaining": "420.00",
                                                              "DueDate": "2022-02-22",
                                                              "IsPaid": "false",
                                                              "AppliedAmount": "-85.00",
                                                              "taxID": "1",
                                                              "totalTax": "40.40",
                                                              "taxRate": "8.00",
                                                              "TimeCreated": "2022-02-07 07:27:28",
                                                              "fullName": "John Doe",
                                                              "firstName": "Doe",
                                                              "lastName": "John",
                                                              "userEmail": "john.doe@cztester.com",
                                                              "phoneNumber": "",
                                                              "companyName": "John Doe",
                                                              "CustomerListID": "CUS-1234567-D01VWE",
                                                              "ship_address1": "10 Street",
                                                              "ship_address2": "",
                                                              "ship_city": "Tucson",
                                                              "ship_state": "AZ",
                                                              "ship_country": "US",
                                                              "ship_zipcode": "85023",
                                                              "address1": "10 Street",
                                                              "address2": "",
                                                              "City": "Tucson",
                                                              "State": "AZ",
                                                              "Country": "US",
                                                              "zipCode": "85023",
                                                              "invoiceItem": [
                                                                {
                                                                  "itemDescription": " aaa    ",
                                                                  "itemQty": "1",
                                                                  "itemPrice": "505",
                                                                  "Name": "PP2",
                                                                  "itemTax": "0"
                                                                }
                                                              ]
                                                            }
                                                          },
                                                          "message": "Payment Successful",
                                                          "code": 200
                                                        }

Retrieve invoice details.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Request Parameter
Key Description Type
requestId One of these can be used as the requestId to retrieve the invoice details: invoiceId, invoiceRefNo, or externalInvoiceId. String

URL

                                                    
                                                        https://merchantapi.payportal.com/invoice/{requestId}

Response Example

                                                    
                                                        {
                                                          "data": {
                                                            "invoiceId": "392",
                                                            "externalInvoiceId": "QWL-4123",
                                                            "invoiceRefrence": "1042",
                                                            "invoiceDueDate": "2022-02-03",
                                                            "invoiceBalance": "50.00",
                                                            "invoiceAppliedAmount": "0.00",
                                                            "invoiceTotal": "57.28",
                                                            "invoiceTimeCreated": "2022-01-03 22:08:25",
                                                            "invoiceTaxData": [
                                                              {
                                                                "taxId": "3",
                                                                "taxRate": "9.10",
                                                                "totalTax": "4.78",
                                                                "taxName": "Tucson Tax"
                                                              }
                                                            ],
                                                            "transactionData": [
                                                              {
                                                                "tnxID": "123456789",
                                                                "tnxAmount": "1.50",
                                                                "tnxDate": "2022-03-17 06:59:29",
                                                                "tnxStatus": "SUCCESS",
                                                                "tnxCustomerId": "1",
                                                                "tnxType": "sale",
                                                                "tnxGatewayId": "155",
                                                                "tnxCode": "100",
                                                                "tnxPaymentMethod": 1,
                                                                "tnxCustomDataFields": {
                                                                  "payment_type": " - "
                                                                },
                                                                "tnxReferenceMemo": "",
                                                                "tnxUserStatus": "1"
                                                              },
                                                              {
                                                                "tnxID": "1263456798",
                                                                "tnxAmount": "5.78",
                                                                "tnxDate": "2022-03-17 07:00:49",
                                                                "tnxStatus": "SUCCESS",
                                                                "tnxCustomerId": "1",
                                                                "tnxType": "sale",
                                                                "tnxGatewayId": "155",
                                                                "tnxCode": "100",
                                                                "tnxPaymentMethod": 1,
                                                                "tnxCustomDataFields": {
                                                                  "payment_type": " - "
                                                                },
                                                                "tnxReferenceMemo": "",
                                                                "tnxUserStatus": "1"
                                                              }
                                                            ],
                                                            "invoiceItem": [
                                                              {
                                                                "itemLineID": "17834",
                                                                "itemID": "1",
                                                                "itemRefID": "19",
                                                                "itemtotalAmount": "52.50",
                                                                "itemQty": "1",
                                                                "itemDescription": null,
                                                                "itemPrice": "52.50",
                                                                "itemName": "Bitbucket Service",
                                                                "itemTaxApplied": "1"
                                                              }
                                                            ],
                                                            "comments":  "Pay invoice online at https://payby.cc/UNG1Y0ZO906"
                                                          },
                                                          "paylink": "https://payportal.com/customer/update_payment/dHo4NDEyMTE0cnYxPTI4MTA-/SU5WLTE2NzM0NTM3NTYtM1lUSjJF",
                                                          "message": "Invoice Detail",
                                                          "code": 200
                                                        }

Void an invoice.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters

One of the following is needed to process the request: the invoice reference number, the invoice ID, or the invoice external ID.

Key Description Required Type Default Restrictions
invoiceID Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
externalInvoiceId Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -
invoiceRefNo Invoice Id,externalInvoiceId or invoiceRefNo one of them are required No String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/invoice/void

Request Example

                                                    
                                                        {
                                                            "invoiceID" : "INV-187592-AN49BA"
                                                            "externalInvoiceId" : "FAL-4455"
                                                            "invoiceRefNo" : "CZU1090"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Invoice voided succcessfully",
                                                            "data": {
                                                                "invoiceId": "INV-1234567-A9DSYR",
                                                                "externalInvoiceId": "FAL-4455",
                                                                "customerId": "CUS-1234567-DS8TVB",
                                                                "invoiceStatus": "Voided",
                                                                "invoiceRefrence": "CZU1090",
                                                                "invoiceDueDate": "2022-11-03",
                                                                "invoiceBalance": "37.00",
                                                                "invoiceAppliedAmount": "0.00",
                                                                "invoiceTotal": "37.00",
                                                                "invoiceTimeCreated": "2022-11-03 14:20:01",
                                                                "invoiceTaxData": null,
                                                                "totalTax": "0.00",
                                                                "invoiceItem": [
                                                                    {
                                                                        "itemLineID": "8813162",
                                                                        "itemID": "PRO-615691-E4M5SP",
                                                                        "itemRefID": null,
                                                                        "itemtotalAmount": "37.00",
                                                                        "itemQty": "2",
                                                                        "itemDescription": "API Invoice Item",
                                                                        "itemPrice": "18.5",
                                                                        "itemName": "ACER-ASPIRE-XU507U",
                                                                        "itemTaxApplied": "0",
                                                                        "itemTaxType": null
                                                                    }
                                                                ]
                                                            },
                                                            "code": 200
                                                        }

Retrieve list of invoices.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
page Page count starting with 0 Yes Int 0 -
limit Limit count starting with 0 Yes Int 100 -
includeItems Include Items on list result No Int [ 1 ] [ 0,1 ]
customerId Filter: customerId No String - -
search Filter: Search Value No String - Search looks for customer full name, reference number, due date, total payment, balance remaining, invoiceID and externalInvoiceId.
invoiceStatus Filter: Search Invoice Depends on their status No String - If empty, retrieves "open". Other options are: "All", "Unpaid", "Past Due", "Paid", "Cancelled", "Failed", "Partial", "open".

URL

                                                    
                                                        https://merchantapi.payportal.com/invoice/all

Request Example

                                                    
                                                        {
                                                            "page": 0,
                                                            "limit": 100
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Invoice List",
                                                          "data": [
                                                            {
                                                              "invoiceId": "INV-1234567-FW6XVN",
                                                              "externalInvoiceId":"SHA-789456",
                                                              "customerId": "CUST-3497-FWVN",
                                                              "invoiceStatus": "Paid",
                                                              "invoiceRefrence": "CZ10001",
                                                              "invoiceDueDate": "2020-02-22",
                                                              "invoiceBalance": "0.00",
                                                              "invoiceAppliedAmount": "1,250.00",
                                                              "invoiceTotal": "1,250.00",
                                                              "invoiceTimeCreated": "2020-01-23 00:07:05",
                                                              "invoiceTaxData": null,
                                                              "totalTax": null,
                                                              "invoiceItem": [
                                                                {
                                                                  "itemLineID": "8963794",
                                                                  "itemID": "PRO-645336-L1PGJV",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "1,250.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "Customer Support",
                                                                  "itemPrice": "1250",
                                                                  "itemName": "Support Customer ",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                }
                                                              ],
                                                              "comments":  "Pay invoice online at https://payby.cc/iZC1w0NU701"
                                                            },
                                                            {
                                                              "invoiceId": "INV-1234567-V4PLDY",
                                                              "externalInvoiceId":"PQR-847598",
                                                              "customerId": "CUST-8577-PSW",
                                                              "invoiceStatus": "Paid",
                                                              "invoiceRefrence": "CZ10002",
                                                              "invoiceDueDate": "2020-02-11",
                                                              "invoiceBalance": "0.00",
                                                              "invoiceAppliedAmount": "1,250.50",
                                                              "invoiceTotal": "1,250.50",
                                                              "invoiceTimeCreated": "2020-02-11 03:02:26",
                                                              "invoiceTaxData": null,
                                                              "totalTax": null,
                                                              "invoiceItem": [
                                                                {
                                                                  "itemLineID": "8307970",
                                                                  "itemID": "PRO-858856-BOCNSI",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "0.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "PP3",
                                                                  "itemPrice": "0",
                                                                  "itemName": "PP3",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                },
                                                                {
                                                                  "itemLineID": "8847325",
                                                                  "itemID": "PRO-645336-L1PGJV",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "1,250.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "Customer Support",
                                                                  "itemPrice": "1250",
                                                                  "itemName": "Support Customer ",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                },
                                                                {
                                                                  "itemLineID": "8107711",
                                                                  "itemID": "PRO-548121-2I7E9O",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "0.50",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "PP2",
                                                                  "itemPrice": "0.5",
                                                                  "itemName": "PP2",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                },
                                                                {
                                                                  "itemLineID": "5206504",
                                                                  "itemID": "PRO-855327-G24LX3",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "0.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "Something",
                                                                  "itemPrice": "0",
                                                                  "itemName": "Something",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                }
                                                              ],
                                                              "comments":  "Pay invoice online at https://payby.cc/iVG1w0ZO108"
                                                            },
                                                            {
                                                              "invoiceId": "INV-4747957-W7TE3R",
                                                              "externalInvoiceId":"ZAP-741225",
                                                              "customerId": "CUST-1427-NASA",
                                                              "invoiceStatus": "Paid",
                                                              "invoiceRefrence": "CZ10003",
                                                              "invoiceDueDate": "2020-02-11",
                                                              "invoiceBalance": "0.00",
                                                              "invoiceAppliedAmount": "1,250.50",
                                                              "invoiceTotal": "1,250.50",
                                                              "invoiceTimeCreated": "2020-02-11 03:03:16",
                                                              "invoiceTaxData": null,
                                                              "totalTax": null,
                                                              "invoiceItem": [
                                                                {
                                                                  "itemLineID": "7253795",
                                                                  "itemID": "PRO-858856-BOCNSI",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "0.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "PP3",
                                                                  "itemPrice": "0",
                                                                  "itemName": "PP3",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                },
                                                                {
                                                                  "itemLineID": "7552402",
                                                                  "itemID": "PRO-645336-L1PGJV",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "1,250.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "Customer Support",
                                                                  "itemPrice": "1250",
                                                                  "itemName": "Support Customer ",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                },
                                                                {
                                                                  "itemLineID": "5037685",
                                                                  "itemID": "PRO-548121-2I7E9O",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "0.50",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "PP2",
                                                                  "itemPrice": "0.5",
                                                                  "itemName": "PP2",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                },
                                                                {
                                                                  "itemLineID": "7870625",
                                                                  "itemID": "PRO-855327-G24LX3",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "0.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "Something",
                                                                  "itemPrice": "0",
                                                                  "itemName": "Something",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                }
                                                              ],
                                                              "comments":  "Pay invoice online at https://payby.cc/iHG1Y0ZO109"
                                                            },
                                                            {
                                                              "invoiceId": "INV-1234567-P8IAJL",
                                                              "externalInvoiceId":"AQW-852036",
                                                              "customerId": "CUST-1234-FNAS",
                                                              "invoiceStatus": "Paid",
                                                              "invoiceRefrence": "CZ10007",
                                                              "invoiceDueDate": "2020-03-16",
                                                              "invoiceBalance": "0.00",
                                                              "invoiceAppliedAmount": "1,250.50",
                                                              "invoiceTotal": "1,250.50",
                                                              "invoiceTimeCreated": "2020-03-16 04:15:16",
                                                              "invoiceTaxData": null,
                                                              "totalTax": null,
                                                              "invoiceItem": [
                                                                {
                                                                  "itemLineID": "6422972",
                                                                  "itemID": "PRO-645336-L1PGJV",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "1,250.00",
                                                                  "itemQty": "1",
                                                                  "itemDescription": "Customer Support",
                                                                  "itemPrice": "1250",
                                                                  "itemName": "Support Customer ",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                },
                                                                {
                                                                  "itemLineID": "6989372",
                                                                  "itemID": "PRO-548121-2I7E9O",
                                                                  "itemRefID": null,
                                                                  "itemtotalAmount": "0.50",
                                                                  "itemQty": "1",
                                                                  "itemDescription": " aaa",
                                                                  "itemPrice": "0.5",
                                                                  "itemName": "PP2",
                                                                  "itemTaxApplied": "0",
                                                                  "itemTaxType": null
                                                                }
                                                              ],
                                                              "comments":  "Pay invoice online at https://payby.cc/pHLK1Y0ZO189"
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Create an invoice. Creating an invoice requires setting the invoice date, customerId or externalCustomerId, and invoiceLineItem. The "invoiceLineItem" field is an array and defined below the Body Parameters.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type
customerId customerId or externalCustomerId one of them are required No String
externalCustomerId customerId or externalCustomerId one of them are required No String
invoiceDate Invoice Date - Date must be "yyyy-mm-dd" format. Such as "2024-01-30" etc. Yes String
externalInvoiceId externalInvoiceId No String
invoiceRefNo invoiceRefNo No String
invoicePaytermDays Invoice Payterm Days. If you use invoiceDate with invoicePaytermDays it will use the invoiceDueDate as the base date and add `invoicePaytermDays` number to the invoice date for the payment due date. No integer
invoiceLineItem Item Data Yes Array
bAddress1 Customer Business Address Line1 No String
bAddress2 Customer Business Address Line2 No String
bCity Customer Business Address City No String
bState Customer Business Address State/Province No String
bCountry Customer Business Address Country No String
bZipcode Customer Business Address ZipCode No String
sAddress1 Customer Shipping Address Line 1 No String
sAddress2 Customer Shipping Address Line 2 No String
sCity Customer Shipping Address City No String
sState Customer Shipping Address State/Province No String
sCountry Customer Shipping Address Country No String
sZipcode Customer Shipping Address ZipCode No String
taxID Tax ID Associated from the list of taxes in your account. If your account is Freshbooks or XERO this does not apply to you. No Integer
invoiceLineItem Array Parameters

Based on what accounting package integration you have we integrate differently for invoiceLineItem.

Key Description Required Type Default Restrictions
itemListID This is the unique ID for the product or service provided. Which must be an active service or product attached to your merchant account. Yes String - -
itemRate The USD amount for the item/service. Yes Float - -
itemQuantity Quantity of item/service. Yes Float - -
itemDescription Description attached to the line item for the service/product. Required but can be empty. Yes String - -
itemTax If you set itemTax to 1 for the line item then tax will be applied to it based on the taxID you provided. No Integer 0 [1,0]

URL

                                                    
                                                        https://merchantapi.payportal.com/invoice/create

Request Example

                                                    
                                                        {
                                                          "customerId": "CUS-1234567-DS8TVB",
                                                          "externalCustomerId": "EXT-CUST-123",
                                                          "invoiceDate": "2024-01-30",
                                                          "externalInvoiceId": "SHA-789456",
                                                          "invoiceRefNo": "KEY 154",
                                                          "invoiceLineItem": [
                                                            {
                                                              "itemListID": "PRO-615691-E4M5SP",
                                                              "externalItemId": "EXT-ITEM-E4M5SP",
                                                              "itemRate": 18.5,
                                                              "itemQuantity": 2,
                                                              "itemDescription": "API Invoice Item"
                                                            }
                                                          ]
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Invoice details saved succcessfully",
                                                            "data": {
                                                                "invoiceId": "INV-1234567-A9DSYR",
                                                                "externalInvoiceId":"SHA-789456",
                                                                "customerId": "CUS-1234744-DS8TVB",
                                                                "externalCustomerId": "EXT-CUST-123",
                                                                "invoiceStatus": "Open",
                                                                "invoiceRefrence": "CZU1090",
                                                                "invoiceDueDate": "2022-11-03",
                                                                "invoiceBalance": "37.00",
                                                                "invoiceAppliedAmount": "0.00",
                                                                "invoiceTotal": "37.00",
                                                                "invoiceTimeCreated": "2022-11-03 14:20:01",
                                                                "invoiceTaxData": null,
                                                                "totalTax": "0.00",
                                                                "invoiceItem": [
                                                                    {
                                                                        "itemLineID": "8813162",
                                                                        "itemID": "PRO-615691-E4M5SP",
                                                                        "externalItemId": "EXT-ITEM-E4M5SP",
                                                                        "itemRefID": null,
                                                                        "itemtotalAmount": "37.00",
                                                                        "itemQty": "2",
                                                                        "itemDescription": "API Invoice Item",
                                                                        "itemPrice": "18.5",
                                                                        "itemName": "ACER-ASPIRE-XU507U",
                                                                        "itemTaxApplied": "0",
                                                                        "itemTaxType": null
                                                                    }
                                                                ],
                                                                "paylink": "https://payportal.com/customer/update_payment/dHo4NDEyMTE0cnYxPTI4MTA-/SU5WLTE2NzM0NTM3NTYtM1lUSjJF"
                                                            },
                                                            "code": 200
                                                        }

Update an invoice. Updating an invoice requires setting the invoice date, customerId or externalCustomerId, and invoiceLineItem. The "invoiceLineItem" field is an array and defined below the Body Parameters.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters

One of the following is needed to process the request: the invoice reference number, the invoice ID, or the invoice external ID.

Key Description Required Type Default Restrictions
invoiceId invoiceId No String - -
customerId customerId or externalCustomerId one of them are required No String - -
externalCustomerId customerId or externalCustomerId one of them are required No String
externalInvoiceId externalInvoiceId No String - -
invoiceRefNo invoiceRefNo can be used to update the invoice, reference number can not be change after the invoice generated. No String - -
invoicePaytermDays Invoice Payterm Days. If you use invoiceDate with invoicePaytermDays it will use the invoiceDueDate as the base date and add `invoicePaytermDays` number to the invoice date for the payment due date. No Int - -
invoiceDate Invoice Date - Date must be "yyyy-mm-dd" format. Such as "2024-01-30" etc. Yes String - -
invoiceLineItem Item Data Yes Array - -
bAddress1 Customer Business Address Line1 No String - -
bAddress2 Customer Business Address Line2 No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bCountry Customer Business Address Country No String - -
bZipcode Customer Business Address ZipCode No String - -
sAddress1 Customer Shipping Address Line 1 No String - -
sAddress2 Customer Shipping Address Line 2 No String - -
sCity Customer Shipping Address City No String - -
sState Customer Shipping Address State/Province No String - -
sCountry Customer Shipping Address Country No String - -
sZipcode Customer Shipping Address ZipCode No String - -
taxID Tax ID Associated from the list of taxes in your account. If your account is Freshbooks or XERO this does not apply to you. No Integer - -
invoiceLineItem Array Parameters

Based on what accounting package integration you have we integrate differently for invoiceLineItem.

Key Description Required Type Default Restrictions
itemListID This is the unique ID for the product or service provided. Which must be an active service or product attached to your merchant account. Yes String - -
itemRate The USD amount for the item/service. Yes Float - -
itemQuantity Quantity of item/service. Yes Float - -
itemDescription Description attached to the line item for the service/product. Required but can be empty. Yes String - -
itemTax If you set itemTax to 1 for the line item then tax will be applied to it based on the taxID you provided. No Integer 0 [1,0]

URL

                                                    
                                                        https://merchantapi.payportal.com/invoice/update

Request Example

                                                    
                                                        {
                                                          "customerId": "CUS-1234567-DS8TVB",
                                                          "externalCustomerId": "EXT-CUST-123",
                                                          "invoiceId": "INV-1234567-TSL015",
                                                          "invoiceDate": "2024-01-30",
                                                          "externalInvoiceId": "SHA-789456",
                                                          "invoiceRefNo": "KEY 153",
                                                          "invoiceLineItem": [
                                                            {
                                                              "itemListID": "PRO-615691-E4M5SP",
                                                              "externalItemId": "EXT-ITEM-E4M5SP",
                                                              "itemRate": 18.5,
                                                              "itemQuantity": 2,
                                                              "itemDescription": "API Invoice Item"
                                                            }
                                                          ]
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Invoice details saved succcessfully",
                                                            "data": {
                                                                "invoiceId": "INV-1234657-TSL015",
                                                                "externalInvoiceId":"SHA-789456",
                                                                "customerId": "CUS-1234657-DS8TVB",
                                                                "externalCustomerId": "EXT-CUST-123",
                                                                "invoiceStatus": "Open",
                                                                "invoiceRefrence": "CZU1091",
                                                                "invoiceDueDate": "2022-11-03",
                                                                "invoiceBalance": "37.00",
                                                                "invoiceAppliedAmount": "0.00",
                                                                "invoiceTotal": "37.00",
                                                                "invoiceTimeCreated": "2022-11-03 14:40:41",
                                                                "invoiceTaxData": null,
                                                                "totalTax": "0.00",
                                                                "invoiceItem": [
                                                                    {
                                                                        "itemLineID": "8962863",
                                                                        "itemID": "PRO-615691-E4M5SP",
                                                                        "externalItemId": "EXT-ITEM-E4M5SP",
                                                                        "itemRefID": null,
                                                                        "itemtotalAmount": "37.00",
                                                                        "itemQty": "2",
                                                                        "itemDescription": "API Invoice Item",
                                                                        "itemPrice": "18.5",
                                                                        "itemName": "ACER-ASPIRE-XU507U",
                                                                        "itemTaxApplied": "0",
                                                                        "itemTaxType": null
                                                                    }
                                                                ]
                                                            },
                                                            "code": 200
                                                        }

Subscriptions

Manage your customer subscriptions.

Create a subscription template for a customer.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
planId Plan ID Yes Integer - -
planName Plan Name Yes String - -
durationList Duration Yes String - Pass 0 if it is having unlimited recurrence.
payCycle Pay Cycle Yes String - Pay cycle options: 1wk, 2wk, mon, qtr, six, yrl, 2yr and 3yr.
gatewayId Gateway ID Yes Integer - Merchant configured gateway Id.
autoPay Auto Pay Yes Integer - Either 1 or 0.
1 means Yes and 0 means No.
emailRecurrance Email recurrence Yes Integer - Either 1 or 0.
1 means Yes and 0 means No.
freeTrial Free Trial Yes Integer - If more than 0 then plan cycle will be free for that many recurrences.
shortUrl URL Yes String - -
billingInfo Billing Info Yes Integer - Either 1 or 0.
1 means Yes and 0 means No.
requireShipping Shipping Required Yes Integer - Either 1 or 0.
1 means Yes and 0 means No.
requireService Service Required Yes Integer - Either 1 or 0.
1 means Yes and 0 means No.
productId[] Product ID Yes Integer - Can have one or more products.
quantity[] Product Quantity Yes Float - -
oneTimeCharge[] One Time Charge Yes String - -
description[] Description Yes String - -
unitRate[] Unit Rate Yes Float - -
total[] Total Yes Float - -
planUrl Plan URL Yes String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/subscription/create_plan

Request Example

                                                    
                                                        {
                                                          "planName": "Test Plan",
                                                          "durationList": "0",
                                                          "payCycle": "mon",
                                                          "gatewayId": "526",
                                                          "autoPay": "1",
                                                          "emailRecurrance": "0",
                                                          "freeTrial": "0",
                                                          "shortUrl": "testpl",
                                                          "billingInfo": "1",
                                                          "requireShipping": "1",
                                                          "requireService": "1",
                                                          "productId": ["PRO-674319-T059CH"],
                                                          "quantity": ["1"],
                                                          "oneTimeCharge": ["0"],
                                                          "description": ["test description"],
                                                          "unitRate": ["2.00"],
                                                          "total": ["2.00"],
                                                          "planUrl": "",
                                                          "planId": ""
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Subscription plan created succsessfully.",
                                                            "data": 46,
                                                            "code": 200
                                                        }

Get all subscription templates.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/subscription/get_subscription_plans_data

Request Example

                                                    
                                                        {
                                                          "page": "0",
                                                          "limit": "100"
                                                        }

Response Example

                                                    
                                                        {
                                                          "message": "Subscription plans",
                                                          "data": [
                                                            {
                                                              "planID": "48",
                                                              "merchantDataID": "478",
                                                              "planName": "Test Plan",
                                                              "subscriptionPlan": "0",
                                                              "freeTrial": "0",
                                                              "invoiceFrequency": "mon",
                                                              "subscriptionAmount": "10.00",
                                                              "totalInvoice": "0",
                                                              "generatedInvoice": "0",
                                                              "totalAmount": null,
                                                              "paidAmount": null,
                                                              "paymentGateway": "704",
                                                              "automaticPayment": "1",
                                                              "emailRecurring": "0",
                                                              "usingExistingAddress": "1",
                                                              "createdAt": "2021-02-26 10:41:44",
                                                              "updatedAt": null,
                                                              "postPlanURL": "testpl",
                                                              "merchantPlanURL": "https://demo.demo.com",
                                                              "isShipping": "1",
                                                              "isService": "1",
                                                              "confirm_page_url": "0",
                                                              "proRate": "0",
                                                              "proRateBillingDay": "0",
                                                              "nextMonthInvoiceDate": "0",
                                                              "autoBilling": "1",
                                                              "creditCard": "0",
                                                              "eCheck": "0",
                                                              "gatwayName": "NMI",
                                                              "plan_items": [
                                                                {
                                                                  "itemID": "125",
                                                                  "itemListID": "21",
                                                                  "itemFullName": "test description",
                                                                  "itemDescription": "test description",
                                                                  "itemQuantity": "1",
                                                                  "itemRate": "10.00",
                                                                  "itemTax": "0",
                                                                  "oneTimeCharge": "0",
                                                                  "planID": "48",
                                                                  "invoiceDataID": "0"
                                                                }
                                                              ]
                                                            }
                                                          ],
                                                          "code": 200
                                                        }

Create a subscription for a customer.

Setting up a subscription can be done without first creating a subscription template. If you supply a subscription template in the subPlanId field it will ignore all fields that exist in the subscription plan template upon subscription creation/edit.

Subscriptions with a start date of today will be billed immediately. If the customer is billed immediately you will be provided invoice information. Subscriptions will always be created regardless of successful or failure creation of invoice or transaction. All subscriptions create a customer invoice and that invoice is linked to the transaction for the subscription. Upon creation and billing of the customer you can find the IsPaid key in the invoice to know immediately if capturing the payment was successful. If the subscription transaction fails (bad billing information, card declined, etc.) it will try again the next day. After 3 attempts we will re-create the invoice with the balance due. All transactions that fail will email the customer regarding their failed transaction. Chargezoom will continue to attempt to bill their subscription daily until a successful transaction occurs. To stop attempting billing a customer you must delete the subscription.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Restrictions
subscriptionName Subscription Name is not required but can be used for display purposes. No String -
subPlanId subPlanId can be created from the Create Subscription Template endpoint. If you provide a subPlanId all items with a red * by the requirements will be ignored and used only from the template. No Integer -
durationList Duration list occurs by providing the total amount of times you want the subscription ran. The calculation becomes (subscription cost / duration list) = charge amount per pay cycle. So a $1000 yearly cost broken down into monthly payments would be a durationList of 12, pay cycle of "mon", the calculated product total would be $1000. Then the customer would be charged $83.33 per month. Yes* Integer Pass 0 if recurrence is unlimited. *Ignored if subPlanId provided.
payCycle The pay cycle will be how often you want the customer to be billed. Yes* String Plan cycle option: "dly", "1wk", "2wk", "mon", "2mn", "qtr", "six", "yrl", "2yr" and "3yr". *Ignored if subPlanId provided.
proRate If you choose a subscription recurring of monthly you can enable prorate billing. To enter Prorate data and charge next month data this must be 1 and payCycle must be "mon". No Integer [1,0]
proBillingDate Enter the day of the month you want to charge on. No Integer This field is only valid if your payCycle is "mon" and proRate is set to 1.
proNextBillingDate Enter the day of the month after which the following month will also be included on the first invoice. No Integer This field is only valid if your payCycle is "mon" and proRate is set to 1.
customerID Customer unique identifier. Yes String Customer Unique
autoPay If you do not enable autoPay the subscription will ignore cardId and any payment details to be saved. It will also not bill the invoice that is generated when the subscription is created. No payments will be made unless the invoice is manually charged. Yes* Integer Either 1 or 0. 1 means Yes and 0 means No. *Ignored if subPlanId provided.
generateDate Generation date is the date of which the subscription was generated but not first billing. For example you can have generate date be today or a day in the past and start date be today or start date be tomorrow. If no generate date provided it will be set to the date subscription created. No String Date format: YYYY/MM/DD
startDate If you set the start date to todays date they will be billed upon creation of the subscription. The start date is first day the charges start occuring. Yes String Date format: YYYY/MM/DD
emailRecurring Send a recurring email invoice Yes* Integer Either 1 or 0. 1 means Yes and 0 means No. *Ignored if subPlanId provided.
freeTrial Free trial subscription Yes* String *Ignored if subPlanId provided.
taxId Tax ID No Integer -
gatewayId Gateway ID Yes* Integer Gateway ID of merchant configured gateway. *Ignored if subPlanId provided.
productId[] Subscription item ID Yes* Integer *Ignored if subPlanId provided.
quantity[] Quantity Yes* Float *Ignored if subPlanId provided.
oneTimeCharge[] One time charge Yes* Integer Either 1 or 0. 1 means Yes and 0 means No. *Ignored if subPlanId provided.
description[] Description is used as the item/service name and description of item. Yes* String *Ignored if subPlanId provided.
unitRate[] Rate Yes* Float *Ignored if subPlanId provided.
taxCheck[] Tax check Yes* Integer Either 1 or 0. 1 means Yes and 0 means No. *Ignored if subPlanId provided.
cardId The cardId can either be created in Customers->Create Payment Method. Or you can submit "new1" as the cardId and it will create a saved payment method during the creation of the subscription. Yes String Must be "new1" or the cardId number
cardNumber Card number Yes (if cardId equal to "new1" and paymentMethod equal to 1) String Must be 15 or 16 digits number.
expMonth Expiration month Yes (if cardId equal to "new1" and paymentMethod equal to 1) Integer Month must be a two-digit number. For single-digit months, prepend with a leading zero (eg: 01-12).
expYear Expiration year Yes (if cardId equal to "new1" and paymentMethod equal to 1) Integer -
cvv Card CVV Yes (if cardId equal to "new1" and paymentMethod equal to 1) Integer Must be 3 or 4 digits number.
eaccountNumber eCheck account number Yes (if cardId equal to "new1" and payment method equal to 2) Int -
erouteNumber eCheck route number Yes(if cardId equal to "new1" and payment method equal to 2) Int -
eaccountName eCheck account holder name Yes(if cardId equal to "new1" and payment method equal to 2) String -
eaccountType eCheck account type Yes(if cardId equal to "new1" and payment method equal to 2) String -
eaccountHolderType eChek account holder type Yes(if cardId equal to "new1" and payment method equal to 2) String -
friendlyName Card friendly name Yes String -
billinfo This is a check to use an existing address on file for the customer. We recommend you submit the address anyway for both billing and non-billing address fields even if it is the same data. Yes* String Either 1 or 0. 1 means Yes and 0 means No. *Ignored if subPlanId provided.
bAddress1 Billing address 1 No String -
bAddress2 Billing address 2 No String -
bCity Billing city No String -
bState Billing state No String -
bCountry Billing country No String -
bZipcode Billing zipcode No Integer -
bPhone Billing phone No Integer Phone number should be 10 digits long.
address1 Address 1 (Non-billing) Yes String -
address2 Address 2 (Non-billing) Yes String -
city City (Non-billing) No String -
state State (Non-billing) No String -
country Country (Non-billing) No String -
zipcode Zipcode (Non-billing) No Integer -
phone Phone (Non-billing) No Integer Phone number should be 10 digits long.

URL

                                                    
                                                        https://merchantapi.payportal.com/subscription/create_subscription

Request Example

                                                    
                                                        {
                                                          "startDate": "2024-10-16",
                                                          "freeTrial": 0,
                                                          "autoPay": 1,
                                                          "gatewayId": 2714,
                                                          "oneTimeCharge": [
                                                            1,
                                                            0
                                                          ],
                                                          "productId": [
                                                            15,
                                                            25
                                                          ],
                                                          "quantity": [
                                                            1,
                                                            1
                                                          ],
                                                          "unitRate": [
                                                            5,
                                                            300
                                                          ],
                                                          "description": [
                                                            "$5.00 One-Time Setup Fee",
                                                            "$300 Yearly Gold Plan"
                                                          ],
                                                          "taxCheck": [
                                                            0,
                                                            0
                                                          ],
                                                          "customerID": "6491379",
                                                          "durationList": "12",
                                                          "subscriptionName": "Antivirus Gold Plan",
                                                          "emailRecurring": 1,
                                                          "payCycle": "dly",
                                                          "address1": "7400 Center ave.",
                                                          "address2": "",
                                                          "city": "Huntington Beach",
                                                          "state": "CA",
                                                          "country": "USA",
                                                          "zipcode": "92647",
                                                          "phone": "1231231232",
                                                          "cardId": "new1",
                                                          "cardNumber": "4761000000000001",
                                                          "expMonth": "10",
                                                          "expYear": "2025",
                                                          "baddress1": "7400 Center ave.",
                                                          "baddress2": "",
                                                          "bcity": "Huntington Beach",
                                                          "bstate": "CA",
                                                          "bcountry": "USA",
                                                          "bzipcode": "92647",
                                                          "bphone": "1231231232"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Subscription created succsessfully.",
                                                            "data": [
                                                                {
                                                                    "subscriptionID": "158",
                                                                    "customerID": "6831448",
                                                                    "merchantDataID": "82",
                                                                    "subscriptionName": "test",
                                                                    "proRate": "0",
                                                                    "proRateBillingDay": "0",
                                                                    "nextMonthInvoiceDate": "0",
                                                                    "subscriptionPlan": "12",
                                                                    "freeTrial": "0",
                                                                    "invoiceFrequency": "mon",
                                                                    "subscriptionAmount": "40.43",
                                                                    "totalInvoice": "12",
                                                                    "generatedInvoice": "1",
                                                                    "totalAmount": "0.00",
                                                                    "paidAmount": "0.00",
                                                                    "generatingDate": null,
                                                                    "firstDate": "2022-10-19",
                                                                    "nextGeneratingDate": "2022-11-19",
                                                                    "startDate": "2022-10-19",
                                                                    "endDate": "2023-09-18",
                                                                    "paymentGateway": "526",
                                                                    "automaticPayment": "1",
                                                                    "emailRecurring": "0",
                                                                    "usingExistingAddress": "0",
                                                                    "cardID": "1146",
                                                                    "address1": "1234 Center ave.",
                                                                    "address2": "",
                                                                    "country": "USA",
                                                                    "state": "CA",
                                                                    "city": "Huntington Beach",
                                                                    "zipcode": "92647",
                                                                    "contactNumber": "1231231232",
                                                                    "createdAt": null,
                                                                    "updatedAt": "2022-02-25 22:27:02",
                                                                    "taxID": "0",
                                                                    "planID": "0",
                                                                    "baddress1": "1234 Center ave.",
                                                                    "baddress2": "",
                                                                    "bcountry": "USA",
                                                                    "bstate": "CA",
                                                                    "bcity": "Huntington Beach",
                                                                    "bzipcode": "92647",
                                                                    "subscriptionStatus": "1",
                                                                    "isSubscriptionDelete": "0",
                                                                    "FullName": "John Doe - 1",
                                                                    "companyName": "John Doe LLC",
                                                                    "planName": "Sprinkle",
                                                                    "gatewayID": "***",
                                                                    "gatewayFriendlyName": "***",
                                                                    "gatewayUsername": "*******",
                                                                    "gatewayPassword": "22",
                                                                    "gatewaySignature": "",
                                                                    "extra_field_1": "",
                                                                    "merchantID": "276",
                                                                    "gatewayType": "17",
                                                                    "status": "0",
                                                                    "gatewayMerchantID": "",
                                                                    "creditCard": "1",
                                                                    "echeckStatus": "1",
                                                                    "isSurcharge": "0",
                                                                    "surchargePercentage": "0",
                                                                    "set_as_default": "1",
                                                                    "enable_level_three_data": "0",
                                                                    "items": [
                                                                        {
                                                                            "itemID": "734",
                                                                            "itemListID": "1",
                                                                            "itemFullName": "really cool product",
                                                                            "itemDescription": "really cool product",
                                                                            "itemQuantity": "1",
                                                                            "itemRate": "13.00",
                                                                            "itemTax": "0",
                                                                            "oneTimeCharge": "0",
                                                                            "subscriptionID": "158",
                                                                            "invoiceDataID": "34278",
                                                                            "itemLineID": null,
                                                                            "TxnLineID": null,
                                                                            "itemTotal": null
                                                                        },
                                                                        {
                                                                            "itemID": "735",
                                                                            "itemListID": "2",
                                                                            "itemFullName": "wow howdy",
                                                                            "itemDescription": "wow howdy",
                                                                            "itemQuantity": "1",
                                                                            "itemRate": "14.00",
                                                                            "itemTax": "0",
                                                                            "oneTimeCharge": "1",
                                                                            "subscriptionID": "158",
                                                                            "invoiceDataID": "34278",
                                                                            "itemLineID": null,
                                                                            "TxnLineID": null,
                                                                            "itemTotal": null
                                                                        },
                                                                        {
                                                                            "itemID": "736",
                                                                            "itemListID": "3",
                                                                            "itemFullName": "so cool",
                                                                            "itemDescription": "so cool",
                                                                            "itemQuantity": "1",
                                                                            "itemRate": "12.75",
                                                                            "itemTax": "0",
                                                                            "oneTimeCharge": "0",
                                                                            "subscriptionID": "158",
                                                                            "invoiceDataID": "34278",
                                                                            "itemLineID": null,
                                                                            "TxnLineID": null,
                                                                            "itemTotal": null
                                                                        },
                                                                        {
                                                                            "itemID": "737",
                                                                            "itemListID": "4",
                                                                            "itemFullName": "some product",
                                                                            "itemDescription": "some product",
                                                                            "itemQuantity": "2",
                                                                            "itemRate": "0.34",
                                                                            "itemTax": "0",
                                                                            "oneTimeCharge": "0",
                                                                            "subscriptionID": "158",
                                                                            "invoiceDataID": "34278",
                                                                            "itemLineID": null,
                                                                            "TxnLineID": null,
                                                                            "itemTotal": null
                                                                        }
                                                                    ],
                                                                    "invoices": [
                                                                        {
                                                                            "id": "4421",
                                                                            "TxnID": "34278",
                                                                            "EditSequence": null,
                                                                            "TimeCreated": "2022-10-21 00:01:47",
                                                                            "TimeModified": "2022-10-21 00:01:47",
                                                                            "RefNumber": "CHZ171-20035",
                                                                            "poNumber": null,
                                                                            "Customer_ListID": "6831448",
                                                                            "Customer_FullName": "John Doe - 1",
                                                                            "ShipAddress_Addr1": "1234 Center ave.",
                                                                            "ShipAddress_Addr2": "",
                                                                            "ShipAddress_City": "Huntington Beach",
                                                                            "ShipAddress_State": "CA",
                                                                            "ShipAddress_Country": "USA",
                                                                            "ShipAddress_Province": null,
                                                                            "ShipAddress_PostalCode": "92647",
                                                                            "BalanceRemaining": "40.43",
                                                                            "AppliedAmount": "0.00",
                                                                            "DueDate": "2022-10-19",
                                                                            "invoiceDate": "2024-01-30",
                                                                            "IsPaid": "false",
                                                                            "InvoiceMemo": null,
                                                                            "userStatus": "Active",
                                                                            "insertInvID": "34278",
                                                                            "invoiceRefNumber": "20035",
                                                                            "checkNumber": null,
                                                                            "paymentDate": null,
                                                                            "Billing_Addr1": "1234 Center ave.",
                                                                            "Billing_Addr2": "",
                                                                            "Billing_City": "Huntington Beach",
                                                                            "Billing_State": "CA",
                                                                            "Billing_Country": "USA",
                                                                            "Billing_PostalCode": "92647",
                                                                            "customerMemo": null,
                                                                            "TaxRate": "0.00",
                                                                            "TotalTax": "0",
                                                                            "TaxListID": "",
                                                                            "qb_status": "0",
                                                                            "qb_inv_companyID": "15683",
                                                                            "qb_inv_merchantID": "82",
                                                                            "isTxnDelete": "0",
                                                                            "leftDay": "29",
                                                                            "ListID": "6831448",
                                                                            "FullName": "John Doe - 1",
                                                                            "status": "Upcoming",
                                                                            "c_status": "Done"
                                                                        }
                                                                    ]
                                                                }
                                                            ],
                                                            "code": 200
                                                        }

Get all customer subscriptions.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/subscription/get_subscriptions_data

Request Example

                                                    
                                                        {
                                                          "page": "0",
                                                          "limit": "100"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Subscription list",
                                                            "data": [
                                                                {
                                                                    "subscriptionID": "96",
                                                                    "customerID": "2",
                                                                    "merchantDataID": "478",
                                                                    "subscriptionName": "",
                                                                    "subscriptionPlan": "0",
                                                                    "freeTrial": "0",
                                                                    "invoiceFrequency": "mon",
                                                                    "subscriptionAmount": "2.00",
                                                                    "totalInvoice": "0",
                                                                    "generatedInvoice": "0",
                                                                    "totalAmount": null,
                                                                    "paidAmount": null,
                                                                    "generatingDate": "1",
                                                                    "firstDate": "2020-02-01",
                                                                    "nextGeneratingDate": "2020-02-01",
                                                                    "startDate": "2020-01-20",
                                                                    "endDate": "2020-01-20",
                                                                    "paymentGateway": "0",
                                                                    "automaticPayment": "1",
                                                                    "emailRecurring": "0",
                                                                    "usingExistingAddress": "0",
                                                                    "cardID": "1670",
                                                                    "address1": "",
                                                                    "address2": "",
                                                                    "country": "",
                                                                    "state": "",
                                                                    "city": "",
                                                                    "zipcode": "",
                                                                    "baddress1": null,
                                                                    "baddress2": null,
                                                                    "bcountry": null,
                                                                    "bstate": null,
                                                                    "bcity": null,
                                                                    "bzipcode": null,
                                                                    "bphone": null,
                                                                    "contactNumber": "",
                                                                    "createdAt": "2021-02-26 11:03:08",
                                                                    "updatedAt": "2021-02-26 11:03:08",
                                                                    "taxID": "0",
                                                                    "planID": "48",
                                                                    "subscriptionStatus": "1",
                                                                    "fullName": "Demo Shop",
                                                                    "companyName": "Demo Shop",
                                                                    "planName": null,
                                                                    "gatewayID": null,
                                                                    "gatewayFriendlyName": null,
                                                                    "items": [
                                                                        {
                                                                            "itemID": "222",
                                                                            "itemListID": "27",
                                                                            "itemFullName": "test description",
                                                                            "itemDescription": "test description",
                                                                            "itemQuantity": "1",
                                                                            "itemRate": "2.00",
                                                                            "itemTax": "0",
                                                                            "oneTimeCharge": "0",
                                                                            "subscriptionID": "96",
                                                                            "invoiceDataID": "0"
                                                                        }
                                                                    ]
                                                                }
                                                            ],
                                                            "code": 200
                                                        }

Delete a subscription. Subscriptions cannot be edited but they can be marked deleted. This does not delete the original subscription historical data or invoice historical data.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type
deleteSubscriptionId Subscription ID you wish to delete. Yes String/Int

URL

                                                    
                                                        https://merchantapi.payportal.com/subscription/delete_subscription

Request Example

                                                    
                                                        {
                                                            "subscriptionID": "96"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Subscription deleted successfully.",
                                                            "data": null 
                                                            "code": 200
                                                        }

Retrieve subscription dunning Management data.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/subscription/dunningManagement

Response Example

                                                    
                                                        {
                                                            "message": "Dunning Managment",
                                                            "data": {
                                                                "period": "15",
                                                                "frequency": "2,4,5,10,15",
                                                                "doWithSubscriptions": "1",
                                                                "doWithInvoices": "1",
                                                                "trialSubscriptions": "1"
                                                            },
                                                            "code": 200
                                                        }

Create or Edit a subscription dunning management.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type
period Chargezoom will retry payment collection during this period. You can choose a final action to be applied on subscriptions and invoices if customers don't pay up by the end of this period. No String/Int
frequency Specify the intervals after which you want to retry payment collection. For example, if you specify 1, 4, 9, then payment collection will be retried after 1, 4, and 9 days from the invoice due date. No String/Int
doWithSubscriptions When dunning period ends, what happens to invoices?
Final action to be taken at the end of the dunning period, if invoice is unpaid. This is applicable for recurring invoices only.
1 for Retain as Active
2 for Cancel Subscriptions 		No String/Int
doWithInvoices When dunning period ends, what happens to invoices?
1 for Mark As Not Paid
2 for Mark As Voided 		No String/Int
trialSubscriptions Dunning for Trial subscriptions
0 or 1 		No String/Int

URL

                                                    
                                                        https://merchantapi.payportal.com/subscription/dunningManagement

Request Example

                                                    
                                                        {
                                                            "period": "15",
                                                            "frequency": "2,4,5,10,15",
                                                            "doWithSubscriptions": "1",
                                                            "doWithInvoices": "1",
                                                            "trialSubscriptions": "1"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Changes to Dunning Managment were saved successfully!",
                                                            "data": {
                                                                "period": "15",
                                                                "frequency": "2,4,5,10,15",
                                                                "doWithSubscriptions": "1",
                                                                "doWithInvoices": "1",
                                                                "trialSubscriptions": "1"
                                                            },
                                                            "code": 200
                                                        }

Payments

Manage customer payments and transactions.

Create a sale transaction authorizing a payment.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
customerId customerId Yes String - -
paymentMethod Payment Method Type ( 1 for Credit Card & 2 for ACH) Yes integer - [1,2]
cardId Card unique identifier Yes String new1 -
cardNumber Card Number Yes(if cardId not equal to "new1" and payment method equal to 1) Int - -
cardCvv Card CVV Yes(if cardId not equal to "new1" and payment method equal to 1) Int - -
expMonth Card expire month Yes(if cardId not equal to "new1" and payment method equal to 1) Int - -
expYear Card expire year Yes(if cardId not equal to "new1" and payment method equal to 1) Int - -
eaccountNumber eCheck account number Yes(if cardId not equal to "new1" and payment method equal to 2) Int - -
erouteNumber eCheck route number Yes(if cardId not equal to "new1" and payment method equal to 2) Int - -
eaccountName eCheck account holder name Yes(if cardId not equal to "new1" and payment method equal to 2) String - -
eaccountType eCheck account type Yes(if cardId not equal to "new1" and payment method equal to 2) String - -
eaccountHolderType eChek account holder type Yes(if cardId not equal to "new1" and payment method equal to 2) String - -
payAmount Amount to be paid Yes Float -
bAddress Customer Business Address Line No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Country field should have a valid ISO 3166 country code No String - -
customerEmail Customer Email No String - -
customerContact Customer Contact No String - -
gatewayId Gateway unique ID Yes Int - -
invoiceId Invoice unique ID No String - -
poNumber PO Number No Int - -
sendEmail Send an email with transaction No Int - [0,1]
referenceMemo Reference memo No String - -
applySurcharge Surcharge(1 for Enable, 0 for Disable) No boolean - [1,0]

URL

                                                    
                                                        https://merchantapi.payportal.com/payments/sale

Request Example

                                                    
                                                        {
                                                            "customerId": "CUS-123457-9WV1YK",
                                                            "paymentMethod": "1",
                                                            "cardId": "new1",
                                                            "cardNumber": "4111111111111111",
                                                            "cardCvv": "1234",
                                                            "expMonth": "02",
                                                            "expYear": "2025", 
                                                            "payAmount": 5.00,   
                                                            "gatewayId": "2469"
                                                            "applySurcharge": "1"
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": "7406132281",
                                                          "message": "Payment Successful",
                                                          "code": 200
                                                        }

Create authorization payment for a customer. The response data number is the transaction id number. You can use this number to void or capture the transaction.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
customerId Customer unique identifier Yes String - -
cardId Card unique identifier Yes String - -
cardNumber Card number Yes(if cardId not equal to "new1") Int - -
cardCvv Card CVV Yes(if cardId not equal to "new1") Int - -
expMonth Card expire month Yes(if cardId not equal to "new1") Int - -
expYear Card expire year Yes(if cardId not equal to "new1") Int - -
payAmount Amount to be paid Yes Float - -
bAddress Customer Business Address Line No String - -
bCity Customer Business Address City No String - -
bState Customer Business Address State/Province No String - -
bZipcode Customer Business Address ZipCode No String - -
bCountry Country field should have a valid ISO 3166 country code No String - -
customerEmail Customer Email No String - -
customerContact Customer Contact No String - -
gatewayId Gateway unique identifier Yes Int - -
poNumber PO Number No Int - -
sendEmail Send an email to customer No Int 0 [1,0]
referenceMemo Reference Memo No String - -
applySurcharge Surcharge(1 for Enable, 0 for Disable) No boolean - [1,0]

URL

                                                    
                                                        https://merchantapi.payportal.com/payments/auth

Request Example

                                                    
                                                        {
                                                            "customerId": "CUS-1234567-9WV1YK",
                                                            "paymentMethod": "1",
                                                            "cardId": "new1",
                                                            "cardNumber": "4111111111111111",
                                                            "cardCvv": "1234",
                                                            "expMonth": "02",
                                                            "expYear": "2025", 
                                                            "payAmount": 5.00,   
                                                            "gatewayId": "2469"
                                                            "applySurcharge": "1"
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": "7406185193",
                                                          "message": "Payment Successful",
                                                          "code": 200
                                                        }

Create a card authorization capture event transaction. Return response data is the transaction id number.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
transactionId Transaction unique identifier Yes String - -
invoiceId Invoice unique identifier No String - -
payAmount Amount to be paid Yes(if invoiceId has value) Float - -
sendEmail Email to be sent to customer No Int 0 [1,0]

URL

                                                    
                                                        https://merchantapi.payportal.com/payments/capture

Request Example

                                                    
                                                        {
                                                            "transactionId": "7479739594", 
                                                            "payAmount": 5.00
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": "7479739594",
                                                          "message": "Payment Successful",
                                                          "code": 200
                                                        }

Create a refund. Transaction id can be retrieved from data of previous auth capture, payment, or sale events. You can also refund a specific invoice which must include the payAmount to be refunded. Amounts but not be more than the original transaction amount.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
transactionId Transaction unique identifier Yes String - -
invoiceRefundData invoiceId and payAmount No Array - -
payAmount Amount to be refunded Yes(if invoiceRefundData column does not have value) Float - -
sendEmail Email to be sent to customer No Int 0 [1,0]

URL

                                                    
                                                        https://merchantapi.payportal.com/payments/refund

Request Example

                                                    
                                                        {
                                                            "transactionId": "200028607652",
                                                            "payAmount": 5.00
                                                        }

Request Example

                                                    
                                                        {
                                                            "transactionId": "200028607652",
                                                            "invoiceRefundData": [
                                                                {
                                                                    "invoiceId":"INV-4729343-ME84RW", 
                                                                    "payAmount":20
                                                                }
                                                            ]
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": "200028607652",
                                                          "message": "Transaction Refunded",
                                                          "code": 200
                                                        }

Void a transaction.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
transactionId Transaction unique identifier Yes String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/payments/void

Request Example

                                                    
                                                        {
                                                            "transactionId": "7406185193"
                                                        }

Response Example

                                                    
                                                        {
                                                          "data": "7406185193",
                                                          "message": "Transaction Voided",
                                                          "code": 200
                                                        }

Retrieve all transactions.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Restrictions
page *Page Number (Starting - 0) * No Int -
limit Listing Limit Count (requires a limit, 0 provides no results) Yes Int -
customerId Customer unique identifier No String -
transactionId Transaction unique identifier No String -
dateTo Date To No String Date format: YYYY/MM/DD
dateFrom Date From No String Date format: YYYY/MM/DD

URL

                                                    
                                                        https://merchantapi.payportal.com/payments/list/transactions

Request Example

                                                    
                                                        {
                                                            "limit": "100"
                                                        }

Response Example

                                                    
                                                        {
                                                          "code": 200,
                                                          "message": "All transactions",
                                                          "data": [
                                                            {
                                                              "tnxID": "123654668468",
                                                              "tnxAmount": "20.00",
                                                              "tnxDate": "2022-07-14 02:19:07",
                                                              "tnxStatus": "Success",
                                                              "tnxCustomerId": "CUS-1234567-NPIE2O",
                                                              "tnxType": "refund",
                                                              "tnxGateway": "Heartland",
                                                              "tnxGatewayId": "642",
                                                              "tnxCode": "200",
                                                              "tnxUserStatus": "2",
                                                              "tnxPaymentMethod": "1",
                                                              "tnxCustomDataFields": "{\"payment_type\":\"Visa - 1111\"}",
                                                              "tnxReferenceMemo": null,
                                                              "tnxInvoiceId": "INV-1234567-ME84RW",
                                                              "tnxInvoiceRef": "CHZ10305"
                                                            }
                                                          ]
                                                        }

Product & Services

Use the products and services object to create items, products, and services.

Create a new product or item. Body parameters follow for your type of integration (QBO, QBD, FreshBooks, XERO, NAP, etc)

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
externalItemId externalItemId No String - -
itemType Supported Type : Service, NonInventory, OtherCharge, Subtotal, Group, Payment and Discount. Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemSku Item SKU Yes String - -
itemType Item Type Yes String - -
itemSalePrice Item sale price Yes Float - -
itemSaleDescription Item sale description Yes String - -
itemPurchasePrice Item purchase or list price. Yes Float - -
itemPurchaseDescription Item purchase description Yes String - -
itemQuantity Item quantity No Float - -
parentItemId Parent Item Id No String - -
expenseAccountId Item expense Account Id No Int - -
incomeAccountId Item income Account Id No Int - -
inventoryAccountId Item inventory Account Id No Int - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemSku Item SKU Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
itemPurchasePrice Item purchase Price Yes Float - -
itemPurchaseDescription Item purchase description Yes String - -
parentItemId Parent Item Id No String - -
expenseAccountId Item expense Account Id No Int - -
incomeAccountId Item income Account Id No Int - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Parent Item Id No String - -
incomeAccountId Item income Account Id Yes String - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemDiscount Item discount Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Parent Item Id No String - -
incomeAccountId Item income Account Id Yes String - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSaleDescription Item Sale description Yes String - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
itemQuantity Item quantity Yes Float - -
incomeAccountId Item income Account Id Yes String - -
inventoryType Item inventory Type No String - -
inventoryStock Item inventory Stock Yes(if you input the value inventoryType ) Int - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
itemCode Item code Yes String - -
itemAccountId Item Account Id Yes String - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Item parent Item Id No String - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemDiscount Item discount Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Item parent Item Id No String - -
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSaleDescription Item Sale description Yes String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/products/create

Request Example

                                                    
                                                        {
                                                            "itemName": "ACER-ASPIRE-XU507U",
                                                            "externalItemId": "EXT-ITEM-123",
                                                            "itemType": "Noninventory",
                                                            "itemSalePrice": "10",
                                                            "itemPurchaseDescription": "Acer Aspire Series"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Product Created Successfully",
                                                            "data": {
                                                                "czItemId": "588",
                                                                "externalItemId": "EXT-ITEM-123",
                                                                "ListID": "PRO-1234657-E4M5SP",
                                                                "EditSequence": null,
                                                                "IsActive": "true",
                                                                "TimeCreated": "2022-08-05 21:07:44",
                                                                "TimeModified": null,
                                                                "Name": "ACER-ASPIRE-XU507U",
                                                                "FullName": "ACER-ASPIRE-XU507U",
                                                                "Type": "Noninventory",
                                                                "Parent_ListID": "",
                                                                "Parent_FullName": null,
                                                                "ManufacturerPartNumber": null,
                                                                "SalesTaxCode_ListID": null,
                                                                "SalesTaxCode_FullName": null,
                                                                "BuildPoint": null,
                                                                "ReorderPoint": null,
                                                                "QuantityOnHand": "0",
                                                                "AverageCost": null,
                                                                "QuantityOnOrder": "0",
                                                                "QuantityOnSalesOrder": "0",
                                                                "AccountRef": null,
                                                                "TaxRate": null,
                                                                "SalesPrice": "10",
                                                                "SalesDesc": "Acer Aspire Series",
                                                                "PurchaseCost": null,
                                                                "PurchaseDesc": null,
                                                                "PrefVendor_ListID": null,
                                                                "PrefVendor_FullName": null,
                                                                "companyListID": "228",
                                                                "Discount": "0.00",
                                                                "DepositToAccountRef": null,
                                                                "DepositToAccountName": null,
                                                                "PaymentMethodRef": null,
                                                                "PaymentMethodName": null
                                                            },
                                                            "code": 200
                                                        }

Retrieve a specific item details and attributes.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String

URL

                                                    
                                                        https://merchantapi.payportal.com/products/{itemID}

Response Example

                                                    
                                                        {
                                                            "data": {
                                                                "itemId": "PRO-213654-E4M5SP",
                                                                "externalItemId": "EXT-ITEM-123",
                                                                "itemName": "ACER-ASPIRE-XU507U",
                                                                "itemType": "Noninventory",
                                                                "itemStatus": "Active",
                                                                "itemSalePrice": "10",
                                                                "itemParentId": "",
                                                                "itemSaleDescription": "Acer Aspire Series",
                                                                "itemAccountId": null
                                                            },
                                                            "message": "Item Detail Get Successfully",
                                                            "code": 200
                                                        }

Get list of items/products.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
page Page Number (Starting - 0) Yes Int - -
limit Listing Limit Count (0 for unlimited) Yes Int - -
search Filter Customer by [ itemName, externalItemId ] No String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/products/all

Request Example

                                                    
                                                        {
                                                            "page": 0,
                                                            "limit": 100
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Item Detail Get Successfully",
                                                            "data": [
                                                                {
                                                                    "itemId": "PRO-123654-E4M5SP",
                                                                    "externalItemId": "EXT-ITEM-123",
                                                                    "itemName": "ACER-ASPIRE-XU507U",
                                                                    "itemType": "Noninventory",
                                                                    "itemStatus": "Active",
                                                                    "itemSalePrice": "10",
                                                                    "itemParentId": "",
                                                                    "itemSaleDescription": "Acer Aspire Series",
                                                                    "itemAccountId": null
                                                                }
                                                            ],
                                                            "code": 200
                                                        }

Update item/product status.

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemStatus Item status Yes Integer - Aceepted Values [ 1, 0 ]

URL

                                                    
                                                        https://merchantapi.payportal.com/products/status_update

Request Example

                                                    
                                                        {
                                                            "itemId": "PRO-1234657-E4M5SP",
                                                            "itemStatus": "1"
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": {
                                                                "message": "Your Item Active",
                                                                "itemId": "PRO-1234657-E4M5SP"
                                                            },
                                                            "data": null,
                                                            "code": 200
                                                        }

Update item/product details. Body parameters follow for your type of integration (QBO, QBD, FreshBooks, XERO, NAP, etc).

Header Parameters
Key Description Required Type
secretKey API secret key Yes String
token Access token received from the login authentication response Yes String
Body Parameters
Key Description Required Type Default Restrictions
itemName Item name Yes String - -
externalItemId externalItemId No String - -
itemType Supported Type : Service, NonInventory, OtherCharge, Subtotal, Group, Payment and Discount. Yes String - -
itemSalePrice Item sale Price No Float - -
itemSaleDescription Item Sale description No String - -
itemPurchaseDescription Item purchase description No String - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemSku Item SKU Yes String - -
itemType Item Type Yes String - -
itemSalePrice Item sale price Yes Float - -
itemSaleDescription Item sale description Yes String - -
itemPurchasePrice Item purchase or list price. Yes Float - -
itemPurchaseDescription Item purchase description Yes String - -
itemQuantity Item quantity No Float - -
parentItemId Parent Item Id No String - -
expenseAccountId Item expense Account Id No Int - -
incomeAccountId Item income Account Id No Int - -
inventoryAccountId Item inventory Account Id No Int - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemSku Item SKU Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
itemPurchasePrice Item purchase Price Yes Float - -
itemPurchaseDescription Item purchase description Yes String - -
parentItemId Parent Item Id No String - -
expenseAccountId Item expense Account Id No Int - -
incomeAccountId Item income Account Id No Int - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Parent Item Id No String - -
incomeAccountId Item income Account Id Yes String - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemDiscount Item discount Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Parent Item Id No String - -
incomeAccountId Item income Account Id Yes String - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSaleDescription Item Sale description Yes String - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
itemQuantity Item quantity Yes Float - -
incomeAccountId Item income Account Id Yes String - -
inventoryType Item inventory Type No String - -
inventoryStock Item inventory Stock Yes(if you input the value inventoryType ) Int - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
itemCode Item code Yes String - -
itemAccountId Item Account Id Yes String - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSalePrice Item sale Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Item parent Item Id No String - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemDiscount Item discount Price Yes Float - -
itemSaleDescription Item Sale description Yes String - -
parentItemId Item parent Item Id No String - -
Key Description Required Type Default Restrictions
itemId Item Id Yes String - -
itemName Item name Yes String - -
itemType Item type Yes String - -
itemSaleDescription Item Sale description Yes String - -

URL

                                                    
                                                        https://merchantapi.payportal.com/products/edit

Request Example

                                                    
                                                        {
                                                            "itemId": "PRO-1233546-E4M5SP",
                                                            "externalItemId": "EXT-ITEM-124",
                                                            "itemName": "ACER-ASPIRE-XU507U",
                                                            "itemType": "Noninventory",
                                                            "itemSalePrice": "10",
                                                            "itemSaleDescription": "Acer Aspire Series",
                                                            "itemPurchaseDescription": ""
                                                        }

Response Example

                                                    
                                                        {
                                                            "message": "Product Upadate Successfully",
                                                            "data": {
                                                                "czItemId": "588",
                                                                "externalItemId": "EXT-ITEM-124",
                                                                "ListID": "PRO-1233546-E4M5SP",
                                                                "EditSequence": null,
                                                                "IsActive": "true",
                                                                "TimeCreated": "2022-08-05 22:13:26",
                                                                "TimeModified": null,
                                                                "Name": "ACER-ASPIRE-XU507U",
                                                                "FullName": "ACER-ASPIRE-XU507U",
                                                                "Type": "Noninventory",
                                                                "Parent_ListID": "",
                                                                "Parent_FullName": null,
                                                                "ManufacturerPartNumber": null,
                                                                "SalesTaxCode_ListID": null,
                                                                "SalesTaxCode_FullName": null,
                                                                "BuildPoint": null,
                                                                "ReorderPoint": null,
                                                                "QuantityOnHand": "0",
                                                                "AverageCost": null,
                                                                "QuantityOnOrder": "0",
                                                                "QuantityOnSalesOrder": "0",
                                                                "AccountRef": null,
                                                                "TaxRate": null,
                                                                "SalesPrice": "10",
                                                                "SalesDesc": "Acer Aspire Series",
                                                                "PurchaseCost": null,
                                                                "PurchaseDesc": null,
                                                                "PrefVendor_ListID": null,
                                                                "PrefVendor_FullName": null,
                                                                "companyListID": "228",
                                                                "Discount": "0.00",
                                                                "DepositToAccountRef": null,
                                                                "DepositToAccountName": null,
                                                                "PaymentMethodRef": null,
                                                                "PaymentMethodName": null
                                                            },
                                                            "code": 200
                                                        }