Skip to main content
API docs by Redocly

API References (v2)

Download OpenAPI specification:Download

Test

https://api.test.kasha.tech

Production

https://api.kasha.tech

Overview

The Kasha API allow merchants to accept payment from most popular payments methods on different countries around the world.

This API is designed using API REST, and supports three different types of integrations:

  • Hosted Cashier: Our quick-to-integrate approach provides you with a hosted cashier UI. Easy solution for the merchant’s customers to initiate and complete payments using their preferred payment options from different countries.
  • Hybrid payment link: Create a payment session and preselect the options and get a link to the hosted cashier. You will need to use our API to get the payment options and the final checkout is done by the user through the hosted cashier.
  • Direct integration using API only: Use our API and your own UI.

Error Codes

Error Code Status Error Reason Description
1000 DECLINED Validation error. Default validation error.
1001 DECLINED Missing phone number. Customer phone number is missing.
1002 DECLINED Invalid document id. Document id is not accepted by the provider.
1003 DECLINED Invalid document type. Document type is not accepted by the provider.
1004 DECLINED Invalid phone number. Phone number is incorrect.
1005 DECLINED Invalid bank account format. Bank account format is invalid.
1006 DECLINED Invalid zip code. Zip code format is invalid or missing.
1007 DECLINED Low amount received. Payment amount is too low.
1008 DECLINED Payment amount is too high. High amount received.
1009 DECLINED Invalid amount. Invalid payment amount, wrong format perhaps?
1100 ERROR Contact support to confirm payment. Contact Support to confirm payment
3000 DECLINED Insufficient card funds. Card doesn't have enough funds to complete the transaction.
3001 DECLINED Do not honour.
3002 DECLINED Untrusted transaction. Risk decline.
3003 DECLINED Abandoned 3DS.
3004 DECLINED Invalid CVV2/CVC2.
3005 DECLINED Invalid cardholder name. Cardholder name wasn't accepted.
3006 DECLINED Exceeded amount limit.
3007 DECLINED Card expired. An expired card was used.
3008 DECLINED Transaction already in progress. A transactions is already in progress.
3009 DECLINED Invalid card number.
3010 DECLINED Customer has failed 3DS. 3DS was abandoned by customer.
3011 DECLINED No card record.
3012 DECLINED Pickup card.
3013 DECLINED Charge count limit reached for this card.
3014 DECLINED Exceeded amount limit.
3015 DECLINED Transaction not permitted to cardholder.
3016 DECLINED Visa decline. This Transaction was Declined by Scheme (Visa)
3017 DECLINED Duplicate transaction.
3018 DECLINED Payment was not received.
3019 DECLINED Recalculation.
3020 DECLINED Transaction amount less than allowed.
3021 DECLINED Country is blocked.
3022 DECLINED Transaction blocked. Generic blocked transaction.
3023 DECLINED Declined by card Issuer. VSIFC
3024 DECLINED Card type declined. This type of card is blocked.
3025 DECLINED Transaction not allowed in country. Only a local card can be used.
3026 DECLINED Mastercard Decline. This Transaction was Declined by Scheme (MasterCard)
994 DECLINED Unidentified subject. Blacklisted card.
995 DECLINED No payment options were found. No payment options were found for the payment.
996 DECLINED Currency conversion error. Couldnt convert currency.
997 DECLINED No route was found. Couldn't route payment to any provider.
998 DECLINED Adapter timeout. Communication error with our adapter.
999 DECLINED Miscellaneous error. Default error for unmapped errors.

Payin

Get Hosted Cashier link

Initiate a payment session and get a link returned o the Hosted Cashier UI.

The payment session for this link expires after 30 min, only 1 payment is allowed for each session.

Authorizations:
Authorization
Request Body schema: application/json

This endpoint will generate a payment session. The Hosted Cashier will display available payment options based on the given country/currency/amount parameters.

For details about request payload data, please refer to Useful Data section.

country
required
string

Alpha-2 ISO Country code

currency
required
string

ISO Currency code

amount
required
integer

Decimal value allowing max two digits after the decimal point. If the amount is a crypto currency, 8 digits are allowed after the decimal point.

redirectUrl
required
string

Merchant redirect page after payment.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

language
string

Alpha-2 ISO Language code

required
object

Json object with the following details.

merchantReference
string

Merchant reference, must be unique and generated in merchant system.

