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

Kapcharge Payment Gateway

Transaction Types

Payment Methods

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) Login in your staging environment,Grab your api {{ClientID}} and {{ClientSecret}}

2) Download and install the Postman app

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

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

Authentication

OAuth GET AccessToken

Bearer Token Authorization is used for all API requests. Multiple API calls can be made securely without requiring authorisation 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

}

Responses

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": "Collect", 
        "TransactionMethod": "Interac", 
        "Description":"Test",
        "Customer": {   
            "FirstName": "John",    
            "LastName": "Doe",  
            "AddressLine1": "1234 Est", 
            "AddressLine2": "Testfield",    
            "City": "Montreal", 
            "Country": "CA",    
            "Province": "QC",   
            "PostalCode": "H3Z2H7", 
            "Email": "[email protected]",   
            "PhoneNumber": "6477891234" 
        },  
        "CustomerBankAccount": {    
            "InstitutionName": "ABC Bank",  
            "InstitutionNumber": "001", 
            "AccountNumber": "1234567", 
            "RoutingNumber": "12345678910", 
            "TransitNumber": "12345",   
            "AccountType": "PC",    
            "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

ISO Country Codes

Transaction Request

Customer

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.

ISO Country Codes

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

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

Status Code : 400 Bad Request

[
    {
        "message": ""
    }
]

Status Code : 403 Forbidden

    {
        "message": ""
    }

Customer Bank Account

Account Type

Payment Authentication (For Interac Only)

Device Info (For Interac Only)

Responses

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,
    "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"
        }
    ]
}

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

Responses

Search transactions

Search transactions

curl --location -g --request GET '{{ Application Url }}/api/v1/Transaction/search?MerchantId=KPC_211-TEST&source=7' 

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",
            "merchantId": "KPC_211-TEST",
            "kapchargeTransactionId": 12648286,
            "clientReference": "Test2321",
            "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
}

Responses

Get Transaction Request Parameters

KAPCHARGE Transaction Sources

Delete a specific transaction

HTTP Request

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

Delete a specific transaction

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.

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

KAPCHARGE Interac Transactions Status Codes

KAPCHARGE EFT Transaction Status Codes

Webhooks Configuration

Overview

Overview of Webhook Configuration API:

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": "TEST URL",
  "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.

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": "TEST URL",
    "webhookSecret": "{WebHookSecret}",
    "webhookAuthenticationHeader": "TEST AUTH HEADER",
    "oAuthClientId": "{ClientSecret}"
}

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

Responses

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>

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": "TEST URL",
    "webhookSecret": "{WebHookSecret}",
    "webhookAuthenticationHeader": "TEST AUTH HEADER",
    "oAuthClientId": "{ClientSecret}"
}

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

Responses

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:

Transaction Return Codes (For Canada Only)

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

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>

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

^

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: