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.

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

Request Headers

Request Body

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

Response

```json
{
"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.

```bash
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.