> ## Documentation Index
> Fetch the complete documentation index at: https://doc.seerbit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Link

> Create shareable payment links your customers can pay from anywhere.

**Ideal for**: Collecting payments without a website or a checkout integration — donations, invoices, social selling, event tickets. You create a link once and share it; anyone who opens it can pay.

## Payment Link or Standard Checkout?

Both send the customer to a SeerBit-hosted page to pay, so the difference is not the payment experience — it is **when the link is created and how many times it can be used**.

| | [Standard Checkout](/online-payments/integrations/standard-checkout) | Payment Link |
| - | - | - |
| **When it is created** | Per transaction, by your server, at the moment the customer is ready to pay | Once, ahead of time — then reused |
| **How many payments** | One. The link is specific to that transaction | Many. Anyone with the link can pay it |
| **Who can pay it** | The customer you created it for | Anyone you share it with |
| **The amount** | Fixed by your server in the request | Fixed, or left for the customer to enter |
| **Customer details** | You supply `email` and `fullName` when creating it | Collected on the payment page via `requiredFields` |
| **You need at payment time** | A server making an API call | Nothing — the link already exists |
| **After payment** | Customer returns to your `callbackUrl` | Customer sees your `successMessage`; no return trip needed |
| **Reconciliation** | One `paymentReference` you generated | Many transactions under one link |
| **Best for** | A cart or checkout your application drives | Invoices, donations, social selling, event tickets |

In short: **Standard Checkout creates a link for one customer, one purchase, at the moment of purchase. A payment link is created once and works for everyone until you turn it off.**

If your application already knows the amount and the customer at the point of payment, use [Standard Checkout](/online-payments/integrations/standard-checkout). If you are sending a request to pay — or selling somewhere you have no checkout at all — use a payment link.

> **Need line items, a due date and a document?** That is an [invoice](/online-payments/payment-features/invoicing), not a payment link — SeerBit emails it to a named customer and gives it an invoice number you can look up. See the [comparison](/online-payments/payment-features/invoicing#invoice-or-payment-link).

## How it works

You create a link through the API (or your dashboard) with a name, a currency and the fields you want to collect. SeerBit returns a `paymentLinkUrl` you can share anywhere. When a customer opens it they see a SeerBit-hosted payment page, pay with any method enabled on your account, and the transaction appears in your dashboard like any other.

Links can be one-time or reusable, can expire on a date, and can let the customer enter the amount themselves — useful for donations.

## Authentication

Payment Link calls are authenticated with a **bearer token**, generated from your public and secret keys.

```bash theme={null}
POST https://seerbitapi.com/api/v2/encrypt/keys
```

<Card title="Authentication" icon="key" href="/authentication#bearer-token">
  How to generate the token, and which credential every other SeerBit API expects.
</Card>

## Create Payment Link

<Badge color="blue">POST</Badge>

```bash theme={null}
https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api
```

#### Request Sample

The code snippet below shows an example request for creating a payment link

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \
  --data-raw '{
    "status":"ACTIVE",
    "paymentLinkName": "Donations",
    "description":"Give out donations",
    "currency": "NGN",
    "successMessage":"Thank you for your payment",
    "publicKey":"YOUR_PUBLIC_KEY",
   "customizationName":"testing1",
    "paymentFrequency":"ONE_TIME",
    "paymentReference": "",
    "email":"js@emaildomain.com",
    "requiredFields": {
        "address":true,
        "amount":true,
        "customerName":true,
        "mobileNumber":true,
        "invoiceNumber":false
    },
    "additionalData":"Customer Email: js@mailinator.com",
    "linkExpirable":false,
    "expiryDate":"",
    "oneTime":false

  }'

  ```

  ```javascript NODE theme={null}
  var request = require('request');
  var options = {
    method: 'POST',
    url: 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer YOUR_ENCRYPTED_KEY',
    },
    body: JSON.stringify({
      status: 'ACTIVE',
      paymentLinkName: 'Donations',
      description: 'Give out donations',
      currency: 'NGN',
      successMessage: 'Thank you for your payment',
      publicKey: 'YOUR_PUBLIC_KEY',
      customizationName: 'testing1',
      paymentFrequency: 'ONE_TIME',
      paymentReference: '',
      email: 'js@emaildomain.com',
      requiredFields: {
        address: true,
        amount: true,
        customerName: true,
        mobileNumber: true,
        invoiceNumber: false,
      },
      additionalData: 'Customer Email: js@mailinator.com',
      linkExpirable: false,
      expiryDate: '',
      oneTime: false,
    }),
  };
  request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
  });
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
    "status":"ACTIVE",
    "paymentLinkName": "Donations",
    "description":"Give out donations",
    "currency": "NGN",
    "successMessage":"Thank you for your payment",
    "publicKey":"YOUR_PUBLIC_KEY",
   "customizationName":"testing1",
    "paymentFrequency":"ONE_TIME",
    "paymentReference": "",
    "email":"js@emaildomain.com",
    "requiredFields": {
        "address":true,
        "amount":true,
        "customerName":false,
        "mobileNumber":true,
        "invoiceNumber":false
    },
    "additionalData":"Customer Email: js@mailinator.com",
    "linkExpirable":false,
    "expiryDate":"",
    "oneTime":false
  }',
    CURLOPT_HTTPHEADER => array(
      'Content-Type: application/json',
      'Authorization: Bearer YOUR_ENCRYPTED_KEY'
    ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
  ```
</CodeGroup>

#### Response Sample

The code snippet below shows an example response for creating a payment link

```json theme={null}
{

    "data": {
        "paymentLinks": {
            "publicKey": "SBPUBK_******************PHI",
            "status": "ACTIVE",
            "additionalData": "custom1:null||custom2:null||custom3:null",
            "paymentLinkName": "Donationas",
            "description": "Donation",
            "successMessage": "Payment made successfully!",
            "paymentLinkId": "000000000",
            "currency": "NGN",
            "paymentReference": "",
            "paymentFrequency": "RECURRENT",
            "paymentLinkUrl": "https://pay.seerbitapi.com/paymentLinkId",
            "customizationName": "utbesti22",
            "environment": "LIVE",
            "requiredFields": {
                "address": true,
                "amount": true,
                "customerName": true,
                "mobileNumber": true,
                "invoiceNumber": false
            },
            "expiryDuration": 0,
            "linkExpirable": false,
            "createdAt": "2021-09-21T10:49:17.728",
            "updatedAt": "2021-09-21T10:49:17.728",
            "oneTime": false,
            "splitPayment": false
        }
    }

}
```

#### Parameter description

| Name | Type | Description | Required |
| - | - | - | - |
| publicKey | `string` | Your SeerBit public key, from **Settings > API Keys**. | Yes |
| paymentLinkName | `string` | The name shown to the customer on the payment page. | Yes |
| currency | `string` | Currency the link collects in, e.g. `NGN`. See [currency codes](/development-resources/currency-codes/overview). | Yes |
| description | `string` | Longer text describing what the payment is for. | No |
| successMessage | `string` | Message shown to the customer after a successful payment. | No |
| paymentFrequency | `string` | `ONE_TIME` or `RECURRENT`. | No |
| paymentReference | `string` | Your own reference. Leave empty to have SeerBit generate one per payment — a reusable link needs a unique reference per transaction. | No |
| email | `string` | Merchant email associated with the link. | No |
| customizationName | `string` | Name of a checkout customisation configured on your dashboard. | No |
| requiredFields | `object` | Which details the customer must supply. See below. | No |
| additionalData | `string` | Free-form metadata carried with the link. | No |
| linkExpirable | `boolean` | Whether the link stops working on `expiryDate`. | No |
| expiryDate | `string` | Date the link expires, when `linkExpirable` is `true`. | No |
| oneTime | `boolean` | `true` closes the link after a single successful payment. | No |
| status | `string` | `ACTIVE` or `INACTIVE`. An inactive link cannot be paid. | No |

##### `requiredFields` object

Set a field to `true` to make the customer enter it before paying.

| Field | Type | Description |
| - | - | - |
| `amount` | `boolean` | Let the customer enter the amount. Use for donations or open-value links. |
| `customerName` | `boolean` | Collect the payer's name. |
| `mobileNumber` | `boolean` | Collect a phone number. |
| `address` | `boolean` | Collect a billing address. |
| `invoiceNumber` | `boolean` | Collect an invoice reference from the payer. |

#### Response fields

| Name | Type | Description |
| - | - | - |
| paymentLinkId | `string` | Identifier for the link. Use it to update or delete the link. |
| paymentLinkUrl | `string` | The shareable URL. This is what you send to customers. |
| environment | `string` | `TEST` or `LIVE`, reflecting the keys used to create the link. |
| expiryDuration | `number` | How long the link remains valid, when expiry is enabled. |
| splitPayment | `boolean` | Whether the link settles across sub-accounts. |
| createdAt / updatedAt | `string` | Timestamps for the link record. |

> **Note**: Required-flag values above are derived from the request samples on this page. Confirm against the [API Reference](/api-reference) before relying on a field being optional.

## Get Merchant Payment Link

<Badge color="green">GET</Badge>

```bash theme={null}
https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api/{publicKey}
```

#### Request Sample

The code snippet below shows an example request for getting merchant payment link

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api/{publicKey}' \
  --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \
  ```

  ```javascript NODE theme={null}
  var request = require('request');
  var options = {
    'method': 'GET',
    'url': 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api/{publicKey}',
    'headers': {
      'Authorization': 'Bearer YOUR_ENCRYPTED_KEY'
    },

  request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
  });
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api/{publicKey}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
   ,
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer YOUR_ENCRYPTED_KEY'
    ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
  ```
</CodeGroup>

#### Response Sample

The code snippet below shows an example response to get all created links

```json theme={null}
{
  "currentPage": 0,
  "responseCode": "00",
  "payload": [
    {
      "businessId": "00000051",
      "publicKey": "publickey",
      "status": "ACTIVE",
      "amount": 10000.0,
      "customisationName": "SeerBitPay",
      "additionalData": "",
      "paymentLinkName": "SeerBit Payment Link",
      "description": "Buy Items",
      "paymentLinkId": "00000000",
      "paymentFrequency": "ONE_TIME",
      "paymentLinkUrl": "https://pay.seerbitapi.com/paymentLinkID",
      "pocketReference": "",
      "environment": "LIVE",
      "requiredFields": {
        "address": true,
        "amount": false,
        "customerName": true,
        "mobileNumber": false,
        "invoiceNumber": false
      },
      "expiryDuration": 0,
      "linkExpirable": false,
      "customTime": "",
      "createdAt": "2021-07-17T12:05:55",
      "updatedAt": "2021-07-17T12:05:55",
      "oneTime": false,
      "splitPayment": false
    }
  ],
  "responseMessage": "successful"
}
```

## Update Payment Link

<Badge color="yellow">PUT</Badge>

```bash theme={null}
https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api
```

#### Request Sample

The code snippet below shows an example request for updating a payment link

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request PUT 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ENCRYPTED_KEY' \
  --data-raw '{
      "paymentLinkId":{paymentlinkid},
      "status":"INACTIVE",
      "description":"Test paymentLink",
      "successMessage":"Payment made successfully!",
      "businessName":"My Business",
      "publicKey":"publicKey",
        "customizationName":"my_link_3",
        "paymentFrequency":"RECURRENT",
        "email":"customer@seerbit.com",
        "requiredFields": {
            "address":true,
            "amount":true,
            "customerName":true,
            "mobileNumber":true,
            "invoiceNumber":false
        },
        "linkExpirable":false,
        "expiryDate":"",
        "oneTime":false

  }'
  ```

  ```javascript NODE theme={null}
  var request = require('request');
  var options = {
    method: 'PUT',
    url: 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer YOUR_ENCRYPTED_KEY',
    },
    body: JSON.stringify({
      paymentLinkId: '0000000',
      status: 'INACTIVE',
      description: 'Test paymentLink',
      successMessage: 'Payment made successfully!',
      businessName: 'My Business',
      publicKey: 'publicKey',
      customizationName: 'my_link_3',
      paymentFrequency: 'RECURRENT',
      email: 'customer@seerbit.com',
      requiredFields: {
        address: true,
        amount: true,
        customerName: true,
        mobileNumber: true,
        invoiceNumber: false,
      },
      linkExpirable: false,
      expiryDate: '',
      oneTime: false,
    }),
  };
  request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
  });
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_POSTFIELDS =>'{
      "paymentLinkId":"0000000",
      "status":"INACTIVE",
      "description":"Test paymentLink",
      "successMessage":"Payment made successfully!",
      "businessName":"My Business",
      "publicKey":"publicKey",
        "customizationName":"my_link_3",
        "paymentFrequency":"RECURRENT",
        "email":"customer@seerbit.com",
        "requiredFields": {
            "address":true,
            "amount":true,
            "customerName":true,
            "mobileNumber":true,
            "invoiceNumber":false
        },
        "linkExpirable":false,
        "expiryDate":"",
        "oneTime":false

  }',
    CURLOPT_HTTPHEADER => array(
      'Content-Type: application/json',
      'Authorization: Bearer YOUR_ENCRYPTED_KEY'
    ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
  ```
</CodeGroup>

#### Response Sample

The code snippet below shows an example response for updating a payment link

```json theme={null}
{
  "data": {
      "paymentLinks": {
          "publicKey": "PublicKey",
          "status": "INACTIVE",
          "description": "Test paymentLink",
          "successMessage": "Payment made successfully!",
          "paymentLinkId": "0000000",
          "paymentFrequency": "RECURRENT",
          "paymentLinkUrl": "null/my_link_3",
          "customizationName": "my_link_3",
          "environment": "LIVE",
          "requiredFields": {
              "address": true,
              "amount": true,
              "customerName": true,
              "mobileNumber": true,
              "invoiceNumber": false
          },
          "expiryDuration": 0,
          "linkExpirable": false,
          "updatedAt": "2021-09-21T11:12:57.404",
          "oneTime": false,
          "splitPayment": false
      }
  }
}
```

## Delete a Payment Link

<Badge color="red">DELETE</Badge>

```bash theme={null}
https://paymentlink.seerbitapi.com/paymentlink/v2/payLinks/api/deleteLink/{paymentLinkId}
```

#### Response Sample

The code snippet below shows an example response for deleting a payment link

```json theme={null}
{
  "status": "Deleted"
}
```

## Notes

* **Share the `paymentLinkUrl`, not the `paymentLinkId`.** The URL is the customer-facing address; the ID is for managing the link through the API.
* **A reusable link produces many transactions.** Reconcile on the transaction reference returned per payment, not on the link itself.
* **Deactivating is not deleting.** Setting `status` to `INACTIVE` stops payments while keeping the link's history; [deleting](#delete-a-payment-link) removes it.
* Confirm every payment server-side before you fulfil — see [Verify a payment](/online-payments/after-payments/verify-payment).
* Links created with test keys only work in test mode. See [Test and live modes](/test-and-live).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.