paymentReference
string

Reference to be used for the Payment.

userId
string

User identifier on the merchant system.

extra1
string

*Use this parameter for indicate the user crypto wallet.

extra2
string

Extra parameter to match payment.

extra3
string

Extra parameter to match payment.

storedToken
string

Stored payment credential.

tax
string

Tax percentage.

object

Shipping address object.

Array of objects

Array with products details.

Responses

Request samples

Content type
application/json
{
  • "country": "BR",
  • "currency": "BRL",
  • "amount": 130,
  • "redirectUrl": "https://merchant.io/where-to-go",
  • "language": "ES",
  • "customer": {
    },
  • "paymentReference": "Invoice ABC123",
  • "userId": "Merch_User_123",
  • "extra1": "extraData001",
  • "extra2": "extraData002",
  • "extra3": "extraData003",
  • "storedToken": "index-stored",
  • "tax": "21%",
  • "shippingAddress": {
    },
  • "orderDetails": [
    ]
}

Response samples

Payout

Get Hosted Cashier link

Initiates a payout session and get a link returned o the Hosted Cashier UI.

The payout session for this link expires after 30 min, only 1 payout is allowed for each session.

Authorizations:
Authorization
Request Body schema: application/json

This endpoint will generate a payout session. The Hosted Cashier will display available payout options based on the given country/currency/amount parameters.

country
required
string

Alpha-2 ISO Country code.

currency
required
string

Alpha-3 ISO Currency code.

amount
required
integer

Decimal value allowing max two digits after the decimal point. If the amount is a crypto currency, 8 digits are allowed after the decimal point.

redirectUrl
required
string

Merchant page to be redirected after the payout.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

required
object

Customer object with end user details, refer to Useful Data section for more information.

userId
string

User id generated by the merchant system.

language
string

Language code ISO alpha 2. Values: ‘EN’, ‘ES’, ‘PT’, ‘IN’..

extra1
string

Optional payload for help merchant to track this payout.

extra2
string

Optional payload for help merchant to track this payout.

extra3
string

Optional payload for help merchant to track this payout.

Responses

Request samples

Content type
application/json
{
  • "country": "BR",
  • "currency": "BRL",
  • "amount": 150,
  • "redirectUrl": "https://merchant1.io/where/to/go",
  • "customer": {
    },
  • "userId": "merchant_user123",
  • "language": "PT",
  • "extra1": "merchant extra value 1",
  • "extra2": "merchant extra value 2",
  • "extra3": "merchant extra value 3"
}

Response samples

Payin

Hybrid Payment

Post the session ID and payment option ID to get a Hosted Cashier link in the response.

When using Hybrid payment the payment options needs to be selected and included in the request. A paymentOptionId for a selected payment method is mandatory to be set in the request. A suboption ID (optionId) is optional and only needed if the payment methods includes more options. Suboptions are not needed for card payment.

Follow these two steps.

  1. Initiate a payment and retrieve payment options(paymentOptionId). See /payment-options.
  2. Get sub-options ID (optionId). See /payment-suboptions. Not needed for Card payment
Authorizations:
Authorization
Request Body schema: application/json

You must previously initiate a session and retreive a correct paymentOptionId to this endpoint.

sessionId
required
string

UUID of the session generated previously.

paymentOptionId
required
string

Payment option string.

optionId
string

Responses

Request samples

Content type
application/json
{
  • "sessionId": "3b21a1e2-e8c2-4e86-8de8-8441ea5c7dba",
  • "paymentOptionId": "f34deaf0-a854-4d12-ae6a-b309c9feb404",
  • "optionId": "e_4435"
}

Response samples

Content type
application/json
{}

Payin

1. Initiate a Payment

Initiate a payment session and retreive all available payment options for given country, currency and amount parameters.

Note: Session expires after 30 min, only 1 payment is allowed for each session.

Authorizations:
Authorization
Request Body schema: application/json

Use this endpoint to initiate a payment session and retreive all the payment options available.

country
required
string = 2 characters

Country code ISO alpha 2.

currency
required
string = 3 characters

Currency code ISO alpha 3.

amount
required
number

Decimal value allowing max two digits after the decimal point. If the amount is a crypto currency, 8 digits are allowed after the decimal point.

redirectUrl
required
string <= 500 characters

Merchant page to be redirected after the payment.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

language
required
string = 3 characters

Language code ISO alpha 2. Values: ‘EN’, ‘ES’, ‘PT’, ‘IN’.

required
object

Customer object with end user details, refer to Useful Data section for more information.

merchantReference
string [ 1 .. 255 ] characters

Merchant reference, must be unique and generated in merchant system.

paymentReference
string [ 1 .. 255 ] characters

Reference to be used for the Payment.

userId
string [ 1 .. 255 ] characters

User id generated by the merchant system.

extra1
string [ 1 .. 255 ] characters

Optional payload for help merchant to track this payment.

extra2
string [ 1 .. 255 ] characters

Optional payload for help merchant to track this payment.

extra3
string [ 1 .. 255 ] characters

Optional payload for help merchant to track this payment.

tax
string [ 1 .. 255 ] characters

Percentage tax, only for informational purporses, it is not applied to end amount.

object

Allow to add a different shipping address, otherwise Customer address object is used. Refer to Useful Data section for more information.

Array of objects

Optional, it allow merchants to indicate productd details, like quantity, dimesions, description etc. Refer to Useful Data section for more information.

Responses

Request samples

Content type
application/json
{
  • "country": "BR",
  • "currency": "BRL",
  • "amount": 130,
  • "redirectUrl": "https://merchant.io/where-to-go",
  • "language": "ES",
  • "customer": {
    },
  • "paymentReference": "Invoice ABC123",
  • "merchantReference": "Merchant Unique Value",
  • "userId": "Merch_User_123",
  • "extra1": "extraData001",
  • "extra2": "extraData002",
  • "extra3": "extraData003",
  • "tax": "21%",
  • "shippingAddress": {
    },
  • "orderDetails": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionId": "af52a9af-6249-4f56-98c3-f0eaf3910eab,",
  • "sessionId": "c3ee84b7-6ef7-4541-a2c7-5881fe86bb30",
  • "paymentOptions": [
    ]
}

2. Get Payment Suboptions

API endpoint to retreive available banks and payments suboptions list.

Note 📌 This endpoint should not be used for card payments.

Authorizations:
Authorization
Request Body schema: application/json

Request must include the header: “Content-Type: multipart/form-data;”

sessionId
required
string

UUID of the session generated previously.

paymentOptionId
required
string

UUID for chosen payment option.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "paymentOptionId": "string"
}

Response samples

Content type
application/json
Example
{
  • "statusCode": "085",
  • "resultType": "option_choice",
  • "result": {
    }
}

3. Post a Payment

Payment API endpoint to complete the session previously generated.

Last endpoint for complete the payment session and connect with the payment processors.

Note: 3D secure authentication for card payment is used through a redirect URL. This redirect will contain an iframes and it it may cause issues if redirected in another iframe

Authorizations:
Authorization
Request Body schema: application/json

You must previously initiate a session and retreive a correct paymentOptionId to this endpoint to get a proper response

sessionId
required
string

UUID of the session generated previously.

paymentOptionId
required
string

Payment option string.

optionId
any or null

Option id chosen by the end user.

object

Set of extra parameters taken from end-user input

Responses

Request samples

Content type
application/json
{
  • "sessionId": "3b21a1e2-e8c2-4e86-8de8-8441ea5c7dba",
  • "paymentOptionId": "f34deaf0-a854-4d12-ae6a-b309c9feb404",
  • "optionId": null,
  • "extraData": {
    }
}

Response samples

Content type
application/json
Example
{
  • "statusCode": "000",
  • "resultType": "success",
  • "result": {
    }
}

Payout

1. Initiate a Payout

Retreive all the payout options allowed for country, currency and amount limits.

This endpoint returns all payout options based on a country. It’s a POST request with a json body specifing country, currency and amount for the payout.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

country
required
string

Country code ISO alpha 2.

currency
required
string

Currency code ISO alpha 3.

amount
required
integer

Decimal value allowing max two digits after the decimal point. If the amount is a crypto currency, 8 digits are allowed after the decimal point.

redirectUrl
required
string

Merchant page to be redirected after the payout.

notificationUrl
string

Merchants notification webhook url. This value will override the notification URL setup in the Merchant Portal.

required
object

Customer object with end user details, refer to Useful Data section for more information.

merchantReference
string

Unique merchant specific reference for this transaction. If not set it will be generated. This reference will be returned in the notification.

