Table of Contents

Overview
Quick Start
API Reference
Webhook Notifications
Examples
Link Lifecycle
Multi-Use Links
Error Handling

Overview

Payment Links enable merchants to collect payments without building a full checkout flow. Generate secure payment links with flexible configurations - from single-use to reusable links, fixed amounts to customer-entered values, and include tax calculations and customer data collection. Share links via email, SMS, or embed them in your application.

Key Features

Secure Payments: PCI-compliant payment collection
Flexible Usage: Choose between single-use or multi-use links with optional usage limits
Custom Amount Links: Allow customers to enter their own payment amount with optional min/max constraints
Tax Support: Automatic tax calculation and display in payment links
Configurable User Data: Request additional customer information (country, city, zip code, address)
Configurable Expiration: Set custom expiration times (default: 12 hours)
Webhook Notifications: Receive real-time payment confirmations
Multiple Payment Methods: Support for various payment instruments
Item Details: Include line items with quantities and prices

Use Cases

E-commerce checkout processes
Invoice payments
Subscription payments
Donations & fundraising
Event tickets
Product catalogs
One-time product purchases
Pay-by-link for remote sales

Quick Start

1. Create a Payment Link

curl -X POST https://sandbox.akua.la/v1/links \
  -H "Content-Type: application/json" \
  -H "Client-Id: your-client-id" \
  -d '{
    "type": "payment",
    "expires_in": 3600,
    "data": {
      "amount": {
        "value": 99.99,
        "currency": "USD"
      },
      "description": "Order #12345"
    }
  }'

2. Share the Link

The response includes a url field - share this with your customer via email, SMS, or embed it in your application.

3. Customer Completes Payment

The customer opens the link, enters payment details, and completes the transaction.

4. Receive Webhook Notification

Configure a webhook to receive real-time payment confirmation with the payment_id and transaction_id.

API Reference

Base URLs

Environment	URL
Sandbox	`https://sandbox.akua.la/v1/links`
Production	`https://api.akua.la/v1/links`

Create Payment Link

POST /v1/links

Headers:

Header	Required	Description
`Content-Type`	Yes	`application/json`
`Client-Id`	Yes	Your client identifier

Request Body:

