Single Payments
One-time Lightning payments from an authenticated user. You request a payment; the user approves or rejects in their wallet; you get status updates and, on success, a preimage.
API
requestSinglePayment(mainKey, subkeys, paymentRequest, onStatusChange)
- paymentRequest: amount (millisats; 1 sat = 1000), currency (
Currency.Millisats), description. - onStatusChange: callback receives status objects. status values: paid, user_approved, user_rejected, user_failed, timeout, error. On paid use preimage; on failure use reason.
await client.requestSinglePayment(
userPubkey,
[],
{
amount: 10000, // 10 sats (millisats)
currency: Currency.Millisats,
description: 'Premium - 1 month'
},
(status) => {
if (status.status === 'paid') { /* preimage in status.preimage */ }
}
);
import cc.getportal.command.request.RequestSinglePaymentRequest;
import cc.getportal.model.SinglePaymentRequestContent;
import cc.getportal.model.Currency;
import java.util.List;
SinglePaymentRequestContent payment = new SinglePaymentRequestContent(
"Premium - 1 month", 10_000L, Currency.MILLISATS, null, null
);
sdk.sendCommand(
new RequestSinglePaymentRequest(
"user-pubkey-hex",
List.of(),
payment,
(n) -> System.out.println("status: " + n.status())
),
(res, err) -> {
if (err != null) { System.err.println(err); return; }
System.out.println("invoice: " + res);
}
);
# 1. Request payment (amount in millisats; 1 sat = 1000 millisats)
curl -s -X POST $BASE_URL/payments/single \
-H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"main_key": "USER_PUBKEY_HEX",
"subkeys": [],
"description": "Premium - 1 month",
"amount": 10000,
"currency": "millisats"
}'
# → { "stream_id": "xyz789" }
# 2. Poll for payment status
curl -s "$BASE_URL/events/xyz789?after=0" \
-H "Authorization: Bearer $AUTH_TOKEN"
# → { "events": [{ "index": 0, "data": { "status": "paid", "preimage": "..." } }] }
Poll until status is paid, user_rejected, timeout, or error. See REST API.
Invoice payment: requestInvoicePayment(mainKey, subkeys, { amount, currency, description, invoice, expires_at }, onStatusChange) — pay an external Lightning invoice. Java: RequestInvoicePaymentRequest.
Linked to subscription: Include subscription_id in the single payment request when tying the first payment to a recurring subscription (see Recurring Payments).
Handle all status values; set a timeout in your app if needed. Store preimage for proof of payment.
Next: Recurring Payments · Cashu Tokens · Profiles