merchantDomain
string

Merchant domain. Required for payment facilitators.

Responses

Request samples

Content type
application/json
{
  • "country": "AR",
  • "currency": "ARS",
  • "amount": 200,
  • "redirectUrl": "https://merchant.io/where-to-go",
  • "customer": {
    },
  • "merchantReference": "Unique merchant ref"
}

Response samples

Content type
application/json
[
  • {
    }
]

2. Get Payout Suboptions

Authorizations:
Authorization
Request Body schema: application/json

Use the sessionId and paymnentOptionId from the response of /payment-option

sessionId
required
string

UUID of the session generated previously.

paymentOptionId
required
string

UUID for chosen payment option.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "paymentOptionId": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

3. Create Payout

Endpoint for initiate a payout request.

After the payout is accepted within the merchant system, it must be approved or declined from the merchant-portal or using the endpoint /settle-payout.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

sessionId
string
paymentOptionId
string
optionId
string

Option id returned in the the payout-suboptions endpoint.

extraData
object

Necessary form input data needed to be set for this option

Responses

Request samples

Content type
application/json
{
  • "sessionId": "a6c13aa9-333d-4e07-b173-e37a71bcc7f3",
  • "paymentOptionId": "dfb7a9c4-1e87-4803-9929-091d946999d3",
  • "optionId": "d_316",
  • "extraData": {
    }
}

Response samples

Content type
application/json
{
  • "statusCode": 0,
  • "resultType": "success",
  • "result": {
    }
}

4. Confirm Payout

Accept or reject a payout on using the direct API.

Payout will remain as “PENDING” until it is confirmed by using “action” parameter:

  • APPROVE a payout will submit all details to the payment processor, at this point the payout is processed but it could be rejected by processor.

  • DECLINE will reject the payout directly, and mark it as DECLINED in the system.

By default this is a mandatory step in the payout flow for security reasons. Contact your account manager if this step can be removed.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

action
required
string

Values: APPROVE or DECLINE.

transactionId
required
string

Internal ID

Responses

Request samples

Content type
application/json
{
  • "action": "APPROVE",
  • "transactionId": "f6ab9d53-db1e-4cd9-bafa-a8e31247054d"
}

Response samples

Content type
application/json
{
  • "statusCode": "000",
  • "status": "PROCESSING",
  • "transactionId": "1a48baf9-affe-4fde-9ccb-eafa32b478e2",
  • "merchantReference": "mr-65gkcsf2w23423",
  • "result": "Payout request was submitted successfully."
}

Refunds

Refund by Reference

Refund a previous authorized transaction

This endpoint will refund a previous authorized transaction, after this process the money will return to origin account. This process cannot be undone.

Authorizations:
Authorization
Request Body schema: application/json

The Content-Type header should be set to application/json along with the merchant API key

merchantReference
string

Reference of the transaction submitted by the merchant

Responses

Request samples

Content type
application/json
{
  • "merchantReference": "ac6c9d64-6ddb-449f-8789-4de064a4fa83"
}

Response samples

Content type
application/json
{
  • "statusCode": "000",
  • "errorReason": "Success",
  • "paymentAmount": 1000,
  • "status": "REFUNDED",
  • "currency": "BRL",
  • "country": "BR",
  • "paymentOptionName": "DepositExpress",
  • "userId": "merchantUser123",
  • "type": "All",
  • "_id": "feb6a715-9f7c-49d4-b6f7-10c59d18a194",
  • "createdAt": "02/09/2021 23:02:33",
  • "updatedAt": "02/09/2022 00:00:00"
}

Query Transactions

Get Transaction status

Get transaction details

Return all details about the transaction by a given transaction ID.

Authorizations:
Authorization
path Parameters
transactionId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "099cdc76-45d1-49e1-8985-e1c82dcfadb3",
  • "sessionId": "90545ca3-fe0d-457c-a9da-283ee2561d82",
  • "country": "GB",
  • "currency": "GBP",
  • "paymentAmount": 10,
  • "method": "Bank Transfer",
  • "status": "COMPLETED",
  • "paymentReference": "invoice-4726",
  • "merchantReference": "Merchant Unique Value",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "orderDetails": [
    ],
  • "errors": {
    },
  • "createdAt": "2022-08-04T08:23:50.738Z",
  • "updatedAt": "2022-08-05T08:23:50.738Z"
}