Introduction

Kapcharge serves as an online payment infrastructure, offering a comprehensive suite of software and APIs tailored for businesses of various sizes. Our technology empowers businesses to accept payments, facilitate payouts, and efficiently manage their financial transactions.

Through cutting-edge innovation, we automate the processing of both inbound and outbound payments. Kapcharge streamlines payment processing services by providing a unified API connecting businesses with the banking and payment ecosystem.

Our commitment lies in delivering the most secure and dependable payment processing service across Canada and the United States, supported by robust risk management and data analytics. With a fully integrated suite of payment solutions, we equip our customers with everything they need to handle payment acceptance and payout processes seamlessly.

Financial terminologies

Canada	Description
Institution Number	An institution number is the three-digit code assigned to each bank to uniquely identify it.
Transit Number	A transit number is a 5-digit branch number that can be found on the bottom of your personal cheques.
Card Number	Most of the credit cards and debit cards have a 16-digit unique number.
CVV	The CVV(Card Verification Value) number is a three-digit or four-digit number depending on your card network.
Expiry Month	The expiration date can be found on the card, written as XX/XX (month and year)pos.
Expiry Year	The expiration date can be found on the card, written as XX/XX (month and year).

Bank Terminology

Kapcharge Payment Gateway

Transaction Types

Description	Transaction Types
Collect	Allows the transfer of funds from a customer's bank account to your merchant account. This transaction is completed in real time.
Pay	Allows the transfer of funds from a merchant account directly to a customer's bank account. This transaction is completed in real time.

Payment Methods

Method	Description	Duration	Send Transaction	Request Transaction
EFT	Electronic funds transfer between banks	3 times a day	Yes	Yes
Interac	Online e-transfers, user receives an e-mail or SMS	Immediately	Yes	Yes
Visa Direct	Visa rails to push funds directly to visa card	Immediately	Yes	No
V/MC Debit	V/MC Debit payments/checkout to collect funds	Immediately	No	Yes

Payment Methods Overview

API Specification

API Introduction

This technical integration specification document explains the KAPCHARGE Payment Gateway new API. It enables merchant systems to post real-time transaction requests to KAPCHARGE Payment Gateway.

This part of the documentation discusses the technical requirements for real-time integration only. For specifications relating to Batch File Uploading or using Virtual Terminals to create and send the transactions online, please refer to the other services of the Kapcharge.

API Specifics

All API requests must pass the header Content-type: application/json; unless explicitly mentioned.

Postman Collection

Follow these steps to quickly get started with the Kapcharge API:

Once you have access to your staging environment:

1) Download and install the Postman app

2) Install the Kapcharge Postman Collection. Click the "Run in Postman" button below to install

3) In Postman find the endpoint /OAuth GET AccessToken within Authentication folder, paste your api {{ClientID}} and {{ClientSecret}} and it's all set.

Kapcharge Swagger API

Swagger API

OAuth GET AccessToken

Bearer Token Authorization is used for all API requests. Multiple API calls can be made securely without requiring authorization each time with a Bearer Token.

Payload

Authentication Payload

{
  "clientId":{{ClientID}}
  "clientSecret":{{ClientSecret}}
}

HTTP Request

Method: POST
Endpoint: {{Application URL}}/api/v1/OAuth/token

Make sure to replace {{Application URL}} with API Application URL as per the environment.

curl --location -g --request POST '{{Application URL}}/api/v1/OAuth/token'

The above command returns JSON structured like this:

{
    "accessToken": "{JWT Token}",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "expiresOn": 1666298431

}

You must replace {{Application URL}} with API Application URL as per the environment.

Parameter	Type	Mandatory
clientId	String	Yes
clientSecret	String	Yes

Responses

Parameter	Description
accessToken	The authorization token that needs to be used throughout the API request.
tokenType	This will always be "Bearer" token type.
expiresIn	This is token expiration time (seconds).
expiresOn	This is token validation end-time (epoch time).

Transaction API

Create Transactions

Sample Request Payload

Sample Request Payload

