Payment Link API

Collect payments from your customers using payment link.

Summary

The Payment Link API allows merchants to generate payment links for their sub-merchants to easily collect payments. Follow these steps to integrate:

1. Generate a Bearer Token

2. Create a Payment Link

3. Share the Payment Link

4. Monitor Payment Status

5. Fetch payment link transactions via paylinkId

Before you begin!

• Link to the postman collection.

• Find your keys on the Klasha Dashboard → Settings → Generate API Keys (here)

Integration steps

Generate a Bearer Token

Obtain a token by sending a POST request to the Token endpoint. Use this token for authentication in subsequent API calls.

POST {{env_url}}/auth/account/v2/login

Request Body

Name	Type	Description
username*	username
password*	password

200: OK

{
    "message": "success",
    "error": null,
    "data": {
        "token": "This is your token"
    }
}

Create a Payment Link

Make a POST request to the Payment Link API, including necessary headers like Authorization (Bearer token) and x-auth-token (Merchant public key). The request body should contain details such as sub-merchant ID, description, currency, and amount.

POST {{env_url}}/merchant/api/v1/paylink/create

Make a POST call to the Payment link to generate a payment link. See an example of the plain json payload to send.

No need for an encryption of the plain json payload.

You’d need to pass, as header the x-auth-token. This can be obtained from your merchant dashboard → Settings → Generate API keys → Merchant public key.

Headers

Name	Value
Authorization	Bearer {{token}}
x-auth-token	{{MERCHANT PUBLIC KEY}}

Request Body

Name	Type	Description
name*	String	Sub-Merchant Name
subMerchantId*	String	Sub-Merchant Identification
description*	String	Intending product or service.
currency*	String	NGN
amount*	Decimal	Amount to accept for the product or service.

Sample Request

{
    "name": "Klash",
    "subMerchantId": "sub-klasha-23456",
    "description": "Payment for 1000 naira purchase",
    "currency": "NGN",
    "amount": 1000
}

200: OK

{
    "message": "success",
    "error": null,
    "data": {
        "paylinkId": "b8d0aab0-5974-45a6-ae4a-8b6d519b4da2",
        "paylinkUrl": "https://dev.d2qotb20wbiarg.amplifyapp.com/?token=b8d0aab0-5974-45a6-ae4a-8b6d519b4da2",
        "businessId": "111"
    }
}

Share the Payment Link

Distribute the generated payment link URL to your sub-merchants for them to receive payments. The link directs customers to a payment page.

See sample of the paylinkUrl page below.

Paylink page for the customer to fill and click Pay with klasha button to proceed.

Monitor Payment Status

Klasha sends payment status updates to your configured webhook URL. Monitor this to track payment outcomes.

200: OK (Webhook)

{
    "data": {
        "createdAt": "2024-08-21T12:03:46.728",
        "subMerchantId": "sub-merchant_12",
        "paylinkId": "8406d382-8443-4c65-aaf2-6dc3721c85b4",
        "narration": "Business wallet popup payment",
        "destinationCurrency": "NGN",
        "sourceAmount": 1500.00,
        "sourceCurrency": "NGN",
        "tnxRef": "paylink-f66b115c-4733-4b2c-88f9-085517c1dba7",
        "status": "successful",
        "destinationAmount": 1500.0,
        "customer": {
            "id": 13,
            "name": "Steph Oj",
            "email": "[email protected]",
            "phone": null,
            "createdAt": "2021-07-20T10:28:43.820",
            "updatedAt": "2021-07-20T10:28:43.820"
        }
    },
    "event": "charge.completed"
}

Fetch payment link transactions via paylinkId

Make a GET request to fetch payment link transactions via paylinkId, including necessary headers like Authorization (Bearer token) and x-auth-token (Merchant public key).

GET {{env_url}}/nucleus/paymentLinkTransaction/id/{{paylinkId}}

You’d need to pass, as header the x-auth-token. This can be obtained from your merchant dashboard → Settings → Generate API keys → Merchant public key.

Headers

Name	Value
Authorization	Bearer {{token}}
x-auth-token	{{MERCHANT PUBLIC KEY}}

Response Body

200: OK

{
    "message": "success",
    "error": null,
    "data": [
        {
            "id": 155,
            "amount": 305.00,
            "currency": "KES",
            "sourceAmount": 305.000000,
            "sourceCurrency": "KES",
            "paymentLinkId": "10df0c84-11ec-434c-9020-33d79c0c7a5a",
            "subMerchantId": "89989aa6-7b59-429b-b855-27c289f02fb0",
            "status": "successful",
            "message": "Transaction Successful",
            "tnxRef": "paylink-87858e5b-8eba-4ebe-8cf4-7883f92c5c10",
            "gateRef": "3378988429",
            "paymentType": "MOBILE_MONEY",
            "customerEmail": "[email protected]"
        },
        {
            "id": 154,
            "amount": 1724.03,
            "currency": "NGN",
            "sourceAmount": 305.000000,
            "sourceCurrency": "KES",
            "paymentLinkId": "10df0c84-11ec-434c-9020-33d79c0c7a5a",
            "subMerchantId": "89989aa6-7b59-429b-b855-27c289f02fb0",
            "status": "FAILED",
            "message": "",
            "tnxRef": "paylink-bf1e85d5-f6e4-475f-b466-87693311a8c7",
            "gateRef": "",
            "paymentType": "BANK_TRANSFER",
            "customerEmail": "[email protected]"
        }
    ]
}