Introduction
Kapcharge provides a full suite of payment processing products by Kapital Solutions that support online lenders, eCommerce, and subscription businesses.
Kapcharge provides businesses of all sizes with software and APIs that enable them to accept payments, send payouts, and manage their financial transactions.
Kapcharge furnishes payment processing services through a single API that allows businesses to connect seamlessly with the banking and payment ecosystem. We provide our customers with the most secure and reliable payment processing service in Canada and the United States, backed by risk management and data analytics.
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 routing number is a combination of the 5-digit branch number and the 3-digit financial institution number that can be found on the bottom of your personal cheques. |
Card Number | Most of the credit cards and debit cards are 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) |
Expiry Year | The expiration date can be found on the card, written as XX/XX (month and year) |
In addition to providing a high-level overview of the API, this document also outlines how to call it successfully.
Kapcharge Payment Gateway
Transaction Flow
The transaction flow takes place among three key stakeholders as shown below
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 send and pull funds directly to visa debit card | Immediately | Yes | Yes* |
Credit Card | Credit Card payments/checkout to collect funds | Immediately | No | Yes |
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
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
}
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": "Collect",
"TransactionMethod": "Interac",
"Description":"Test",
"Customer": {
"FirstName": "John",
"LastName": "Doe",
"AddressLine1": "1234 Est",
"AddressLine2": "Testfield",
"City": "Montreal",
"Country": "CA",
"Province": "QC",
"PostalCode": "H3Z2H7",
"Email": "test@test.com",
"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
Transaction Request
Parameter | Type | Mandatory | Default | 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. | |
Customer | object | yes | Pass the Customer object with all the required details as seen in Customer below. | |
CustomerBankAccount | object | yes | 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 | First Name of the customer (maximum 100 characters). |
LastName | string | yes | Last Name of the customer (maximum 100 characters). |
AddressLine1 | string | yes | Billing Address Line 1 (maximum 255 characters). |
AddressLine2 | string | no | Billing Address Line 2 (maximum 255 characters). |
City | string | yes | Billing address city (maximum 100 characters). |
Country | string | yes | Billing address country (maximum 4 characters).Refer notice below. |
Province | string | no | Billing address state/province (maximum 100 characters). |
PostalCode | string | yes | Billing address postal code (maximum 20 characters). |
string | yes | Customer email (maximum 100 characters). | |
PhoneNumber | string | yes | 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.
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
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). |
RoutingNumber | string | yes | In Canada, your routing number is a combination of the 5-digit branch number and the 3-digit financial institution number that can be found on the bottom of your personal cheques. In the U.S. a routing number is a 9-digit number. (maximum 50 characters). |
TransitNumber | string | yes | Customer Transit Number (maximum 50 characters). |
AccountType | string | yes | Check Account Type here. |
AccountOwnershipType | string | yes | Either BUSINESS or INDIVIDUAL only. |
Account Type
Type | Description |
---|---|
PC | Personal Checking |
PS | Personal Savings |
PL | Personal Loan |
BC | Business Checking |
BS | Business Savings |
BL | Business Loan |
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,
"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
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. |
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": "na@na.com"
}
},
{
"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": "na@na.com"
}
}
],
"currentPage": 1,
"pageCount": 1,
"pageSize": 10,
"rowCount": 2,
"firstRowOnPage": 1,
"lastRowOnPage": 2
}
Responses
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. |
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
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 Interac Transactions Status Codes
Status Name | Status Code | Description |
---|---|---|
InProgress | 2 | Indicates the transaction is being processed. |
Accepted | 0 | Indicates the transaction was sent to Interac. |
FraudBlock | 7 | Indicates the transaction was flagged as a potential fraud transaction by Interac. |
System Error | 9000 | Indicates the transaction has validation or connectivity error(s) and was not successfully processed. |
Cancelled | -1 | Indicates the transaction was cancelled by the merchant. |
Declined | 1 | Indicates the transaction was declined by the fund recipient. |
Deposit_Failed | 101 | Indicates the fund transfer failed by recipient financial institution. |
Expired | 102 | Indicates that the fund transfer was expired before being completed by the recipient. |
Security_Answer_Failure | 103 | Indicates that the transaction security question was not answered correctly by the recipient. |
Failed | 105 | Indicates the transaction failed by Interac. |
Deposit_Pending | 107 | Indicates one of the fund transfer steps by the sender was not completed. |
Deposit_Complete | 108 | Indicates the fund transfer was successfully completed. |
Available | 109 | If seen more than a few seconds, indicates the transaction reverted to a previous state for an unknown reason. |
KAPCHARGE EFT Transaction Status Codes
Status Name | Status Code | Description |
---|---|---|
Accepted | 0 | Indicates the transaction was sent to the Bank. |
InProgress | 2 | Indicates the transaction is being processed. |
Returned | 5 | Indicates the transaction was returned by the Bank. |
System Error | 90 | Indicates the transaction has validation or connectivity error(s) and was not successfully processed. |
Cancelled | -1 | Indicated the transaction was deleted by Kapcharge. |
Declined | 1 | Indicated the transaction was declined by Kapcharge as it was not valid. |
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.
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": "TEST URL",
"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>
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
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:
Transaction Return Codes (For Canada Only)
Return 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 |
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
Return 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 |
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. |