[   
    {   
        "MerchantId": "TEST_123-KC",    
        "Currency": "CAD",  
        "ClientReference": "JohnDoe",   
        "AmountInCents": 100,   
        "DueDate": "2023-01-13",    
        "TransactionFlow": "Debit",
        "TransactionMethod": "Interac",
        "IsInteracViaSMS": "true",  
        "Description":"Sample payload of a transaction",
        "Customer": {   
            "FirstName": "John",    
            "LastName": "Doe",  
            "CompanyName": "Sample Co",
            "AddressLine1": "1234 Est", 
            "AddressLine2": "App #208",    
            "City": "Montreal", 
            "Country": "CA",    
            "Province": "QC",   
            "PostalCode": "H3Z2H7", 
            "Email": "[email protected]",   
            "PhoneNumber": "6477891234" 
        },  
        "CustomerBankAccount": {    
            "InstitutionName": "ABC Bank",  
            "InstitutionNumber": "001", 
            "AccountNumber": "1234567", 
            "TransitNumber": "12345",   
            "AccountOwnershipType": "INDIVIDUAL"    
        },
        "PaymentAuthentication": {
            "HasSecurityQuestionAndAnswer": true,
            "Question": "What colour is my shirt?",
            "Answer": "BLUERAIN"
        },
        "DeviceInfo": {        
            "IpAddress": "1.0.0.125",
            "DeviceFingerprint": "3p2yZ#WsyQQC99VANt6yxG7n6RU"        
        }
    }
]

HTTP Request

Method: POST
Endpoint: {{ Application Url }}/api/v1/transaction

You must replace {{Application Url}} with Application Url as per the environment.
For any parameter related to Country ,please use the alpha-2 standard.
Follow the link below:

ISO Country Codes

Transaction Request

Parameter	Type	Mandatory	Description
MerchantId	String	Yes	Merchant id (maximum 15 characters).
Currency	String	Yes	Either "CAD" or "USD" only (maximum 3 characters).
ClientReference	String	Yes	Client Reference (maximum 100 characters).
AmountInCents	Integer	Yes	Transaction amount in cents.
DueDate	String	Yes	Due date for the transaction (Format: YYYY-MM-DD).
TransactionFlow	String	Yes	Either "Collect" or "Pay" only.
TransactionMethod	String	Yes	Either "EFT" or "Interac" only.
IsInteracViaSMS	String	No	The value should be "true" to send money via SMS and "false" by default.
Customer	Object	Yes	Pass the Customer object with all the required details as seen in Customer below.
CustomerBankAccount	Object	Yes (EFT only)	Pass the Customer Bank Account object with all the required details as seen in Customer Bank Account below.
PaymentAuthentication	Object	No	Pass the PaymentAuthentication object with all the required details as seen in Payment Authentication below (Only when Transaction Method is Interac).
DeviceInfo	Object	No	Pass the DeviceInfo object with all the required details as seen in Device Info below (Only when Transaction Method is Interac).

Customer

Parameter	Type	Mandatory	Description
FirstName	String	Yes (except for EFT & Interac transaction with AccountOwnershipType BUSINESS)	First Name of the customer (maximum 100 characters).
LastName	String	Yes (except for EFT & Interac transaction with AccountOwnershipType BUSINESS)	Last Name of the customer (maximum 100 characters).
CompanyName	String	Yes (only for EFT & Interac transaction with AccountOwnershipType BUSINESS)	Company Name of the customer (maximum 100 characters). (maximum 100 characters).
AddressLine1	String	Yes (EFT only)	Billing Address Line 1 (maximum 255 characters).
AddressLine2	String	No	Billing Address Line 2 (maximum 255 characters).
City	String	Yes (EFT only)	Billing address city (maximum 100 characters).
Country	String	Yes (EFT only)	Billing address country (maximum 4 characters).Refer notice below.
Province	String	Yes (EFT only)	Billing address state/province (maximum 100 characters).
PostalCode	String	Yes (EFT only)	Billing address postal code (maximum 20 characters).
Email	String	Yes (EFT only)	Customer email (maximum 100 characters).
PhoneNumber	String	Yes for EFT or for Interac when IsInteracViaSMS="true"	Phone number (maximum 50 characters, no special characters accepted).

curl --location -g --request POST '{{ Application Url }}/api/v1/transaction'

Make sure to replace {{Application Url}} with Application Url as per the environment. For any parameter related to Country ,please use the alpha-2 standard.
Follow the link below:
ISO Country Codes.

You must replace {{Application Url}} with Application Url as per the environment.
For any parameter related to Country ,please use the alpha-2 standard.
Follow the link below:

ISO Country Codes

The above command returns JSON structured like this:
Status Code : 200 OK

[
    {
        "kapchargeTransactionId": 12345679,
        "clientReference": "JohnDoe",
        "transactionStatus": "Accepted",
        "transactionFlow": "Pay",
        "amountInCents": 100,
         "errors": [
            {
                "message": ""
            }
         ]
    }
]

Status Code : 400 Bad Request

    {
        "title": "One or more validation errors occurred.",
        "status": "400",
        "detail": "Please refer to the errors property for additional details.",
        "instance": "/api/v1/Transaction",
        "errors": {
            "[0].Customer.Province": [
               "The Province is required. Invalid Canadian province"
             ]
        }  
    }

Status Code : 500 Internal Server Error

    {
        "title": "An error has occured",
        "detail": "Please refer to the errors property for additional details",
        "status": 500,
        "errors": [
            {
                "code": "InternalServerError",
                "message": "The Amount must be greater than 0.01.",
                "developerMessage": ""
            }
        ]
    }

Customer Bank Account (For EFT only)

Parameter	Type	Mandatory	Description
InstitutionName	string	yes	Customer Institution/Bank Name (maximum 100 characters).
InstitutionNumber	string	yes	Customer Institution/Bank Number (maximum 3 characters).
AccountNumber	string	yes	Customer Account Number (maximum 12 characters).
TransitNumber	string	yes	Customer Transit Number (maximum 50 characters).
AccountOwnershipType	string	yes	Either BUSINESS or INDIVIDUAL only.

Payment Authentication (For Interac Only)

Parameter	Type	Mandatory	Description
Question^*	String	Yes	The question for the user to process the interac request.
Answer^*	String	Yes	The answer for the user to process the interac request.

Device Info (For Interac Only)

Parameter	Type	Mandatory	Description
IpAddress	String	Yes	The IP address of the UserId, the sender, of the funds. Required if Accounts Payable with Interac, and peer-to-peer enabled.
DeviceFingerprint	String	Yes	A unique identifier supplied by Kapcharge for DeviceFingerprint is always required.

Responses

Parameter	Description
kapchargeTransactionId	The unique transaction ID generated by Kapcharge.
clientReference	Transaction reference provided by the client.
transactionStatus	Refer KAPCHARGE Bank Status Response Codes here.
transactionFlow	Either "Collect" or "Pay".
amountInCents	Transaction amount in cents.
listOfErrors	Error message (only when there is some error processing request).

Get a specific transaction

Get a specific transaction

curl --location -g --request GET '{{ Application Url }}/api/v1/transaction/12345679'

Make sure to replace {{Application Url}} with Application Url as per the environment.

HTTP Request

Method: GET
Endpoint: {{ Application Url }}/api/v1/transaction/<TransactionID>

The above command returns JSON structured like this:

{
    "kapchargeTransactionId": 12345679,
    "clientReference": "SmithDoe",
    "transactionStatus": "Accepted",
    "transactionFlow": "Collect",
    "amountInCents": 200,
    "availabledate" : "2022-10-26T15:36:30.265Z",
    "declineddate" : "2022-10-27T15:36:30.265Z",
    "transactionEvents": [
        {
            "eventDate": "2022-10-25T17:46:38.791Z",
            "eventType": "SUBMITTED",
            "description": "CREATED_BY_EFT_FILE_JOB"
        },
        {
            "eventDate": "2022-10-25T15:36:30.265Z",
            "eventType": "CREATED"
        }
    ]
}

You must replace {{Application Url}} with Application Url as per the environment.

This endpoint retrieves a specific transaction request based on transaction id.

Responses

Parameter	Description
kapchargeTransactionId	The unique transaction ID generated by Kapcharge.
clientReference	Transaction reference provided by the client.
transactionStatus	Refer KAPCHARGE Bank Status Response Codes here.
transactionFlow	Either "Collect" or "Pay".
amountInCents	Transaction amount in cents.
availabledate	Date that EFT transaction is settled to wallet.
declineddate	Date that transaction was Returned or Declined.

Search transactions

Search transactions

curl --location -g --request GET '{{Application Url}}/api/v1/Transaction/search?MerchantId=mk2'

Make sure to replace {{Application Url}} with Application Url as per the environment.

HTTP Request

Method: GET
Endpoint: {{ Application Url }}/api/v1/transaction/search?<>Parameters

The above command returns JSON structured like this:

{
    "results": [
        {
            "createdDateTime": "2023-11-20T00:01:26.7179746",
            "availabledate" : "2022-10-26T15:36:30.265Z",
            "declineddate" : "2022-10-27T15:36:30.265Z",
            "merchantId": "KPC_211-TEST",
            "kapchargeTransactionId": 12648286,
            "clientReference": "232145214",
            "transactionStatus": "Accepted",
            "transactionFlow": "Pay",
            "amountInCents": 110,
            "customer": {
                "customerFullName": "CustomerFirstName CustomerLastName",
                "email": "[email protected]"
            }
        },
        {
            "createdDateTime": "2023-11-20T00:01:25.0257408",
            "merchantId": "KPC_211-TEST",
            "kapchargeTransactionId": 12648285,
            "clientReference": "ScheduleTest",
            "transactionStatus": "Accepted",
            "transactionFlow": "Pay",
            "amountInCents": 110,
            "customer": {
                "customerFullName": "CustomerFirstName CustomerLastName",
                "email": "[email protected]"
            }
        }
    ],
    "currentPage": 1,
    "pageCount": 1,
    "pageSize": 10,
    "rowCount": 2,
    "firstRowOnPage": 1,
    "lastRowOnPage": 2
}

You must replace {{Application Url}} with Application Url as per the environment.

Get Transaction Request Parameters

Parameter	Type	Mandatory	Default	Description
MerchantId	String	Yes		Merchant id (maximum 15 characters).
Page	Int	No	1
PageSize	Int	No	10
createdDateTimeFrom	DateTime	No		Transaction Created DateTime From .
createdDateTimeTo	DateTime	No		Transaction Created DateTime To .
TransactionFlow	String	No		Either "Collect" or "Pay" only.
TransactionStatus	String	No		Refer KAPCHARGE Bank Status Response Codes here.
Source	Int	No		Refer KAPCHARGE Transaction Sources here.

KAPCHARGE Transaction Sources

Description	Source Code	Description
FILE	1	Indicates the transaction was created through File.
API	5	Indicates the transaction was created through API.
VT	6	Indicates the transaction was created through Virtual terminal.
ADR	7	Indicates the transaction was created through ADR.

Cancel a specific transaction

HTTP Request

Method: DELETE
Endpoint: {{Application Url}}/api/v1/transaction/<TransactionID>

HTTP Request

Method: DELETE
Endpoint: {{Application Url}}/api/v1/transaction/<TransactionID>

Delete a specific transaction

curl --location -g --request DELETE '{{Application Url}}/api/v1/transaction/12345679'

Make sure to replace {{Application Url}} with Application Url as per the environment.

You must replace {{Application Url}} with Application Url as per the environment.

The above command returns JSON structured like this:

{
    "kapchargeTransactionId": 12345679,
    "clientReference": "12345679",
    "transactionStatus": "Cancelled",
    "transactionFlow": "Collect",
    "amountInCents": 200
}

This endpoint deletes a specific transaction request based on transaction id.

Responses

Parameter	Description
kapchargeTransactionId	The unique transaction ID generated by Kapcharge.
clientReference	Transaction reference provided by the client.
transactionStatus	Refer KAPCHARGE Bank Status Response Codes here.
transactionFlow	Either "Collect" or "Pay".
amountInCents	Transaction amount in cents.

KAPCHARGE Transaction Status

Status Name	Description
Created	Indicates the transaction was acknowledged by the bank/processor.
Processing	Indicates the transaction is being processed.
Accepted	Indicates the transaction was accepted by the bank/processor.
Cancelled	Indicates the transaction was cancelled by the merchant.
Returned (EFT only)	Indicates the transaction was returned by the bank.
Declined	Indicates the transaction was declined by the bank, processor or customer.
TrnError	Indicates the transaction has validation or connectivity error and was not successfully processed.
Fraud (Interac Only)	Indicates the transaction was confirmed as Fraud by Kapcharge or Merchant.
FraudBlock (Interac Only)	Indicates the transaction was flagged as a potential fraud transaction by Interac.

V/MC Debit and Visa Direct Transaction

Create V/MC Debit and Visa Direct Transactions for a new customer

V/MC Debit and Visa Direct transactions are executed with a different endpoint and authorization key for a new customer.

Name	Description
Skyflow endpoint	https://{{transaction_inbound_url}}/api/v1/transaction

Create V/MC Debit and Visa Direct Transactions

Create V/MC Debit and Visa Direct Transactions

[   
    {
        "MerchantId": "KPC_201-KPCHRG",
        "Currency": "CAD",
        "ClientReference": "referenceNewClient",
        "AmountInCents": "121",
        "DueDate": "2024-01-22",
        "TransactionFlow": "Collect",
        "TransactionMethod": "CreditCard",
        "Customer": {
            "FirstName": "Andrew",
            "LastName": "Torress",
            "AddressLine1": "888",
            "city": "ogoki",
            "country": "ca",
            "province": "QC",
            "postalcode": "j7c0n6",
            "email": "[email protected]",
            "PhoneNumber": "5145551414"
        },
        "CustomerCreditCard": {
            "Number": "4111111111111111",
            "ExpiryMonth": "12",
            "ExpiryYear": "27",
            "Cvv": "999"
        }
    }
]

HTTP Request

Method: POST
Endpoint: {{ transaction_inbound_url }}/api/v1/transaction

Transaction Request

Parameter	Type	Mandatory	Description
MerchantId	String	Yes	Merchant id (maximum 15 characters).
Currency	String	Yes	Either "CAD" or "USD" only (maximum 3 characters).
ClientReference	String	Yes	Client Reference (maximum 100 characters).
AmountInCents	Integer	Yes	Transaction amount in cents.
DueDate	String	Yes	Due date for the transaction (Format: YYYY-MM-DD).
TransactionFlow	String	Yes	Either "Collect" for V/MC debit or "Pay" for VisaDirect.
TransactionMethod	String	Yes	CreditCard or VisaDirect.
Customer	Object	Yes	Pass the Customer object with all the required details as seen in Customer.
CustomerCreditCard	Object	Yes	The V/MC Debit or Visa direct information of the customer.

Customer Credit Card

Parameter	Type	Mandatory	Description
Number	String	Yes	Card number.
ExpiryMonth	String	Yes	The 2 digits of card expiration month.
ExpiryYear	String	Yes	The last 2 digits of card expiration year.
Cvv	String	Yes	The 3-4 digits of Cvv (Card Verification Value) the security feature on credit cards

The above command returns JSON structured like this:
Status Code : 200 OK

[
    {
        "amountInCents": 121,
        "clientReference": "referenceNewClient",
        "customer": {
            "creditCardToken": "4111115933501111",
            "customerFullName": "ANDREW TORRESS",
            "email": "[email protected]"
        },
        "kapchargeTransactionId": 12676894,
        "responseCode": "100",
        "transactionFlow": "COLLECT",
        "transactionStatus": "Accepted"
    }
]

Responses

Parameter	Description
amountInCents	Transaction amount in cents.
clientReference	Transaction reference provided by the client.
Customer	The Customer response information Object
kapchargeTransactionId	The unique transaction ID generated by Kapcharge.
responseCode	The response code of the transaction.
transactionFlow	Either "Collect" for V/MC debit or "Pay" for VisaDirect.
transactionStatus	Refer KAPCHARGE Bank Status Response Codes here.

Customer response information

Parameter	Description
creditCardToken	A token generated when a transaction is created for a new customer.
customerFullName	The full name of the new created customer.
email	The email of the new created customer.

Create V/MC Debit and Visa Direct Transactions for an existing customer

To create a V/MC Debit and Visa Direct transaction for an existing customer you need the creditCardToken generated when the first transaction for the customer was created. You only need to provide the creditCardToken in the CustomerCreditCard object if (ExpirationMonth, ExpiryYear, CVV, Number) are not send. You will use the Kapcharge endpoint to create a transaction for an existing customer.

Sample Request Payload

Sample Request Payload

[   
    {
        "MerchantId": "KPC_201-KPCHRG",
        "Currency": "CAD",
        "ClientReference": "referenceClient",
        "AmountInCents": "121",
        "DueDate": "2024-01-22",
        "TransactionFlow": "Collect",
        "TransactionMethod": "Collect",
        "Customer": {
            "FirstName": "Andrew",
            "LastName": "Torress",
            "AddressLine1": "888",
            "city": "ogoki",
            "country": "ca",
            "province": "QC",
            "postalcode": "j7c0n6",
            "email": "[email protected]",
            "PhoneNumber": "5145551414"
        },
        "CustomerCreditCard": {
            "Token": "4111115933501111",
        }
    }
]

HTTP Request

Method: POST
Endpoint: {{ Application URL }}/api/v1/transaction

Transaction Request

Parameter	Type	Mandatory	Description
MerchantId	String	Yes	Merchant id (maximum 15 characters).
Currency	String	Yes	Either "CAD" or "USD" only (maximum 3 characters).
ClientReference	String	Yes	Client Reference (maximum 100 characters).
AmountInCents	Integer	Yes	Transaction amount in cents.
DueDate	String	Yes	Due date for the transaction (Format: YYYY-MM-DD).
TransactionFlow	String	Yes	Either "Collect" for V/MC debit or "Pay" for VisaDirect.
TransactionMethod	String	Yes	CreditCard or VisaDirect.
Customer	Object	Yes	Pass the Customer object with all the required details as seen in Customer.
CustomerCreditCard	Object	Yes	the V/MC Debit or Visa direct information of the customer.

Customer Credit Card info

Parameter	Type	Mandatory	Description
Token	String	Yes if (ExpirationMonth, ExpiryYear, CVV, Number) are not send	The generated token provided after the creation of the first transaction for the customer.

The above command returns JSON structured like this: Status Code : 200 OK

[
    {
        "kapchargeTransactionId": 12676894,
        "clientReference": "referenceClient",
        "transactionStatus": "Accepted",
        "transactionFlow": "COLLECT",
        "amountInCents": 121,   
         "customer": {
            "customerFullName": "ANDREW TORRESS",
            "email": "[email protected]",
             "creditCardToken": "4111115933501111",
        }
    }
]

Responses

Parameter	Description
kapchargeTransactionId	The unique transaction ID generated by Kapcharge.
clientReference	Transaction reference provided by the client.
transactionStatus	Refer KAPCHARGE Bank Status Response Codes here.
transactionFlow	Either "Collect" for V/MC debit or "Pay" for VisaDirect.
amountInCents	Transaction amount in cents.
Customer	Customer response information Object.

Refund a transaction

You have the possibility to refund a customer by using the request bellow.

HTTP Request

Method: DELETE
Endpoint: {{Application Url}}/api/v1/transaction/refund/<TransactionID>

Refund a specific transaction

HTTP Request

Method: DELETE
Endpoint: {{Application Url}}/api/v1/transaction/refund/<TransactionID>

Refund a specific transaction

curl --location -g --request DELETE '{{Application Url}}/api/v1/transaction/refund/56345679'

Make sure to replace {{Application Url}} with Application Url as per the environment.

You must replace {{Application Url}} with Application Url as per the environment.

The above command returns JSON structured like this:

{
    "kapchargeTransactionId": 56345679,
    "transactionStatus": "Accepted",
    "transactionFlow": "Collect",
    "amountInCents": 200
}

This endpoint refund a specific transaction request based on transaction id.

Responses

Parameter	Description
kapchargeTransactionId	The unique transaction ID generated by Kapcharge.
transactionStatus	Refer KAPCHARGE Bank Status Response Codes here.
transactionFlow	Either "Collect" or "Pay".
amountInCents	Transaction amount in cents.

Webhooks Configuration

Overview

Overview of Webhook Configuration API: WebHook Configuration API step-by-Step Overview

The webhooks aim to give your organization a real-time update on returned transactions.

Update a Webhooks configuration for a specific merchant

Payload

Update Merchant Webhooks Configuration Payload

{
  "merchantId": "TEST_123-KC",
  "webhookEnabled": false,
  "webhookUrl": " https://www.webhook.com/",
  "webhookAuthenticationHeader": "TEST AUTH HEADER"
}

HTTP Request

Method: PUT
Endpoint: {{Application Url}}/api/v1/configuration

GET http://example.com/kittens/<ID>

To enable webhooks, you must send the below information through the API.

You must replace {{Application Url}} with Application Url as per the environment.

Parameter	Description
merchantId	The unique merchant ID generated by Kapcharge.
webhookEnabled	Boolean (true or false),true => Transaction Rejection notification => ON, false => Transaction Rejection notification => OFF.If ON => Notification will be received on the webhook url.
webhookUrl	Merchant webhook url.
webhookAuthenticationHeader	Merchant webhook authentication header.

curl --location -g --request PUT '{{Application Url}}/api/v1/configuration'

Make sure to replace {{Application Url}} with Application Url as per the environment.

The above command returns JSON structured like this:

{
    "merchantId": "TEST_123-KC",
    "webhookEnabled": false,
    "webhookUrl": " https://www.webhook.com/",
    "webhookSecret": "{WebHookSecret}",
    "webhookAuthenticationHeader": "TEST AUTH HEADER",
    "oAuthClientId": "{ClientSecret}"
}

This endpoint updates a specific webhooks configuration request based on merchant id.

Responses

Parameter	Description
merchantId	The unique merchant ID generated by Kapcharge.
webhookEnabled	Boolean (true or false),true => Transaction Rejection notification => ON, false => Transaction Rejection notification => OFF.If ON => Notification will be received on the webhook url.
webhookUrl	Merchant webhook url.
webhookSecret	Please refer to Contract or contact Account Manager to obtain.
webhookAuthenticationHeader	Merchant webhook authentication header.
oAuthClientId	Please refer to Contract or contact Account Manager to obtain.

Get Webhooks Configuration for a specific merchant

Identification When a URL is defined, Kapcharge will send a POST request each time there is a status change to "rejected".

HTTP Request

Method: GET
Endpoint: {{Application Url}}api/v1/configuration/<MerchantID>

You must replace {{Application URL}} with Application URL as per the environment.

curl --location -g --request GET '{{Application Url}}/api/v1/configuration/TEST_123-KC'

Make sure to replace {{Application URL}} with Application URL as per the environment.

The above command returns JSON structured like this:

{
    "merchantId": "TEST_123-KC",
    "webhookEnabled": false,
    "webhookUrl": " https://www.webhook.com/",
    "webhookSecret": "{WebHookSecret}",
    "webhookAuthenticationHeader": "TEST AUTH HEADER",
    "oAuthClientId": "{ClientSecret}"
}

