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

Authentication

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

}

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

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

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

Responses

Get Transaction Request Parameters

KAPCHARGE Transaction Sources

Cancel a specific transaction

HTTP Request

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

Cancel 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 Transaction Status

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.

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

Customer Credit Card

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

Customer response information

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

Customer Credit Card info

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

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.

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

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

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

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

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>

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: