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). |
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 |
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
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
}
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",
"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
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. |
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). |
String | Yes (EFT only) | Customer email (maximum 100 characters). | |
PhoneNumber | String | Yes (EFT only) | 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": "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,
"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": "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
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>
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
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 |
---|---|
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. |
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.
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:
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.
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>
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>
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. |