Exchange Token News Support About
Karsha News

Karsha Vouchers API

2017/11/4 12:54:35AM GMT

We made an easy to use and full featured API to accept Karsha Vouchers as a payment method, or make autonomous operations with Karsha Vouchers on your website. If you are not familiar with Karsha Vouchers yet, please read this article to know more about them.

Also, please read this article to understand Personal Salt and its use and effect on vouchers. In all API calls, sending the Personal Salt is optional. But if you send the correct Personal Salt, the output vouchers would be chained to the original vouchers and the results would include the child(ren) voucher codes too.

 

The base URL for most of the API requests is: https://karsha.biz/voucher/api and all outputs are in JSON format.

 

Get Voucher Information:

You can get information about the voucher by calling this URL:

https://karsha.biz/voucher/api/get/<voucher-code>[/personal-salt]

 

For example, by calling this URL:

https://karsha.biz/voucher/api/get/022d560ab919a078364860e2a4281a87/Xcwerf3564sd

 

You'd get an output like:

{
  "voucher_id":"85",
  "voucher_code":"022d560ab919a078364860e2a4281a87",
  "currency":"USD",
  "amount":"6410.58",
  "date_create":"2017-11-01 05:30:11",
  "date_use":null,
  "parent1_code":"59784747a7b0db0981464ee522d5839c",
  "parent2_code":null,
  "child1_code":null,
  "child2_code":null
}

If the voucher was not found in the database, an empty resonse would get returned.

 

Merge Vouchers:

You can merge two vouchers into a new voucher by calling this URL:

https://karsha.biz/voucher/api/merge/<voucher1-code>/<voucher1-code>[/personal-salt]

 

For example, by calling this URL:

https://karsha.biz/voucher/api/merge/022d560ab919a078364860e2a4281a87/e83678ce538a4502c7bbc4e71240c241/Xcwerf3564sd

 

You’d get an output like:

{
  "result":0,
  "message":"OK.",
  "input":
  [
    {
      "voucher_id":"85",
      "voucher_code":"022d560ab919a078364860e2a4281a87",
      "currency":"USD",
      "amount":"6410.58",
      "date_create":"2017-11-01 05:30:11",
      "date_use":"2017-11-03 23:30:10",
      "parent1_code":"59784747a7b0db0981464ee522d5839c",
      "parent2_code":null,
      "child1_code":null,
      "child2_code":null
    },
    {
      "voucher_id":"69",
      "voucher_code":"e83678ce538a4502c7bbc4e71240c241",
      "currency":"USD",
      "amount":"6415.67",
      "date_create":"2017-11-01 05:16:46",
      "date_use":"2017-11-03 23:30:10",
      "parent1_code":"c8b94b1e06d8b6ec4306bd06ccbea5d6",
      "parent2_code":null,
      "child1_code":null,
      "child2_code":null
    }
  ],
  "output":
  [
    {
      "voucher_id":"108",
      "voucher_code":"73305c3b0b40408a1f559178529b0481",
      "currency":"USD",
      "amount":"12826.2",
      "date_create":"2017-11-03 23:30:10",
      "date_use":null,
      "parent1_code":"022d560ab919a078364860e2a4281a87",
      "parent2_code":"e83678ce538a4502c7bbc4e71240c241",
      "child1_code":null,
      "child2_code":null
    }
  ]
}

 

Split a Voucher:

To split a voucher into two new vouchers, call this URL:

https://karsha.biz/voucher/api/split/<voucher-code>/<amount>[/personal-salt]

 

For example:

https://karsha.biz/voucher/api/split/73305c3b0b40408a1f559178529b0481/1200/Xcwerf3564sd

 

Would return this result:

{
  "result":0,
  "message":"OK.",
  "input":
  [
    {
      "voucher_id":"108",
      "voucher_code":"73305c3b0b40408a1f559178529b0481",
      "currency":"USD",
      "amount":"12826.2",
      "date_create":"2017-11-03 23:30:10",
      "date_use":"2017-11-03 23:35:43",
      "parent1_code":"022d560ab919a078364860e2a4281a87",
      "parent2_code":"e83678ce538a4502c7bbc4e71240c241",
      "child1_code":null,
      "child2_code":null
    }
  ],
  "output":
  [
    {
      "voucher_id":"109",
      "voucher_code":"4ce719e2abd091378746dfd9b3a30f7b",
      "currency":"USD",
      "amount":"1200",
      "date_create":"2017-11-03 23:35:43",
      "date_use":null,
      "parent1_code":"73305c3b0b40408a1f559178529b0481",
      "parent2_code":null,
      "child1_code":null,
      "child2_code":null
    },
    {
      "voucher_id":"110",
      "voucher_code":"a2887d214d0f2872404c62868f3b4199",
      "currency":"USD",
      "amount":"11626.2",
      "date_create":"2017-11-03 23:35:43",
      "date_use":null,
      "parent1_code":"73305c3b0b40408a1f559178529b0481",
      "parent2_code":null,
      "child1_code":null,
      "child2_code":null
    }
  ]
}

 