{
  "type": "payment",
  "expires_in": 3600,
  "multi_use": false,
  "data": {
    "amount": {
      "type": "fixed",
      "value": 99.99,
      "tax": 9.99,
      "currency": "USD"
    },
    "description": "Premium subscription",
    "merchant_id": "mer-123456",
    "merchant_name": "Acme Store",
    "items": [
      {
        "name": "Premium Plan",
        "description": "Monthly subscription",
        "quantity": 1,
        "amount": 99.99
      }
    ],
    "redirect_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  },
  "metadata": {
    "webhook": "https://your-domain.com/webhooks/payment",
    "api_key": "your-webhook-secret",
    "client_name": "Acme Corp",
    "additional_fields": ["country", "city"]
  }
}

Response: 201 Created

{
  "id": "lnk-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://checkout.akua.la/link/lnk-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payment",
  "status": "created",
  "multi_use": false,
  "use_count": 0,
  "data": {
    "amount": {
      "type": "fixed",
      "value": 99.99,
      "tax": 9.99,
      "total": 109.98,
      "currency": "USD"
    },
    "description": "Premium subscription",
    "merchant_id": "mrc-123456",
    "merchant_name": "Acme Store",
    "items": [
      {
        "name": "Premium Plan",
        "description": "Monthly subscription",
        "quantity": 1,
        "amount": 99.99
      }
    ],
    "redirect_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  },
  "client_id": "cli-xyz789",
  "expires_at": "2025-01-15T14:00:00Z",
  "created_at": "2025-01-15T13:00:00Z",
  "updated_at": "2025-01-15T13:00:00Z",
  "metadata": {
    "webhook": "https://your-domain.com/webhooks/payment",
    "api_key": "your-webhook-secret",
    "client_name": "Acme Corp",
    "additional_fields": ["country", "city", "zip_code"]
  }
}

Request Parameters

Required Fields

Field	Type	Description
`type`	string	Must be `"payment"`
`data.amount.currency`	string	Three-letter currency code (e.g., `"USD"`, `"EUR"`, `"MXN"`)
`data.amount.value`*	number	Payment amount (must be > 0). Required for fixed-amount links, must NOT be provided for custom-amount links
`data.description` OR `data.items`	string OR array	At least one is required: Either a payment description string OR an array of line items (see Item Object structure below)

Optional Fields

Field	Type	Description
`expires_in`	integer	Seconds until expiration (range: 60-86400). If not provided, defaults to 12 hours
`multi_use`	boolean	Set to `true` to allow multiple uses of the same link (default: `false`)
`max_uses`	integer	Maximum number of times a multi-use link can be used (only valid when `multi_use` is `true`)
`data.description`	string	Payment description shown to customer
`data.merchant_id`	string	Merchant identifier for the transaction
`data.merchant_name`	string	Merchant name displayed in the checkout UI
`data.items`	array	Array of line items (see below)
`data.customer`	object	Customer information (name, email, phone)
`data.allowed_payment_methods`	array	Accepted payment methods
`data.redirect_url`	string	URL to redirect after successful payment
`data.cancel_url`	string	URL to redirect if customer cancels
`metadata`	object	Custom metadata and webhook configuration (see below)

Amount Object

The amount object supports two modes: fixed amount (default) and custom amount.

Fixed Amount Mode (default):

{
  "type": "fixed",
  "value": 99.99,
  "tax": 9.99,
  "currency": "USD"
}

When tax is provided, the system automatically calculates total = value + tax and displays it to the customer.

Custom Amount Mode:

{
  "type": "custom",
  "currency": "USD",
  "min_amount": 10.0,
  "max_amount": 1000.0
}

In custom amount mode:

The customer enters the payment amount
value and tax fields must NOT be provided
min_amount and max_amount are optional constraints
If both min and max are provided, min must be less than max

Amount Object Fields:

Field	Type	Required	Description
`type`	string	No (default: `"fixed"`)	Amount type: `"fixed"` or `"custom"`
`value`	number	Yes (for fixed only)	Payment amount. Must NOT be provided for custom amount links
`tax`	number	No (fixed only)	Tax amount to add to value. Must NOT be provided for custom amount links
`currency`	string	Yes	Three-letter currency code (e.g., `"USD"`, `"EUR"`, `"MXN"`)
`min_amount`	number	No (custom only)	Minimum allowed amount for custom links. Must be > 0
`max_amount`	number	No (custom only)	Maximum allowed amount for custom links. Must be > min_amount
`total`	number	No (auto-calculated)	Read-only field showing `value + tax` (automatically calculated)

Item Object

{
  "name": "Product Name",
  "description": "Product description",
  "quantity": 1,
  "amount": 49.99
}

Get Payment Link

GET /v1/links/{id}

Response: 200 OK

Returns the full link object with current status and data.

Webhook Notifications

Receive real-time notifications when payments are completed.

Configuration

Include webhook settings and additional options in the metadata object:

{
  "metadata": {
    "webhook": "https://your-domain.com/webhooks/payment",
    "api_key": "your-webhook-secret",
    "client_name": "Your Business Name"
  }
}

Metadata Fields:

Field	Type	Description
`webhook`	string	URL to receive payment notifications
`api_key`	string	Secret key sent in webhook headers for verification
`client_name`	string	(Optional) Client name for display purposes
`additional_fields`	array	(Optional) Array of additional user data fields to collect: `["country", "city", "zip_code", "address"]`

Additional Fields:

The additional_fields array in metadata allows you to request additional information from customers during checkout. Fields included in this array will be displayed as required fields in the payment form.

Supported values:

"country" - Customer's country
"city" - Customer's city
"zip_code" - Customer's postal/zip code
"address" - Customer's street address

Example:

{
  "metadata": {
    "webhook": "https://your-domain.com/webhooks/payment",
    "api_key": "your-webhook-secret",
    "additional_fields": ["country", "city", "zip_code", "address"]
  }
}

Only the fields you specify will be requested from the customer. If additional_fields is not provided or is an empty array, no additional fields will be collected.

Webhook Payload

When a payment is completed, a POST request is sent to your webhook URL:

{
  "link_id": "lnk-abc123",
  "payment_id": "pay-xyz789",
  "transaction_id": "trx-abc123"
}

Headers

Header	Description
`Content-Type`	`application/json`
`Api-Key`	Your configured `api_key` (if provided)

Examples

cURL Examples

Create a simple payment link:

curl -X POST https://sandbox.akua.la/v1/links \
  -H "Content-Type: application/json" \
  -H "Client-Id: cli-your-client-id" \
  -d '{
    "type": "payment",
    "expires_in": 3600,
    "data": {
      "amount": {
        "value": 150.00,
        "currency": "USD"
      },
      "description": "Invoice #INV-2025-001"
    }
  }'

Create a payment link with items and webhook:

curl -X POST https://sandbox.akua.la/v1/links \
  -H "Content-Type: application/json" \
  -H "Client-Id: cli-your-client-id" \
  -d '{
    "type": "payment",
    "expires_in": 7200,
    "data": {
      "amount": {
        "value": 249.98,
        "currency": "USD"
      },
      "description": "Online Store Purchase",
      "merchant_id": "mrc-store123",
      "merchant_name": "Widget Store",
      "items": [
        {
          "name": "Widget Pro",
          "description": "Premium widget",
          "quantity": 2,
          "amount": 99.99
        },
        {
          "name": "Shipping",
          "quantity": 1,
          "amount": 50.00
        }
      ],
      "customer": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "redirect_url": "https://store.example.com/thank-you",
      "cancel_url": "https://store.example.com/cart"
    },
    "metadata": {
      "webhook": "https://store.example.com/api/webhooks/akua",
      "api_key": "whsec_abc123xyz",
      "client_name": "Widget Store Inc",
      "order_id": "ORD-2025-0042"
    }
  }'

Create a payment link with tax:

curl -X POST https://sandbox.akua.la/v1/links \
  -H "Content-Type: application/json" \
  -H "Client-Id: cli-your-client-id" \
  -d '{
    "type": "payment",
    "expires_in": 3600,
    "data": {
      "amount": {
        "type": "fixed",
        "value": 100.00,
        "tax": 10.00,
        "currency": "USD"
      },
      "description": "Product with tax"
    }
  }'

The response will include the calculated total (110.00 in this case).

Create a custom amount payment link:

curl -X POST https://sandbox.akua.la/v1/links \
  -H "Content-Type: application/json" \
  -H "Client-Id: cli-your-client-id" \
  -d '{
    "type": "payment",
    "expires_in": 3600,
    "data": {
      "amount": {
        "type": "custom",
        "currency": "USD",
        "min_amount": 10.00,
        "max_amount": 500.00
      },
      "description": "Donation - Enter your amount"
    }
  }'

Create a multi-use payment link:

curl -X POST https://sandbox.akua.la/v1/links \
  -H "Content-Type: application/json" \
  -H "Client-Id: cli-your-client-id" \
  -d '{
    "type": "payment",
    "multi_use": true,
    "max_uses": 100,
    "expires_in": 86400,
    "data": {
      "amount": {
        "value": 50.00,
        "currency": "USD"
      },
      "description": "Event ticket - Reusable link"
    }
  }'

Create a payment link with additional user data fields:

curl -X POST https://sandbox.akua.la/v1/links \
  -H "Content-Type: application/json" \
  -H "Client-Id: cli-your-client-id" \
  -d '{
    "type": "payment",
    "expires_in": 3600,
    "data": {
      "amount": {
        "value": 150.00,
        "currency": "USD"
      },
      "description": "Product requiring shipping address"
    },
    "metadata": {
      "webhook": "https://your-domain.com/webhooks/payment",
      "additional_fields": ["country", "city", "zip_code", "address"]
    }
  }'

Get link status:

curl -X GET https://sandbox.akua.la/v1/links/lnk-abc123 \
  -H "Client-Id: cli-your-client-id"

Link Lifecycle

Payment links transition through the following states:

┌──────────┐     ┌──────────┐
│ created  │────▶│   used   │
└──────────┘     └──────────┘
      │
      │
      ▼
┌──────────────────────────────────────────┐
│              expired                      │
│  (automatic after expires_at timestamp)   │
└──────────────────────────────────────────┘

Status Definitions

Status	Description
`created`	Link generated, ready to be shared
`used`	Payment completed successfully
`expired`	Link has passed its expiration time

Important Notes

Links can be configured as single-use (default) or multi-use
Single-use links cannot be used again after the first payment
Multi-use links can be used multiple times, with an optional max_uses limit
Expired links return a 410 Gone response
Already-used single-use links return a 409 Conflict response

Multi-Use Links

By default, payment links are single-use and expire after the first successful payment. However, you can create multi-use links that can be used multiple times.

Enabling Multi-Use

To create a multi-use link, set multi_use: true in your link creation request:

{
  "type": "payment",
  "multi_use": true,
  "data": {
    "amount": {
      "value": 99.99,
      "currency": "USD"
    },
    "description": "Monthly subscription"
  }
}

Usage Limits

You can optionally limit the number of times a multi-use link can be used with the max_uses field:

{
  "type": "payment",
  "multi_use": true,
  "max_uses": 10,
  "data": {
    "amount": {
      "value": 99.99,
      "currency": "USD"
    },
    "description": "Group event tickets (max 10)"
  }
}

Link Response

Multi-use links include usage tracking in the response:

{
  "id": "lnk-abc123",
  "multi_use": true,
  "max_uses": 10,
  "use_count": 3,
  "status": "created"
}

Fields:

multi_use: true if the link can be used multiple times
max_uses: Maximum allowed uses (optional, null means unlimited)
use_count: Current number of successful payments made with this link

Link Status for Multi-Use

Multi-use links behave differently than single-use links:

Before max uses reached: Status remains "created" and link can be used
After max uses reached: Status changes to "used" and link cannot be used anymore (if max_uses is set)
No max uses set: Link can be used indefinitely until expiration
After expiration: Status changes to "expired" regardless of usage

Use Cases

Multi-use links are ideal for:

Recurring payments: Monthly subscriptions, membership fees
Group payments: Event tickets, group orders
Donation links: Ongoing fundraising campaigns
Product catalogs: Reusable payment links for the same product
Limited edition sales: Set max_uses to control inventory

Error Handling

HTTP Status Codes

Code	Description
`200 OK`	Request successful
`201 Created`	Link created successfully
`400 Bad Request`	Invalid request format, missing Client-Id, or validation error
`403 Forbidden`	Unauthorized access to this resource
`404 Not Found`	Link not found
`409 Conflict`	Link has already been used
`410 Gone`	Link has expired
`500 Internal Server Error`	Server error

Error Response Format

{
  "error": "Link has expired"
}

Common Error Messages

HTTP Status	Error Message
`400`	`"Client ID header is required"`
`400`	`"Invalid JSON data"`
`403`	`"Unauthorized access"`
`409`	`"Link has already been used"`
`410`	`"Link has expired"`

`"Link has expired"`