# Payment Link API

### 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`

{% hint style="info" %}
Before you begin!
{% endhint %}

## Integration steps

## Generate a Bearer Token

Obtain a token by following the authentication guide [here](https://developers.klasha.com/~/revisions/Tw5bfW3awcozGbmqzgEE/overview/authentication). Use this token as your Bearer token in subsequent API calls.

## Create a Payment Link

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">`{{env_url}}/merchant/api/v1/paylink/create`</mark>

This api generates a payment link that can be given to your customers to make payments.

**NB**: No need for an encryption of the plain json payload.

#### Headers

| Name          | Value                                                        |
| ------------- | ------------------------------------------------------------ |
| Authorization | Bearer <mark style="color:$primary;">{{token}}</mark>        |
| x-auth-token  | <mark style="color:$primary;">{{MERCHANT PUBLIC KEY}}</mark> |

#### Request Body

| Name                                            | Type    | Description                                                |
| ----------------------------------------------- | ------- | ---------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>          | String  | Sub-Merchant Name                                          |
| subMerchantId<mark style="color:red;">\*</mark> | String  | Sub-Merchant Identification                                |
| description<mark style="color:red;">\*</mark>   | String  | Intending product or service.                              |
| currency<mark style="color:red;">\*</mark>      | String  | NGN                                                        |
| amount<mark style="color:red;">\*</mark>        | Decimal | <p>Amount to accept for the </p><p>product or service.</p> |

See an example of the plain json payload to send.

{% tabs fullWidth="true" %}
{% tab title="Sample Request" %}

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

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "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"
    }
}
```

{% endtab %}
{% endtabs %}

## 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 page below).

<figure><img src="https://257545343-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNw4nU37LIEg41plxXG5u%2Fuploads%2F73pjRFgs0yqyM1B5kJM1%2Ffor%20payment%20link%20API.png?alt=media&#x26;token=9b77fd5c-bc1e-4d53-a466-2f9b97e91fd8" alt="" width="563"><figcaption><p>Paylink page for the customer to fill and click Pay with klasha button to proceed.</p></figcaption></figure>

## Monitor Payment Status

We would send payment status updates to your configured webhook URL. Monitor this to track payment outcomes. See webhook details [here](https://developers.klasha.com/~/revisions/ZnKl9fQgoz2UyPgPcwp6/misc/webhook).

## Fetch payment link transactions

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">`{{env_url}}/nucleus/paymentLinkTransaction/id/{{paylinkId}}`</mark>

This api fetches all transactions associated to the `paylinkId` generated above.

#### Headers

| Name                                            | Value                                                     |
| ----------------------------------------------- | --------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | Bearer <mark style="color:red;">`{{token}}`</mark>        |
| x-auth-token<mark style="color:red;">\*</mark>  | <mark style="color:red;">`{{MERCHANT PUBLIC KEY}}`</mark> |

#### Params

| Name                                        | Type   | Description                                  |
| ------------------------------------------- | ------ | -------------------------------------------- |
| paylinkId<mark style="color:red;">\*</mark> | String | paylink id generated while creating the link |

#### Response

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "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": "test@example.com"
        },
        {
            "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": "payment not authorised",
            "tnxRef": "paylink-bf1e85d5-f6e4-475f-b466-87693311a8c7",
            "gateRef": "",
            "paymentType": "BANK_TRANSFER",
            "customerEmail": "fooboo@test.com"
        }
    ]
}
```

{% endtab %}
{% endtabs %}