This endpoint retrieves a specific webhooks configuration request based on merchant id.

Responses

Parameter	Description
merchantId	The unique merchant ID generated by Kapcharge.
webhookEnabled	Boolean (true or false),true => Transaction Rejection notification => ON, false => Transaction Rejection notification => OFF.If ON => Notification will be received on the webhook url.
webhookUrl	Merchant webhook url.
webhookSecret	Please refer to Contract or contact Account Manager to obtain.
webhookAuthenticationHeader	Merchant webhook authentication header.
oAuthClientId	Please refer to Contract or contact Account Manager to obtain.

Webhook Return Notification

Configure using Webhook Config API

Webhook Return Notification

{
  "transactionId" : 12345678,
  "returnCode" : "{RETURN CODE}",
  "returnDateTime" : "{DATETIME}""
}

Kapcharge sends a return notification to merchants once a transaction is returned. The message body that merchants receive is as follows:

Webhook Return Notification - Test Simulator

This API is protected, which means the user needs to obtain an access token and include the token in the header when calling the API mentioned above. (like our other APIs).

curl --location -g --request POST '{{Application Url}}/api/v1/Transaction/return/12345678'

Make sure to replace {{Application Url}} with Application Url as per the environment.

HTTP Request

Method: POST
Endpoint:{{Application Url}}/api/v1/Transaction/return/<TRANSACTION_ID>

You must replace {{Application Url}} with Application Url as per the environment.

Payload:

The only input required is TRANSACTION_ID.

Response:

There is no response body
API returns 200, 401, or 403

Webhook Return Notification

{
  "transactionId" : 12345678,
  "returnCode" : "{RETURN CODE}",
  "returnDateTime" : "{DATETIME}""
}

How it will work?

API will look into Merchant's Webhook configuration
(Refer: Update Webhooks Configuration here or Get Webhooks Configuration here )
Post a return message to the merchant's webhook URL.
The message body that merchant would receive is as mentioned in Webhook Return Notification here.

EFT Decline Codes

Decline Code	Description
900	Edit Reject
901	NSF (Debit Only)
902	Account not found
903	Payment Stopped/Recalled
905	Account Closed
907	No Debit Allowed
908	Funds Not Cleared (Debit Only)
909	Currency/Account Mismatch
910	Payor/Payee Deceased
911	Account Frozen
912	Invalid/Incorrect Account No.
914	Incorrect Payor/Payee Name
915	No Agreement Existed
916	Not According to Agreement - Personal
917	Agreement Revoked – Personal
918	No Confirmation/Pre-Notification – Personal
919	Not According to Agreement – Business
920	Agreement Revoked – Business
921	No Confirmation/Pre-Notification – Business
922	Customer Initiated Return
990	Institution in Default

Interac Decline Codes

Decline Code	Description
800	Customer Declined
801	Deposit Failed
802	Security Answer Failure
803	Deposit Pending
804	Expired

V/MC Card Decline Codes

Decline Code	Description
200	Transaction was declined by processor.
201	Do not honor.
202	Insufficient funds.
203	Over limit.
204	Transaction not allowed.
220	Incorrect payment information.
221	No such card issuer.
222	No card number on file with issuer.
223	Expired card.
224	Invalid expiration date.
225	Invalid card security code.
226	Invalid PIN.
240	Call issuer for further information.
250	Pick up card.
251	Lost card.
252	Stolen card.
253	Fraudulent card.
260	Declined with further instructions available. (See response text)
261	Declined-Stop all recurring payments.
262	Declined-Stop this recurring program.
263	Declined-Update cardholder data available.
264	Declined-Retry in a few days.
300	Transaction was rejected by gateway.
400	Transaction error returned by processor.
410	Invalid merchant configuration.
411	Merchant account is inactive.
420	Communication error.
421	Communication error with issuer.
430	Duplicate transaction at processor.
440	Processor format error.
441	Invalid transaction information.
460	Processor feature not available.
461	Unsupported card type.

Visa Direct Decline Codes:

Decline Code	Description
01	Refer to card issuer
02	Refer to card issuers special conditions
03	Invalid merchant
04	Pick-up
05	Do not honor
06	Error
07	Pick-up card, special conditions
08	Honor with identification
09	Request in progress
10	Approved for partial amount
11	Approved (VIP)
12	Invalid transaction
13	Invalid amount
14	Invalid card number (no such number)
15	No such issuer
16	Approved, update track 3
17	Customer cancellation, reversal (unsupported)
18	Customer dispute, chargeback (future)
19	Re-enter transaction
20	Invalid response
21	No action taken, reversal (unsupported)
22	Suspected malfunction, reversal (unsupported)
23	Unacceptable transaction fee
24	File update not supported by receiver
25	Unable to locate record on file
26	Duplicate file update record, no action
27	File update field edit error
28	File update record locked out
29	File update not successful, contact acquirer
30	Format error (may also be a reversal)
31	Bank not supported by switch
32	Completed partially, reversal (unsupported)
33	Expired card, pick-up
34	Suspected fraud, pick-up
35	Card acceptor contact acquirer, pick-up
36	Restricted card, pick-up
37	Card acceptor call acquirer security, pick-up
38	Allowable PIN tries exceeded, pick-up
39	No credit account
40	Requested function not supported
41	Lost card, pick-up
42	No universal account
43	Stolen card, pick-up
44	No investment account
45	Reserved for ISO use
46	Reserved for ISO use
47	Reserved for ISO use
48	Reserved for ISO use
49	Reserved for ISO use
50	Reserved for ISO use
51	Insufficient funds
52	No checking account
53	No savings account
54	Expired card
55	Incorrect PIN
56	No card record
57	Transaction not permitted to cardholder
58	Transaction not permitted to terminal (may also be a chargeback)
59	Suspected fraud
60	Card acceptor contact acquirer
61	Exceeds withdrawal amount limit
62	Restricted card
63	Security violation (may also be a chargeback)
64	Original amount incorrect, reversal (unsupported)
65	Exceeds withdrawal frequency limit
66	Card acceptor call acquirer security
67	Hard capture, pick-up
68	Response received too late, reversal (unsupported)
69	Reserved for ISO
70	Reserved for ISO
71	Reserved for ISO
72	Reserved for ISO
73	Reserved for ISO
74	Reserved for ISO
75	Allowable number of PIN tries exceeded
76	Key synchronization error (FIS)
77	Reserved for private use
78	Customer not eligible for POS (Star SM )
79	Invalid digital signature
80	Stale dated transaction (Star SM )
81	Issuer requested standin
82	Count exceeds limit (VISANet)
83	Reserved for private use
84	Time limit for pre-authorization reached (VISANet)
85	Issuer has no reason to decline the transaction (Account Verification)
86	Cannot verify PIN (VISANet)
87	Check already posted
88	Information not on file
89	Card verification value (CVV) verification failed (no pickup)
90	Cutoff is in progress
91	Issuer or switch is inoperative
92	Financial institution or intermediate network unknown for routing
93	Transaction cannot be completed, violation of law
94	Duplication transaction
95	Reconcile error
96	System malfunction
97	Reserved for national use
98	Reserved for national use
99	Card network fault error
0Z-9Z	Reserved for ISO use
C2-E0	Reserved for national use (X9.2)
EZ-MZ	Reserved for national use (X9.2)
N0	Authorization life cycle unacceptable
N1	Authorization life cycle expired
R2	Allowable PAN entries warning -- approved
R3	Approved with overdraft protection
R4	Bad CVV3
S0	Check not acceptable for cash
S1	Check not acceptable
S2	Check deposit limit exceeded
S3	Cash back limit exceeded
S4	Check amount does not match courtesy amount
S5	PIN not selected
S6	PIN already selected
S7	Unmatched voucher information
S8	Allowable PAN entries exceeded -- denial
S9	Expiration date mismatch
SA	Inactive card
SB	Expiration date mismatch (card pickup)
SC	Item suspected for stop pay
SD	Account closed
SE	Ineligible account
SF	Item submitted more than two times
SG	No account on file - absolute
SH	Unable to locate
SI	General denial
SJ	Item settled via ACH
SK	Cross-reference card not found
SL	Category limit exceeded
SM	Transaction limit exceeded
SN	Daily limit exceeded
SO	Monthly limit exceeded
SP	Invalid secret code
SQ	PIN key sync error
SR	Bad CVV2
SS	Stop payment order
ST	Revocation of authorization order
SV	Stop reoccurring payments
T3	Lost card (no pickup)
T4	Closed account
T5	Dormant account
T6	Special conditions (no pick-up)
T7	Purchase only approval for purchase with cash back transaction.
T9	Insufficient funds for fees
TA	ARQC validation failed for chip card
TB	Unsafe PIN
U0-YZ	Reserved for private use

For more details kindly refer to: Payments Canada (LIST OF RETURN REASON CODES ,Page 9-10) ^

Errors

The Kapcharge API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Invalid or expired access token.
403	Forbidden.
404	Not Found -- The specified endpoint could not be found.
405	Method Not Allowed -- You tried to access the endpoint with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The details requested has been removed from our servers.
429	Too Many Requests -- You reached your quota
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.