NAV Navbar
shell c/c++ ruby
  • Introduction
  • General Information
  • How do I ...
  • API Getting Started
  • Devices API Getting Started
  • Introduction

    Welcome to the Kashing! API. You can use our API to access Kashing API endpoints, which can get information on our various products and the integration operations required to integration our solution into your business.

    This document is designed to show how to integrate your application with the Kashing Payment Gateway. It contains everything from how to send requests correctly to our API and how to handle responses from our API. There are a number of per-requisites that will be required to integrate with our API these are listed below.

    We have language bindings in Shell, Ruby, Nodejs, C/C++ and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    This API documentation page was created for Kashing!. Feel free to edit it and use it as a base for your own API's documentation.

    General Information

    Document owner: Kashing Limited

    Version: 2.0

    Date: 14/02/2016

    Support: support@kashing.co.uk

    How do I ...

    Here you will find documentation regarding various topics relating to the Kashing! service.

    Activate my e-commerce service?

    Kashing's e-commerce option automates the payment process and allows you to use various options in taking payments.

    If you have previously set up a Kashing! account, it’s easy to start taking online payments today

    1. Set up your payment policy
    2. Update your T&Cs
    3. Switch on e-commerce
    4. Apply your discount code

    SET UP YOUR PAYMENT POLICY

    Log into your Kashing! account:

    1. Select Organisation from the menu bar.
    2. Select Payment policy from the tabs.

      HTML5 Icon

    3. Select a policy type from the dropdown list:
      a. Normal Transactions: The full payment is taken at the time of booking.
      b. Split Transactions: A deposit is taken at the time of booking followed by the final balance on the date set in Guestlink (see next section). Choose whether to take a percentage of the total bill (eg 50%) or a flat rate (eg '£'50) and enter the amount.
      c. Charge as you go: Card details are secured in an encrypted form but the card is not charged. The card details are validated at the time of booking to ensure that the number is valid, the card hasn't been reported lost or stolen etc. The card can be charged one or more times for any amount and at any time as necessary.
    4. Click Update.

    Clients wishing to integrate their Guestlink services with Kashing! should follow the below mentioned procedure:

    1. Go to eCommerce > Online Payment
    2. Select Kashing! from the Account Supplier dropdown
    3. Optionally add a Card Processing Fee as a percentage or a flat rate
    4. If you selected a Split Payment policy, use the Balance Collected boxes to set when the final balance will be taken for each type of accommodation.
    5. Click Save
    6. Select Kashing from the dropdown box(es) under Assign Payment Methods

      HTML5 Icon

    Update your T&Cs:

    1. Go to eCommerce > T&Cs
    2. Ensure that your terms and conditions accurately describe your payment policy.

    Apply my discount voucher code?

    If you have received a voucher code and want to apply it please follow the following steps to activate your voucher:

    1. Click Discounts at the top right
    2. Enter the voucher code
    3. Click Apply


    HTML5 Icon

    Change or cancel a future payment?

    If you have selected a Split Payments policy, a deposit is taken at the time of booking and the balance payment is scheduled for the date you set in Guestlink (see How do I Activate E-Commerce?). You may wish to cancel this future payment if a guest prefers to pay by another method, or amend it if the guest changes their booking date or the final balance changes (guest stays an extra night, discount rate applied).

    1. Select Transactions from the menu bar
    2. Click on the relevant Id (use the search option if necessary


    HTML5 Icon

    To cancel a future payment:

    1. Click Cancel Future Payment button


    HTML5 Icon

    To edit a future payment:

    1. Click Edit Payment
    2. Edit the date the payment should be made or amount to be charged as required
    3. Click Confirm

    Generate a payment request?

    If a guest is booking over the phone or by email, the most secure way of taking their card details is to use the payment request option. You generate a secure link and email to the guest who then uses it to enter their card details rather than reading them over the phone or writing them in an email.

    Generating a payment request:

    1. Select Payments from the menu bar
    2. Click Generate a Payment Request Link

      HTML5 Icon

    3. Complete the form (note that some fields are mandatory)
    4. Tick Mail the payment link to the customer

      HTML5 Icon

    5. Click Create Payment Request

    Recharge a client?

    The recharge facility allows you to take an additional amount from a customer's card if they take extras such as dinner, parking or attraction tickets during their stay, are a no-show or in the case of loss or damage.

    1. Select Transactions from the menu bar
    2. Click on the relevant Id (use the search option if necessary
    3. Click Recharge
    4. Edit the description of what the payment is for (this appears on the customer's bank statement) if necessary.
    5. Click Confirm

      HTML5 Icon

    6. The transaction will immediately appear at the top of the list. A status of Settling (clock icon) indicates that the payment has been successful.

    Reconcile my money received?

    The Kashing system includes a Statements section that provides detailed information including a full breakdown of each wire transfer to you from Kashing.

    Wire transafers:

    1. Click on Statements in the menu down the left hand side of the screen
    2. Locate a line that refers to a Wire Transfer. The reference number should appear on your bank statement.

      HTML5 Icon

    3. Click on the Transactions column to view details of the Wire Transfer.

    This includes a line for each payment included in the transfer plus additional lines for Kashing Fees and Rewards as applicable (note that Fees and Rewards including vouchers are paid at the end of each month).

    The Kashing system gives you the option to upload a company logo; this is included in printouts/receipts generated by the system.

    1. Click on Organisation from the left hand menu.
    2. Click Browse in the Company Logo box.

      HTML5 Icon

    3. Locate the image on your computer that you would like to use for your profile picture (.jpg or.png) and click Open; the name of the chosen file appears in the Company Logo box.
    4. Click the Update button; your chosen picture appears alongside the words Organisation Profile.

      HTML5 Icon

    Change my profile picture?

    The Kashing system gives you the option to upload a profile picture; this is shown in the top right hand corner of the screen when you log in.

    1. Click on your name/organisation name near the top right hand corner of the screen to go to the User Profile screen.

      HTML5 Icon

    2. Click Browse in the Profile Picture box.
    3. Locate the image on your computer that you would like to use for your profile picture (.jpg or.png) and click Open; the name of the chosen file appears in the Profile Picture box.
    4. Click the Save button; your chosen picture appears alongside your name in the top corner of the screen

    Close my account

    Should you wish to no longer use our service and you want to protect your data from un-authorised access you can and should close your account. By closing your account we will remove all authorisation and access to your detail. Please export or download all the information you might need before closing your account as this will no longer be avaiable to you once you have successfully closed your account.

    1. Select Organisation from the menu bar

      HTML5 Icon

    2. Click the Close Account button
    3. Click OK to the warning message that appears.

    API Getting Started

    Account Information

    In order to use our API you must first request an account. This can be done by contacting Kashing by email on support@Kashing.co.uk or going to our website at Sign Up to request an account.

    For development and testing you must use our website Sign Up to request an account.

    Once your account has been activated you will find the following information:

    Information Required
    API Address Yes
    Organisation ID Yes
    Key Yes

    Simple Payment Request Concept

    The concept behind the Kashing! API is that every charge request that is made to Kashing! is done in 2 steps. This is called SPR, (Simple Payment Request). SPR enables the merchant application to initialise a transaction, exchange this information for a token and complete the transaction when and where they wish.

    Some example cases:

    Technology Requirements

    Kashing! as a payment solution is agnostic from the type of technology you wish to use. We have developed our platform to support all current and future systems as long as it meets the below minimum conditions you will be able to wnable the technology to facilitate payments.

    Test Information

    Information Data
    Card Number 4929421234600821
    CVV/CVC 123
    Expiry Date 12/17
    Currency GBP
    API Development Server Address https://staging-backend.kashing.co.uk
    Development Panel Server Address https://staging.kashing.co.uk

    Production Information

    Information Data
    API Server Address https://api.kashing.co.uk
    Panel Server Address https://frontend.kashing.co.uk

    Magic Cards

    All card information is directly submitted to Kashing! servers. Any information submitted will be stored so please be carefull not to submit sensitive information during your testing process. Please use the below listed magic card numbers instead of actual data.

    Card Error
    4929421234600821 Success
    5399393495256833 Declined
    5487882196944815 General Bank Error

    API Response Codes

    Nearly every request that is made to the gateway API will have a Response which will contain a Response and Reason code. Listed below are the possible Response and Reason codes, all other codes not represented in this document are to be treated as errors.

    Responce Codes

    Code Detail
    1 Approved
    2 Declined
    3 Error
    4 Redirect
    5 Cancelled
    6 Pending
    10 Card Storage Only
    501 Authentication Failure Throttling

    Reason Codes

    Code Detail
    1 Approved and Success
    2 Declined
    3 Refunded
    4 Redirect
    5 Cancelled
    6 Pending Approval
    7 Database Error
    8 Card Holder Cancelled
    9 Unknown Merchant
    100 Connection Not Secure
    101 Invalid HTTP Method
    102 Field Missing
    103 Field Invalid
    104 Authentication Failed
    105 General Error
    107 Anti Fraud
    108 Bank Redirect
    109 Transaction Not Found
    110 Transaction Is Invalid
    111 MID Is Invalid
    112 Request Duplication
    113 Service error
    140 Refund Not Supported
    160 Recurrent Not Supported

    Protocol Signing & Structure

    Every request that is sent to the gateway requires some form of authentication, the most common of the authentication methods is the use of protocol signing, this will be referred to as the "pSign" from now on. This is a method whereby we use a one way hash of your secret key + the data which you have sent. This creates a very strong value for determining if you are the person who is supposed to be sending the request.

    To create the pSign for the packet, you will need to create a string of all the parameters in the order of which they are sent, salt this string with the secret key found for the merchant and then do a SHA1 hash of this string.

    "{"merchantid": "1", "refundamount": "5","description": "Test \"transaction\"", "transactionID": "1320145192f1e87157dc248541cd"}"

    For the above bodies, the secret key is test, so the constructed string before hashing will look like this

    String: test15Test \"transaction\"1320145192f1e87157dc248541cd

    psign: 154f150b460bdf95a2784aab001ccdc0537aa7c1

    We finally append our pSign to the request to end up with:

    "{"MerchantID": "1", "refundAmount": "5","OrderDescription": "Test \"transaction\"", "transactionID": "1320145192f1e87157dc248541cd", "psign": "154f150b460bdf95a2784aab001ccdc0537aa7c1"}"

    A typical response for this packet would be:

    Success Response:

    {"responseCode": 1, "reasonCode": 1}

    Error Response:

    {"responseCode": 3, "reasonCode": 104}

    Transaction Processing

    The first step is Initialise the transaction. This method is used to fill non sensitive information about the transaction and customer into the Kashing! system, which will then create a transaction token for you. In order to be able to submit the sensitive card information you will need to reference the token. While testing ensure that you don't submit active PAN numbers, please contact Kashing! for test PAN numbers.

    Parameters

    Parameter Format Required
    merchantid Integer Ex. (123) Yes
    amount Float or cent (100 = 1.00) Yes
    currency ISO 4217 Yes
    returnurl ISO 4217 Yes
    ip RFC 1069 Ex. (xxx.xxx.xxx.xxx) Yes
    forwardedip RFC 1069 Ex. (xxx.xxx.xxx.xxx) No
    merchanturl Valid URL Yes
    description Order description Yes
    useragent Browser User Agent No
    language ISO 639-1 No
    email Valid Email No
    phone Valid Phone number No
    firstname As appears on card Yes
    lastname As appears on card Yes
    address1 Card holder Yes
    address2 Card holder No
    city Card holder Yes
    postcode Card holder Yes
    country ISO 3166-1 Yes
    uid Device id String upto 255 No
    processtype 1 = e-commerce, 2 = MOTO, 3 = e-wallet, 4 = chip & pin No
    psign SHA-1 Hash Yes

    Type: POST

    Path: /transaction/init

    Body: {"transactions":[{"merchantid":"35","amount":"10.00","currency":"GBP","returnurl": "https://staging.kashing.co.uk/thanks","ip":"192.168.0.111","forwardedip":"80.177.11.240","merchanturl": "shop.test.co.uk","description":"1 x Test order from","language":"en","email":"test@test.net","phone":"07770000000","firstname": "Rüdiger","lastname":"Green","address1":"Flat 6 Primrose Rise","address2":"347 Lavender Road","city":"Northampton","postcode":"NN17 8YG","country":"UK","datetocomplete":"2016-08-30","uid":"O-99999","processtype": 1,"psign":"6563dd46766b4f443098ff26604cb5fcd263520d"}]}

    Common Responses

    Here are some common responses that you will receive from the API. You will get the results in a JSON Array and outside of this array, there will be general information which relates to the request.

    Success:

    {"results":[{"responsecode":4,"reasoncode":1,"uid":"O-99999","merchantid":"35","token":"cEDezTx96Rx","amount":1000,"currency":"GBP", "redirect":"https://staging-backend.kashing.co.uk/transaction/serve?ID=cEDezTx96Rx"}],"redirect":"https://staging-backend.kashing.co.uk/transaction/serve?ID=cEDezTx96Rx","responsecode":1,"error":"success"}

    Error:

    {"results":[{"responsecode":3,"reasoncode":104,"uid":"O-99999","merchantid":"35","token":"cEDezTx96Rx","amount":1000,"currency":"GBP", "redirect":"https://staging-backend.kashing.co.uk/transaction/serve?ID=cEDezTx96Rx"}],"redirect":"https://staging-backend.kashing.co.uk/transaction/serve?ID=cEDezTx96Rx","responsecode":1,"error":"success"}

    Common Responses Breakdown

    Field Type
    responsecode What kind of response is this
    reasoncode The reason for this response
    token The Temp ID created for this transaction
    amount How much is to be charged
    redirect Where to redirect your customer. For hosted payment
    results Array for results

    Hosted Payment - Return

    If you have decided to use Kashings' hosted payment page then once the user has filled in their information and it has been processed, they will be returned to a landing page of your choice, there are a few possible scenarios that the transaction can end in.

    1. Successful transaction The customer is served a thank you before being redirected back to the merchant landing page. E.g. https://www.merchant.com/return?UID=Trans1+Trans2&TransactionID=68g6fg86dsfg78478gfw+78bw8s7rbg78rwbs&ResponseCode=1+1&ReasonCode=1+1
    2. Failure The customer's transaction fails, they are served an error message and this error code is sent back to the merchant. E.g. https://www.merchant.com/return?UID=Trans1+Trans2&TransactionID=68g6fg86dsfg78478gfw+78bw8s7rbg78rwbs&ResponseCode=3+1&ReasonCode=5+1
    3. Cancel The customer chose to cancel the transaction

    After the card holder has been redirected to the above link, you are provided the UID, TransactionID, ResponseCode and ReasonCode. Using the parameters given you can display the appropriate error page and set the transaction ID & Error codes appropriately in your own Data-Base. Please use the "retrieve" transaction API to confirm the status of the transaction.

    Parse the values in the order they are given, Using the above transaction return URL there are 2 transaction responses they should be parsed to give the following data:

    UID: Trans1 , TransactionID: 68g6fg86dsfg78478gfw , ResponseCode: 1 , ReasonCode: 1

    Charge Transaction

    If you choose not to use the hosted payment solution, you can charge the card using the token. This allows the merchant to generate their own payment page or manually submit card information.

    Type: POST

    Path: /transaction/charge

    Body: {"cardnumber":"4761739001010010","cvv":"123","expiry":"12/17","token":"Lst43AHPOrX"}

    Parameter Format Required
    cardnumber Card number to charge Yes
    cvc/cvv Security code of card Yes
    expiry Returned from original transaction Yes
    token Token received from initialised request Yes

    Common Responses

    Success:

    {"responseCode": 1, "reasonCode": 1}

    Error:

    {"responseCode": 3, "reasonCode": 102}

    Not supported:

    {"responseCode": 3, "reasonCode": 140}

    Charge Response Breakdown

    Field Type
    status What kind of response is this
    redirect The reason for this response
    transactionid The transaction id assocaited

    Get Transaction

    In this method, using the final transactionid you received when submitting a transaction, you can retrieve the transaction information.

    Type: POST

    Path: /json/transaction/find

    Body: {"merchantid": "3", "uid": "Trans1", "transactionid": "156b4b77ae2334c4596fdf15a31d4","psign": "dbd3c664821e8f1c9a49b237d601756a44b1a415"}

    Parameter Format Required
    merchantid Integer Ex. (123) Yes
    uid Found on the original transaction Yes
    transactionid Returned from original transaction Yes
    psign SHA-1 Hash Yes

    Common Responses

    Success: {"merhcantid": "3", "amount": 167, "uid": "Trans 2", "currency": "GBP", "datetime": "2014-09-19 17:03:05 UTC+0100", "transactionid": "156b4b77ae2334c4596fdf15a31d4", "ip": "81.13.114.123", "forwardedip": "86.13.114.123", "useragent": "Mozilla Firefox", "language": "en-us", "email": "email@customer.com", "phone": "+447563829279", "firstname": "Barry", "lastname": "Green", "fullname": "Barry Green", "address1": "56", "address2": "The Street", "city": "London", "postcode": "SW19RD", "country": "GB", "description": "AAA X 4", "merchanturl": "http://myshop.com", "refunded": 0, "responsecode": 0, "reasonCode": 1}

    Error: {"responsecode": 3, "reasoncode": 102}

    Get Transaction Breakdown

    Field Type
    responseCode What kind of response is this
    reasonCode The reason for this response

    Common Responses

    Invalid pSign: {"responseCode": 3, "reasonCode": 104, "transaction": {}}

    Invalid Params: {"responseCode": 3, "reasonCode": 102, "transaction": {}}

    Recharge Transaction

    If you wish to recharge a transaction you can send a request using a previous transaction processed to recharge. This feature is subject to service permissions. If you have any question or queries please contact our support team.

    Type: POST

    Path: /transaction/recharge

    Body: {"merchantid": "3", "transactionid": "156b4b77ae2334c4596fdf15a31d4","description": "some recurrent transaction", amount: "99.99", "psign": "dbd3c664821e8f1c9a49b237d601756a44b1a415"}

    Parameter Format Required
    merchantid Integer Ex. (123) Yes
    transactionid Returned from original transaction Yes
    description Description of transaction Yes
    amount The amount you wish to charge ex. 99.99 Yes
    psign SHA-1 Hash Yes

    Common Responses

    Invalid psign: {"responsecode": 3, "reasoncode": 104, "transaction": {}}

    Invalid Params: {"responsecode": 3, "reasoncode": 102, "transaction": {}}

    Success: {"responsecode": 1, "reasoncode": 1, "transaction": {"transactionid": "d179af810a8b96ed43642126d1eb929ca1a4a250", "amount": 167, "currency": "GBP"}}

    Refund Transaction

    If you wish to refund a transaction you can send a request using the previous trasnaction ID to refund specifying the amount to refund. Using the ID taken from a successful transaction, you can request a refund for this transaction using the below API call.

    Type: POST

    Path: /transaction/refund

    Body: {"merchantid": "3", "refundamount": "1.97", "transactionid": "156b4b77ae2334c4596fdf15a31d4","psign": "dbd3c664821e8f1c9a49b237d601756a44b1a415"}

    Parameter Format Required
    merchantid Integer Ex. (123) Yes
    transactionid Returned from original transaction Yes
    refundAmount The amount to be refunded ex. 1.97 Yes
    psign SHA-1 Hash Yes

    Common Responses

    Invalid psign: {"responsecode": 3, "reasoncode": 104, "transaction": {}}

    Invalid Params: {"responsecode": 3, "reasoncode": 102, "transaction": {}}

    Success: {"responseCode": 1, "reasonCode": 1}

    Error: {"responseCode": 3, "reasonCode": 102}

    Not supported: {"responseCode": 3, "reasonCode": 140}

    Find Transaction

    In this method, using the final transactionid you received when submitting a transaction, you can retrieve the transaction information. This can include card information if you selected to use the “savecard” param in the original transaction. If you did not use this or set this parameter to 0 you will receive redacted information.

    Type: POST

    Path: /transaction/find

    Body: {"merchantid": "3", "uid": "Trans1", "transactionid": "156b4b77ae2334c4596fdf15a31d4","returncard": 1, "psign": "dbd3c664821e8f1c9a49b237d601756a44b1a415"}

    Parameter Format Required
    merchantid Integer Ex. (123) Yes
    transactionid Returned from original transaction Yes
    uid String upto 255 No
    returncard Bool Ex. (0 or 1) Yes
    psign SHA-1 Hash Yes

    Common Responses

    Success: {"merchantid": "3", "amount": "1.67", "uid": "Trans 2", "currency": "GBP", "datetime": "2014-09-19 17:03:05 UTC+0100", "transactionid": "156b4b77ae2334c4596fdf15a31d4", "customerip": "81.13.114.123", "customerforwardedip": "86.13.114.123", "customeruseragent": "Mozilla Firefox", "customeracceptlanguage": "en-us", "customeremail": "support@customer.com", "customerphone": "+447563829279", "customerfirstname": "Barry", "customerlastname": "Green", "customerfullname": "Barry Green", "customeraddress1": "56", "customeraddress2": "The Street", "customercity": "London", "customerzipcode": "SW19RD", "customerstateprovince": "", "customercountry": "GB", "cardbin": "541333", "cardissuer": "MASTERCARD", "cardnumber": "5413330000000027", "cardexpiry": "01/15", "orderdescription": "AAA X 4", "merchanturl": "http://myshop.com", "reoccurring": 0, "refunded": 0, "responsecode": 0, "reasoncode": 1}

    Error: {"responseCode": 3, "reasonCode": 102}

    Re-tokenise

    This method can be used to request a new token based on the current transactionid.

    Type: POST

    Path: /transaction/retoken

    Body: {"merchantid": "3", transactionid": "156b4b77ae2334c4596fdf15a31d4", "psign": "dbd3c664821e8f1c9a49b237d601756a44b1a415"}

    Parameter Format Required
    merchantid Integer Ex. (123) Yes
    transactionid Returned from original transaction Yes
    psign SHA-1 Hash Yes

    Common Responses

    Success: `{"merchantid": "3", "transactionid": "156b4b77ae2334c4596fdf15a31d4", "responsecode": 0, "reasoncode": 1}

    Invalid pSign: {"responseCode": 3, "reasonCode": 104, "transaction": {}}

    Invalid Params: {"responseCode": 3, "reasonCode": 102, "transaction": {}}

    Devices API Getting Started

    Introduction

    This method is a way of accepting card information from Point of Sale systems, Mail Order / Telephone Order sources or other applications to eliminate the PCI Burden on traditional computer systems. It requires the Kashing Mobile SDK or a tablet with a Kashing chip & pin device and mobile application.

    Error Codes

    Every request that is made to the API will respond with some error codes. All other error codes not listed here are to be treated as errors.

    Code Detail
    0 No Error
    1 General Error
    2 Declined
    3 Authentication Failed
    5 Cancelled
    7 Device Paired
    8 Failed to Pair Device

    Action Codes

    Any request that requires Kashing devices to assume control of the browser must specify what "Action" was taken on the browser upon returning to the merchants third party system.

    Code Detail
    1 Merchant Authentication
    2 Merchant Pairing
    3 Transaction

    Merchant Pairing & Authentication URL Generation

    In order for the gateway API to be aware of the attched device a pairing process needs to be performed. This can be a dynamic or static process. Kashing provides a pairing facility through the online web service to administer devices and a method of assigning devices generic or friendly names. It is therefore not mandatory to impliment the device management facility within your application. Trasnactions may simply specify the device id in order to activate trasnactions to a specific attached device.

    To pair the tablet or mobile phone application you have been provided with your merchants organisation account, you will need to generate a URL. This URL serves two purposes; the first is to authenticate and to initialise the browser or crm system. The second is to allow you to enter a code into your browser or crm system that will pair your merchant account with your device. A cookie is stored on your merchant browser or crm system to identify & authenticate you in future requests.

    Example Usage:

    Type: POST

    Path: /TwoFactor/Init

    Body: {"Type": "1","ID":"31", "Return": "crm.test.co.uk", "Name": "Store 1", "CID": "Till 1", "pSign": "6563dd46766b4f443098ff26604cb5fcd263520d"}

    A typical URL your CRM system will need to generate, will look like this:

    https://tf.kashing.co.uk/TwoFactor/Init?Type=1&ID=3&CID=23&Return=https://tf.kashing.co.uk/TwoFactor/Merchant/Init/Page&Name=Tom%20Smith&pSign=a194dd56506c564edc4aeae4c117f924907b0c4f

    Here is a breakdown of each argument:

    Field Type
    Type Type of Initialisation:
    1 = Device Pairing
    3 = Merchant Authentication
    ID The ID of your merchant account held by us.
    Return The return URL, this will typically be your CRM system.
    Name Nickname for the person using the browser.
    CID Custom Identifier your CRM can provide allowing you to have custom information sent back to you upon returning control of the browser to your CRM system.
    pSign Verification signature.

    Return:

    After completing the authentication and pairing process the merchant will be returned to your returnurl provided in the first request.

    Submitting A Transaction

    The submission process is non sensitive. It doesn require any authentication or protocol signature. Once your device is configured and the return RUL specified, you will need to setup some method of posting non-sensitive information from your thrid party application to Kashing devices. All that is required is the corresponding device UID to initiate the transaction. The easiest method to do this is using a HTML form.

    Example Usage:

    Type: POST

    Body: html form example

    Param Data
    Amount Amount you wish to charge.
    Currency Currency that will be used.
    Description Description of the transaction.
    FirstName Card holder first name.
    LastName Card holder last name.
    Address1 Address line 1
    Address2 Address line 2
    City City of card holder.
    PostCode Post code of card holder.
    Country Country of card holder.
    Email Email of card holder.
    Phone Phone number of card holder.
    UID Unique ID for the tablet you wish to process this transaction. Otherwise 0.
    REQ_PAYER_REF ID of payer set by your CRM.
    ORDERID ID of the initial recurring transaction set by your CRM.
    payrefid ID of payer set by your CRM.
    storageid ID of the card stored with the payer.
    CUSTID Customer ID sent by your CRM.
    CARD_COMMENT String set by CRM system.
    TOKEN_TYPE String set by CRM system.
    HAS_SUSPENDED String set by CRM system.
    BSB_DSP String set by CRM system.
    mid ID Assigned to MID you wish the card information be processed through. This will be provided by Kashing.
    PRODID Product ID or Loan ID.

    Return

    To communicate with your CRM system we request a return URL is provided (Return), this enables Kashing to send you error information and to redirect control back to the merchant who is using the system. After a transaction has been initialised using the provided form template, the browser is put into a state of suspension, waiting until the transaction is processed or cancelled by the device. After the transaction has been completed, the browser for the merchant is returned to your ReturnURL provided in the initial authentication step.

    Response: Here are examples of a typical response you are likely to encounter using the device system.

    Param Data
    TransactionID Transaction ID returned by the payment gateway processing this payment.
    ID Merchant ID.
    Error Error Code.
    Action The type of action completed.
    CID Custom ID set by the calling CRM system.
    UID ID of the device who processed this transaction
    orderid ID of the initial reucrring transaction set by your CRM
    payrefid ID of payer set by your CRM.
    storageid ID of the card stored with the payer.
    customerid Customer ID sent by your CRM.
    productid Product ID or Loan ID.

    Managing Devices

    Devices can be configured using Kashing's administration interface. In order to get the status of known devices associated the API can be interrogated to determine their status or in order to generate a trasnaction request using the device ID. There will be certain scenarios where your CRM system will need access to the devices paired with your merchant account and administrate them.

    Device Retrieval

    Retrieve a list of the devices paired with your merchant. This will return an array, which contains your tablets in an array for each tablet group.

    Example Usage:

    Type: POST

    Path: /TwoFactor/Device/Get

    Body: {"MerchantID": "35", "pSign": "809f7f8bc2392bed2079e39c70e68172e7f72cda"}

    Param Data
    MerchantID Organisation ID.
    pSign Protocol Sign.

    A typical response for this packet would be:

    Waiting Response:

    {"Device":[{"Name":"Test Device","UID":38848195,"ID":35,"Status":"Waiting","Time":"2015-03- 04 14:37:20 UTC+0000"},{"Name":"Test Device","UID":40056179,"ID":35,"Status":"","Time":""},{"Name":"Test Device","UID":31719388,"ID":35,"Status":"Waiting","Time":"2015-04-02 16:38:48 UTC+0100"}]}

    Param Data
    Name Generic Device Name.
    UID Unique Device ID.
    ID Organisation ID.
    Status Device status.
    Time Latest heartbeat data from device.

    Device Reset

    In order to cancel or reset a transaction request sent to a device you can issue a device reset instruction.

    Example Usage:

    Type: POST

    Path: /TwoFactor/Device/Reset

    Body: {"MerchantID": "35", "UID": "555123","pSign": "809f7f8bc2392bed2079e39c70e68172e7f72cda"}

    Param Data
    MerchantID Organisation ID.
    UID UID of device you wish to modify.
    pSign Protocol Sign.

    A typical response for this packet would be:

    Error Response: Success: {"Error":0}