Payments API

The Payments API is the core engine for moving value across the Linka network. It supports single payments, bulk payouts, and complex multi-step cross-border settlements.

Core Concepts

Payment Object: Represents a single transfer of value from a source to a destination.
Settlement: The process of finality where funds are confirmed in the destination account.
Idempotency: All POST requests support idempotency keys to prevent duplicate processing.

Create a Payment

Use this endpoint to initiate a transfer between Linka wallets or to an external address.

POST https://api.linka.xyz/v1/payments

Request Headers

Header	Type	Description
`Authorization`	`string`	`Bearer sk_live_...`
`Idempotency-Key`	`string`	Unique key to prevent duplicates (optional)

Request Body

{
  "amount": "100.00",
  "currency": "USDC",
  "source_wallet": "wal_orig_123",
  "recipient": "wal_dest_456",
  "description": "Invoice #8872",
  "metadata": {
    "internal_id": "inv_99"
  }
}

Response

{
  "id": "pay_123456789",
  "object": "payment",
  "amount": "100.00",
  "currency": "USDC",
  "status": "pending",
  "source": "wal_orig_123",
  "destination": "wal_dest_456",
  "created_at": "2024-01-01T12:00:00Z"
}

List Payments

Retrieve a paginated list of payments associated with your account.

GET https://api.linka.xyz/v1/payments?limit=10&offset=0

Query Parameters

status: Filter by pending, completed, or failed.
currency: Filter by currency code (e.g., USDC, MXN).
recipient_id: Filter by a specific recipient.

Webhook Events

When a payment changes status, we will send a notification to your configured webhook URL:

payment.created: Triggered immediately upon creation.
payment.succeeded: Triggered when funds reach the destination.
payment.failed: Triggered if the transaction is rejected or fails on-chain.

[!WARNING] Always verify the Idempotency-Key if you are retrying requests due to network timeouts.