Paylinks

Paylinks are shareable payment links that allow you to collect payments from customers without requiring a full integration. Create a paylink, share the URL, and customers can pay directly through a simple checkout page.

Overview

Paylinks are perfect for:

• One-time payments
• Donations
• Invoice payments
• Selling products or services
• Variable or fixed amount payments

Each paylink has a unique slug that creates a public URL: https://cari.finance/p/{slug}

The paylink model

Create a paylink

curl -X POST https://api.cari.finance/paylinks \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Subscription",
    "description": "Monthly premium subscription",
    "amount": 2999,
    "currency": "usd",
    "amount_type": "fixed",
    "max_uses": 1,
    "enabled_providers": ["card"]
  }'

{
  "id": "plink_abc123def456",
  "title": "Premium Subscription",
  "description": "Monthly premium subscription",
  "amount": 2999,
  "currency": "usd",
  "amount_type": "fixed",
  "slug": "premium-subscription",
  "current_uses": 0,
  "max_uses": 1,
  "active": true,
  "expires_at": null,
  "enabled_providers": ["card"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List all paylinks

curl -G https://api.cari.finance/paylinks \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3" \
  -d page=1 \
  -d items_per_page=20

{
  "data": [
    {
      "id": "plink_abc123",
      "title": "Premium Subscription",
      "amount": 2999,
      "currency": "usd",
      "amount_type": "fixed",
      "slug": "premium-subscription",
      "current_uses": 0,
      "active": true
    }
  ],
  "total_count": 1,
  "has_more": false
}

Retrieve a paylink

curl https://api.cari.finance/paylinks/plink_abc123def456 \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3"

Update a paylink

curl -X PUT https://api.cari.finance/paylinks/plink_abc123def456 \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "active": false
  }'

Delete a paylink

curl -X DELETE https://api.cari.finance/paylinks/plink_abc123def456 \
  -H "Authorization: Bearer pk_test_27436257e3fe4b0fa266f4a6f59047a3"

Public endpoints

These endpoints don't require authentication and are used by the public checkout page.

Get public paylink

Retrieve public information about a paylink by its slug.

curl https://api.cari.finance/p/premium-subscription

Validate paylink

Validate a paylink password (if password-protected).

curl -X POST https://api.cari.finance/p/premium-subscription/validate \
  -H "Content-Type: application/json" \
  -d '{
    "password": "secret123"
  }'

Process paylink payment

Process a payment through a paylink. This endpoint handles the payment processing and links the charge to the paylink.

curl -X POST https://api.cari.finance/p/premium-subscription/pay \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2999,
    "provider": "card",
    "card": {
      "token": "card_token_here"
    },
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "password": "secret123"
  }'

Variable amount paylinks

For variable amount paylinks, customers can specify their own payment amount. When processing the payment, include the amount parameter:

{
  "amount": 5000,
  "provider": "card",
  "card": {
    "token": "card_token_here"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Best practices

1. Use descriptive slugs: Create meaningful slugs that reflect the purpose of the paylink
2. Set expiration dates: For time-sensitive offers, always set an expiration date
3. Limit usage: Use max_uses to prevent abuse of donation or one-time payment links
4. Password protection: Add password protection for sensitive or high-value paylinks
5. Monitor usage: Track current_uses to understand how your paylinks are being used