Skip to main content

Direct API Integration

Direct API Integration for card payments​

Integrating to Kasha directly through the API gives you the flexibility to do card payment and refunds using your own user interface. Authentication with 3D secure 2 is supported through an authentication URL where the user needs to be redirected to complete the verification.

To create a card payment there are two endpoints that need to be consumed - /payment-options and /direct-payment. Initial status of the payment request will be returned in the response when the /direct-payment is called. It is however required to setup a webhook to get an asynchronous status notification of the transaction. The URL where these status notifications shall be sent can be set for every single transaction when requesting the /payment-options endpoint, or be configured in the merchant portal.

Read more about webhooks here.

1 Initiate a payment session and get available payment options​

First step is to use the /payment-option endpoint to initiate the payment session. The response will return cards as an available payment option if this option is supported for the given information in the request.

Example request:

/payment-options

{
    "country": "DE",
    "currency": "er",
    "amount": 130,
    "redirectUrl": "https://merchant.io/where-to-go",
    "notificationUrl": "https://merchant.io/where-to-go",
    "language": "ES",
    "customer": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+34666999666",
        "userDevice": "MOBILE",
        "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
        "ip": "84.232.140.77",
        "address": {
            "street": "32 Windsor Gardens",
            "streetNumber": "24",
            "country": "GB",
            "zipCode": "W9 3RG",
            "city": "London",
            "state": "Great London."
        },
        "identify": {
            "number": "36570630563",
            "type": "BRA_CPF"
        }
    }
}

Example response:

{
    "transactionId": "9ba7acd4-302d-447a-86e4-f96f7a527a8f",
    "sessionId": "49ce8a52-94c6-4be0-be9d-465f68f6b400",
    "paymentOptions": [
        {
            "paymentOptionId": "4864ab16-2fa4-464a-b692-a74cab45aaf8",
            "name": "Card",
            "logo": "https://kasha-test.s3.eu-west-1.amazonaws.com/payment-options/4864ab16-2fa4-464a-b692-a74cab45aaf8/card-1664786551844-400px.png",
            "extraData": [
                {
                    "label": "Card Number",
                    "name": "cardnum",
                    "type": "string",
                    "values": [],
                    "required": true
                },
                {
                    "label": "Owner",
                    "name": "cardholder",
                    "type": "string",
                    "values": [],
                    "required": true
                },
                {
                    "label": "Expiration Year",
                    "name": "expiryyear",
                    "type": "string",
                    "values": [],
                    "required": true
                },
                {
                    "label": "Expiration Month",
                    "name": "expirymonth",
                    "type": "string",
                    "values": [],
                    "required": true
                },
                {
                    "label": "CVV",
                    "name": "cardcvv",
                    "type": "string",
                    "values": [],
                    "required": true
                }
            ]
        }
    ]
}

The response will include Card as a payment option with the “extraData” object specifying the data needed for this payment.

Example:

            "extraData": [
                {
                    "label": "Card Number",
                    "name": "cardnum",
                    "type": "string",
                    "values": [],
                   …..

Card number is a mandatory data field, the required name of the field is “cardnum”. This is to be used in the second step when the payment is requested.

2 Request the payment​

Request

/direct-payment

{
    "sessionId": "{{sessionId}}",
    "paymentOptionId": "4864ab16-2fa4-464a-b692-a74cab45aaf8",
    "extraData": {
        "cardnum": "4387751111111111",
        "expiryyear": "2030",
        "expirymonth": "12",
        "cardcvv": "123",
        "cardholder": "Babben lars"
    }
}

The extraData required in this request are returned in the response of /payment-option. For cards that is cardnum, cardholder, expirymonth.

Responses​

Different response types can be returned for card payment. Success, Declined, Error and Redirect.

Note: Status of the transaction will be sent to the configured webhook.

Success

{
    "statusCode": "000",
    "resultType": "success",
    "result": {
        "transactionId": "15be2828-c286-48f0-ae73-7a9f151dc0f2"
        "status":"COMPLETED"
    }
}

Redirect

{
    "statusCode": "300",
    "resultType": "redirect",
    "result": {
        "redirectUrl": "https://sandbox.kasha.tech/3DSecureExample",
        "transactionId": "f5773e8a-697e-4b25-a01d-bd3701091a8f"
    }
}

Declined

{
    "statusCode": "900",
    "resultType": "declined",
    "result": {
    "errors": [
        {
            "code": "3000",
            "message": "Insufficient card funds."
        }
    ],
    "transactionId": "6bbffe09-429f-4929-8a9b-934792099164"
    }
}

Error

{
    "statusCode": "999",
    "resultType": "error",
    "result": {
    "errors": [
        {
            "code": "1100",
            "message": "Contact Support to confirm payment"
        }
    ],
    "transactionId": "6bbffe09-429f-4929-8a9b-934792099164"
    }
}