Card Enrollment Link Integration Guide

Overview

The Card Enrollment Link allows you to securely collect and store customer payment cards. These links can be embedded in iframes and fully customized to match your brand.

Quick Start

1. Create a Card Enrollment Link

Endpoint: POST https://sandbox.akua.la/v1/links

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Basic Request:

{
  "type": "card_enrollment",
  "expires_in": 3600,
  "metadata": {
    "sandbox": false
  }
}

Request with Styling:

{
  "type": "card_enrollment",
  "expires_in": 86400,
  "data": {
    "webhook": "https://your-domain.com/webhook",
    "api_key": "your-webhook-api-key"
  },
  "metadata": {
    "sandbox": false,
    "styleConfig": {
      "visibility": {
        "header": false,
        "footer": false
      },
      "text": {
        "buttonText": "Save Card"
      },
      "colors": {
        "primary": "#007bff"
      }
    }
  }
}

Response:

{
  "id": "lnk-d7ac0929-504b-4f37-b23d-20ecc185740e",
  "url": "https://checkout-dev.akua.la/link/lnk-d7ac0929-504b-4f37-b23d-20ecc185740e",
  "type": "card_enrollment",
  "status": "created",
  "client_id": "cli-csgg2dblhcklgmeucd10",
  "expires_at": "2025-11-19T17:48:24.498072802Z"
}

2. Embed in Your Website

<!DOCTYPE html>
<html>
<head>
  <title>Add Payment Method</title>
</head>
<body>
  <iframe
    src="https://checkout-dev.akua.la/link/lnk-YOUR-LINK-ID"
    width="100%"
    height="600"
    frameborder="0"
    style="max-width: 500px; margin: 0 auto; display: block;"
  ></iframe>
</body>
</html>

Styling Configuration

Customize the form appearance through the styleConfig object in metadata:

Simple Examples

Minimal Form (No Header/Footer):

{
  "styleConfig": {
    "visibility": {
      "header": false,
      "footer": false
    }
  }
}

Custom Colors:

{
  "styleConfig": {
    "colors": {
      "background": "#f5f5f5",
      "primary": "#007bff",
      "text": "#333333"
    }
  }
}

Custom Text:

{
  "styleConfig": {
    "text": {
      "headerTitle": "Add Your Card",
      "buttonText": "Save",
      "successMessage": "Card saved!"
    }
  }
}

Complete StyleConfig Structure

{
  visibility?: {
    header?: boolean;       // Show/hide header
    footer?: boolean;       // Show/hide footer
    labels?: boolean;       // Show/hide field labels
    alerts?: boolean;       // Show/hide success/error alerts
  };

  text?: {
    headerTitle?: string;      // Header text
    cardFormSubtitle?: string; // Subtitle text
    footerText?: string;       // Footer text
    buttonText?: string;       // Submit button text
    successMessage?: string;   // Success message
    errorMessage?: string;     // Error message
  };

  colors?: {
    background?: string;       // Page background
    formBackground?: string;   // Form background
    primary?: string;          // Primary color (buttons)
    text?: string;             // Text color
    success?: string;          // Success alert color
    error?: string;            // Error alert color
  };

  layout?: {
    formWidth?: string;        // Form width (e.g., '100%', '500px')
    formMaxWidth?: string;     // Max form width
    padding?: string;          // Padding ('sm', 'md', 'lg')
    alignment?: 'left' | 'center' | 'right';
  };

  styles?: {
    container?: CSSProperties;  // Custom CSS for container
    form?: CSSProperties;       // Custom CSS for form
    header?: CSSProperties;     // Custom CSS for header
    footer?: CSSProperties;     // Custom CSS for footer
    button?: CSSProperties;     // Custom CSS for button
    alert?: CSSProperties;      // Custom CSS for alerts
  };
}

Webhook Notifications

When a card is successfully enrolled, a webhook notification is sent if configured:

Webhook Configuration:

{
  "data": {
    "webhook": "https://your-domain.com/webhook",
    "api_key": "your-secret-key"
  }
}

Webhook Payload:

{
  "instrument_id": "ins-abc123"
}

The webhook will include the Api-Key header if provided.

React Integration Example

import React from 'react';

const CardEnrollmentIframe = ({ linkId }) => {
  return (
    <iframe
      src={`https://checkout-dev.akua.la/link/${linkId}`}
      width="100%"
      height="600"
      frameBorder="0"
      style={{
        maxWidth: '500px',
        margin: '0 auto',
        display: 'block',
        border: 'none',
        borderRadius: '8px',
      }}
    />
  );
};

export default CardEnrollmentIframe;

cURL Example

curl -X POST https://akua.dev.akua.la/links-api/v1/links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Client-Id: YOUR_CLIENT_ID" \
  -d '{
    "type": "card_enrollment",
    "expires_in": 3600,
    "data": {
      "sandbox": true
    }
  }'

API Response Status

created: Link has been created and is ready to use
opened: Link has been accessed/viewed
used: Card has been successfully enrolled