Spend a Voucher:

This is the most used API function, especially for merchants. This function gets a payee voucher code, a payer voucher code, and a payment amount. It then splits the payer voucher to the payment amount (if its value is greater than the payment amount), then merges the resulted voucher with the payee voucher. Then it returns the resulted voucher (which is owned by the payee), and the remainder voucher (which is owned by the payer and must be given to him).

If only one voucher code is given, it'd be considered as the payer voucher. So, after splitting the payer voucher to the payment amount (if needed), the resulted voucher would be directly sent back instead of merging it with the payee voucher.

The URL format is:

https://karsha.biz/voucher/api/spend[/payee-voucher-code]/<payer-voucher-code>/<amount>[/personal-salt]

 

For example, by calling this URL:

https://karsha.biz/voucher/api/spend/4ce719e2abd091378746dfd9b3a30f7b/a2887d214d0f2872404c62868f3b4199/2500/Xcwerf3564sd

 

The result would be:

{
  "result":0,
  "message":"OK.",
  "input":
  [
    {
      "voucher_id":"109",
      "voucher_code":"4ce719e2abd091378746dfd9b3a30f7b",
      "currency":"USD",
      "amount":"1200",
      "date_create":"2017-11-03 23:35:43",
      "date_use":"2017-11-03 23:42:39",
      "parent1_code":"73305c3b0b40408a1f559178529b0481",
      "parent2_code":null,
      "child1_code":null,
      "child2_code":null
    },
    {
      "voucher_id":"111",
      "voucher_code":"900df61af903b14f6b83d9ce7455b3c7",
      "currency":"USD",
      "amount":"2500",
      "date_create":"2017-11-03 23:42:39",
      "date_use":"2017-11-03 23:42:39",
      "parent1_code":"a2887d214d0f2872404c62868f3b4199",
      "parent2_code":null,
      "child1_code":null,
      "child2_code":null
    }
  ],
  "output":
  [
    {
      "voucher_id":"113",
      "voucher_code":"ef37627a024d7b69662fd9472717e7be",
      "currency":"USD",
      "amount":"3700",
      "date_create":"2017-11-03 23:42:39",
      "date_use":null,
      "parent1_code":"4ce719e2abd091378746dfd9b3a30f7b",
      "parent2_code":"900df61af903b14f6b83d9ce7455b3c7",
      "child1_code":null,
      "child2_code":null
    },
    {
      "voucher_id":"112",
      "voucher_code":"4a6ae97c2314736459c6e0eda2b0d8cc",
      "currency":"USD",
      "amount":"9126.2",
      "date_create":"2017-11-03 23:42:39",
      "date_use":null,
      "parent1_code":"a2887d214d0f2872404c62868f3b4199",
      "parent2_code":null,
      "child1_code":null,
      "child2_code":null
    }
  ]
}

 

Get a Voucher Image:

If you need to show the image of a voucher to a customer, you can call this URL:

https://karsha.biz/voucher/image/<voucher-code>

 

For example calling this URL:

https://karsha.biz/voucher/image/ef37627a024d7b69662fd9472717e7be

 

Would get you this image:

Karsha Voucher Image

If you call https://karsha.biz/voucher/download/<voucher-code> instead,(e.g. https://karsha.biz/voucher/download/ef37627a024d7b69662fd9472717e7be), it’d force the browser to download and save the image instead of showing it in the page.

 

API Errors:

If any of the API calls reach an error, you will get this response instead:

{
  "result":<error_code>,
  "message":"<error_message>"
}

 

The following error codes are hardcoded in the system:

1: Voucher not found.

2: Voucher is already used.

3: Invalid split amount.

4: Split amount is greater than voucher amount.

5: You can't merge a voucher with itself.

6: You can't merge vouchers with different currencies.

7: Voucher amount is insufficient.

 

API Test:

To test the API system without having to worry about mistakenly losing a voucher code, you can use the API Test service. Instead of https://karsha.biz/voucher/api/..., you can call https://karsha.biz/voucher/apitest/.... This way, all of the operations are done in test mode without any modification to the vouchers database. Hypothetical vouchers which are created during operations will have the ID of zero and a random (or if personal salt is given, real-looking) voucher code. All other information are exactly like real API calls.

 

If you need any help implementing Karsha Voucher API into your website, please don't hesitate to contact our Support. We would be happy to help you.

Frequently Asked Questions

Here are the answers to the most frequently asked questions from our support staff. Click on any question to view its answer.



If you have any other question, or if there is any ambiguity, please feel free to contact our Customer Support. We'd be happy to help you, answer your questions, and hear your valuable suggestions.