Payments

Protokol Payments enables online payment processing through supported payment gateways. It supports the full transaction lifecycle — authorization, purchase, capture, void, refund — and card tokenization for recurring payments.

Note

This integration is currently geolocked to Serbia (RS).

Overview

Key characteristics:

Transaction lifecycle — authorization, purchase, capture, void, and refund operations
Payment links — generate hosted payment pages for checkout flows
Card tokenization — securely store card tokens for recurring payments
Direct token payments — charge stored tokens without redirect
Transaction reporting — workflow events on transaction status changes
Provider support — currently supports Monri payment gateway

Creating a Payment Link

Generate a hosted payment page that redirects the customer to complete payment.

SDKHTTP (cURL)

import { Payments } from "@ptkl/sdk/beta"

const payments = new Payments()
const link = await payments.getPaymentLink("monri", "user-123", {
  totalAmount: "1500.00",
  description: "Order #456",
  redirectUrl: "https://myapp.com/payment/complete",
  lang: "en",
})

console.log(link) // { url: "https://...", transactionId: "..." }

curl -X POST https://lemon.protokol.io/luma/integrations/v1/protokol-payments/monri/user-123/payment-link \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "totalAmount": "1500.00",
    "description": "Order #456",
    "redirectUrl": "https://myapp.com/payment/complete",
    "lang": "en"
  }'

Payment with Line Items

SDK

import { Payments } from "@ptkl/sdk/beta"

const payments = new Payments()
const link = await payments.getPaymentLink("monri", "user-123", {
  items: [
    { name: "Widget A", pricePerUnit: 500, quantity: 2, price: 1000 },
    { name: "Shipping", price: 350 },
  ],
  description: "Order #456",
  redirectUrl: "https://myapp.com/payment/complete",
})

Listing Transactions

SDKHTTP (cURL)

import { Payments } from "@ptkl/sdk/beta"

const payments = new Payments()
const result = await payments.getTransactions("user-123", {
  status: "completed",
  sortBy: "createdAt",
  sortDirection: "desc",
  limit: 20,
  page: 1,
})

console.log(result.transactions)  // Transaction[]
console.log(result.totalCount)    // total matching count

curl -X GET "https://lemon.protokol.io/luma/integrations/v1/protokol-payments/transactions/user-123?status=completed&limit=20&page=1" \
  -H "Authorization: Bearer $TOKEN"

Getting a Single Transaction

SDKHTTP (cURL)

import { Payments } from "@ptkl/sdk/beta"

const payments = new Payments()
const tx = await payments.getTransaction("monri", "user-123", "tx-id-789")

console.log(tx.status)  // "completed"
console.log(tx.amount)  // 1500

curl -X GET https://lemon.protokol.io/luma/integrations/v1/protokol-payments/monri/user-123/tx-id-789 \
  -H "Authorization: Bearer $TOKEN"

Transaction Fields

Field	Type	Description
`id`	`string`	Internal transaction ID
`provider`	`string`	Payment provider (e.g. `"monri"`)
`transactionId`	`string`	Provider-side transaction ID
`userId`	`string`	User reference
`amount`	`number`	Transaction amount (minor units)
`precision`	`number`	Decimal precision
`currency`	`string`	Currency code
`status`	`string`	`pending`, `completed`, `failed`, `refunded`, `voided`, `deactivated`, `expired`
`description`	`string`	Transaction description
`paymentLink`	`string`	Payment page URL (if applicable)
`autoRefund`	`boolean`	Whether auto-refund is enabled
`metadata`	`object`	Additional metadata (lang, items)
`logs`	`array`	Status change log entries
`expiresAt`	`string`	Expiration timestamp
`createdAt`	`string`	Creation timestamp

Void, Refund, and Deactivate

SDKHTTP (cURL)

import { Payments } from "@ptkl/sdk/beta"

const payments = new Payments()

// Void a pending transaction
await payments.voidTransaction("monri", "user-123", "tx-id-789")

// Refund a completed transaction
await payments.refund("monri", "user-123", "tx-id-789")

// Deactivate a payment link
await payments.deactivatePaymentLink("monri", "user-123", "tx-id-789")

# Void
curl -X POST https://lemon.protokol.io/luma/integrations/v1/protokol-payments/monri/user-123/tx-id-789/void \
  -H "Authorization: Bearer $TOKEN"

# Refund
curl -X POST https://lemon.protokol.io/luma/integrations/v1/protokol-payments/monri/user-123/tx-id-789/refund \
  -H "Authorization: Bearer $TOKEN"

Card Tokenization

Request a token for storing card details for future payments.

SDK

import { Payments } from "@ptkl/sdk/beta"

const payments = new Payments()

// Get a tokenization link (redirects user to enter card)
const tokenLink = await payments.getTokenRequestLink("monri", "user-123", {
  description: "Save card for recurring billing",
  redirectUrl: "https://myapp.com/card-saved",
})

// Charge a stored token directly
const tx = await payments.directPayUsingToken("monri", "user-123", {
  totalAmount: "2000.00",
  description: "Monthly subscription",
  token: "stored-card-token",
})

Provider Settings

SDK

import { Payments } from "@ptkl/sdk/beta"

const payments = new Payments()
const settings = await payments.settings("monri")

console.log(settings.merchant_key)
console.log(settings.authenticity_token)

Workflow Integration

Transaction Events

Event	When
`integration.payment.transaction.report`	Transaction status changed (created, completed, failed, refunded, etc.)

Permissions

Permission	Description
`view_transactions`	View transaction list and details
`create_authorization_transaction`	Create authorization-only transactions
`create_purchase_transaction`	Create purchase (direct charge) transactions
`void_transaction`	Void pending transactions
`refund_transaction`	Refund completed transactions
`capture_transaction`	Capture authorized transactions
`tokenize_card`	Request card tokenization
`use_tokenized_card`	Charge stored card tokens

Using in Platform Functions

const { Payments } = $sdk.version('0.10')
const payments = new Payments()

// Create payment link for an order
const link = await payments.getPaymentLink("monri", $input.body.user_id, {
  totalAmount: $input.body.amount,
  description: "Order #" + $input.body.order_id,
  redirectUrl: $input.body.redirect_url,
})

response.json({
  payment_url: link.url,
  transaction_id: link.transactionId,
})

SDK Reference

The Payments class is available via the SDK:

import { Payments } from "@ptkl/sdk/beta"

// Or via the Integrations facade
import { Integrations } from "@ptkl/sdk/beta"
const integrations = new Integrations()
const payments = integrations.getPayments()

Method	Description
`payments.getPaymentLink(provider, userId, options)`	Generate a hosted payment link
`payments.getTransactions(userId, params?)`	List transactions with filtering
`payments.getTransaction(provider, userId, txId)`	Get a single transaction
`payments.voidTransaction(provider, userId, txId)`	Void a pending transaction
`payments.refund(provider, userId, txId)`	Refund a completed transaction
`payments.deactivatePaymentLink(provider, userId, txId)`	Deactivate a payment link
`payments.settings(provider)`	Get provider configuration
`payments.getTokenRequestLink(provider, userId, options)`	Request card tokenization link
`payments.directPayUsingToken(provider, userId, options)`	Charge a stored card token