Payment Link Integration Guide

Overview
Quick Start
API Reference
Webhook Notifications
Examples
Link Lifecycle
Error Handling

Overview

Payment Links enable merchants to collect payments without building a full checkout flow. Generate a secure, one-time-use link that can be shared via email, SMS, or embedded in your application.

Key Features

Secure Payments: PCI-compliant payment collection
One-Time Use: Each link can only be used once
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
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,
  "data": {
    "amount": {
      "value": 99.99,
      "currency": "USD"
    },
    "description": "Premium subscription",
    "merchant_id": "mrc-123456",
    "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"
  }
}

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",
  "data": {
    "amount": {
      "value": 99.99,
      "currency": "USD"
    },
    "description": "Premium subscription",
    "merchant_id": "mrc-123456",
    "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"
  }
}

Request Parameters

Required Fields

Field	Type	Description
`type`	string	Must be `"payment"`
`data.amount.value`	number	Payment amount (must be > 0)
`data.amount.currency`	string	Three-letter currency code (e.g., `"USD"`, `"EUR"`, `"MXN"`)
`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
`data.description`	string	Payment description shown to customer
`data.merchant_id`	string	Merchant identifier for the transaction
`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

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 in the metadata object:

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

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",
      "items": [
        {
          "name": "Widget Pro",
          "description": "Premium widget",
          "quantity": 2,
          "amount": 99.99
        },
        {
          "name": "Shipping",
          "quantity": 1,
          "amount": 50.00
        }
      ],
      "customer": {
        "name": "Jane Smith",
        "email": "[email protected]"
      },
      "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",
      "order_id": "ORD-2025-0042"
    }
  }'

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 are one-time use - once used, they cannot be used again
Expired links return a 410 Gone response
Already-used links return a 409 Conflict response

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

Table of Contents