Themia.Payments.Beam
0.70.0
dotnet add package Themia.Payments.Beam --version 0.70.0
NuGet\Install-Package Themia.Payments.Beam -Version 0.70.0
<PackageReference Include="Themia.Payments.Beam" Version="0.70.0" />
<PackageVersion Include="Themia.Payments.Beam" Version="0.70.0" />
<PackageReference Include="Themia.Payments.Beam" />
paket add Themia.Payments.Beam --version 0.70.0
#r "nuget: Themia.Payments.Beam, 0.70.0"
#:package Themia.Payments.Beam@0.70.0
#addin nuget:?package=Themia.Payments.Beam&version=0.70.0
#tool nuget:?package=Themia.Payments.Beam&version=0.70.0
Themia.Payments.Beam
The Beam Checkout adapter for Themia.Payments: BeamPaymentGateway
implements IPaymentGateway and IPaymentGatewayCapabilities, BeamWebhookVerifier implements
IPaymentWebhookVerifier, and BeamPaymentClient exposes the Beam-only features — payment links and QR
slip verification — that have no counterpart on the provider-agnostic interfaces. Targets net8.0 and
net10.0.
Registration
services.AddThemiaPaymentsBeam(o =>
{
o.MerchantId = configuration["Payments:Beam:MerchantId"]!;
o.ApiKey = configuration["Payments:Beam:ApiKey"]!;
o.Environment = BeamEnvironment.Playground; // sandbox; same API, no real money
o.WebhookHmacKey = configuration["Payments:Beam:WebhookHmacKey"]; // needed only to verify webhooks
});
AddThemiaPaymentsBeam validates MerchantId, ApiKey, Timeout and WebhookHmacKey on start,
registers the named HttpClient, and calls AddThemiaPayments() itself — a host does not need to call
both. Register only one payment adapter per container (see the Themia.Payments README).
Pointing the client at a fake Beam server (test stacks only)
Set BeamOptions.BaseAddress (config key Payments:Beam:BaseAddress) to make the client call your own server instead of
Beam. It wins over the address derived from Environment, and is checked on start:
Environmentmust bePlayground; any override withProductionis refused.- It must be a bare origin (no user info, path, query or fragment).
httpis accepted only for a loopback host (localhost,127.0.0.0/8,::1); any other host needshttps.
The merchant id and API key are sent to that address, so use it only for an environment you control.
WebhookHmacKey is optional, but when set it must be the base64 of at least 16 bytes — the key
Lighthouse gives you is 32. An empty, blank, non-base64 or short key fails startup validation (the key
itself is never echoed in the message), and BeamWebhookVerifier fails closed on any unusable key with
InvalidOperationException rather than computing an HMAC with it: an empty key would let anyone forge a
valid X-Beam-Signature.
Only a lone QrPromptPay charge is a direct charge
CreateChargeAsync posts a direct POST /api/v1/charges only when AllowedMethods resolves (after
the method policy) to exactly [QrPromptPay]. Everything else — a lone Card, MobileBanking,
Wallet, or more than one method offered together — creates a Beam payment link
(POST /api/v1/payment-links) instead: Beam's hosted checkout page collects the details and lets the
shopper choose.
This is not the same failure mode as "no direct card charge type" — a direct POST /api/v1/charges needs
card data or a saved card token, and card tokenization is out of scope for this version, so a
lone [Card] request could never succeed as a direct charge anyway. Routing it through a link, where
Beam's own hosted page collects the card, is the only way a card payment can complete at all today.
When a request becomes a link, ChargeCreation.ChargeId is the link's id, not a charge id.
GetChargeAsync knows this: given that id, it first tries GET /api/v1/charges/{id} (a genuine charge
id), and on a 404 retries it as GET /api/v1/payment-links/{id}, following a paid link to the charge
that actually paid it. A charge id you got back from a single-method QR charge is a real charge id from
the start; a charge id from any other request is a link id until someone pays it. RefundAsync resolves
the id exactly the same way before posting, so refunding by a link id refunds the charge that paid the
link; a link nobody has paid yet is PaymentApiException(FailureKind.NotFound, "no_charge_for_link").
var creation = await gateway.CreateChargeAsync(new CreateChargeRequest
{
Amount = Money.Thb(50_000),
ReferenceId = "order-42",
AllowedMethods = [PaymentMethod.Card], // -> a payment link; creation.ChargeId is the link id
});
// Later, regardless of which path created it:
var charge = await gateway.GetChargeAsync(new ChargeRef(creation.ChargeId, "order-42"));
How many HTTP calls a method makes
Each HTTP call may take up to ~91 s with the default 30 s Timeout (3 attempts plus backoff — see the
Themia.Payments README), so the chains below set the worst case. Pass a CancellationToken with your
own deadline.
| Call | HTTP calls |
|---|---|
CreateChargeAsync |
1 |
GetChargeAsync by charge id / by reference |
1 |
GetChargeAsync by a paid link id |
3 (charge 404 → link → the link's charges), up to ~4.5 min |
RefundAsync by charge id / by reference |
3 (resolve, read the payment method, refund) |
RefundAsync by a link id |
5 (resolve via link, read the payment method, refund), up to ~7.5 min |
BeamPaymentClient — Beam-only features
Reaching for BeamPaymentClient is how an app says out loud that it is now tied to Beam.
var client = provider.GetRequiredService<BeamPaymentClient>();
var link = await client.CreatePaymentLinkAsync(new BeamPaymentLinkRequest
{
Amount = Money.Thb(50_000),
ReferenceId = "order-42",
AllowedMethods = [PaymentMethod.Card, PaymentMethod.QrPromptPay],
ExpiresAt = DateTimeOffset.UtcNow.AddHours(1),
});
await client.GetPaymentLinkAsync(link.Id);
await client.DisablePaymentLinkAsync(link.Id); // the only mutation — a link cannot be edited or deleted
var verification = await client.VerifyQrSlipAsync(rawQrContent); // or the Stream/fileName overload, PNG/JPEG ≤ 2 MB
CreatePaymentLinkAsync applies the same CreateChargeRequestValidator and PaymentMethodGate the
gateway does — this client is not a way around the adopter's method policy.
Slip verification matches only this merchant's own Beam-created charges. A slip printed for a
transfer Beam never charged — including a QR rendered offline by Themia.PromptPay — verifies as
FailureKind.NotFound, never a false match. The image overload refuses a filename containing a double
quote, a backslash, or a control character (it is interpolated into a Content-Disposition header), and
an image larger than 2 MB before it is ever sent.
The webhook signature proves origin, not freshness
X-Beam-Signature is an HMAC-SHA256 over the exact raw body — it authenticates that Beam sent it, but
Beam's scheme carries no timestamp and no nonce. A captured, genuine webhook replays correctly for
ever. BeamWebhookVerifier cannot protect you from this by itself: deduplicate on your own key
(charge id + status is enough) before acting on a Verified event.
The event name arrives on the unsigned X-Beam-Event header — the HMAC covers only the body — so
the verifier reconciles a modelled event's claimed type against the signed body's own chargeId /
refundId / status before trusting it, and reports WebhookOutcome.Malformed rather than a
PaymentEvent the body does not actually support when they disagree.
services.AddThemiaPaymentsBeam(o => { /* … */ o.WebhookHmacKey = configuration["Payments:Beam:WebhookHmacKey"]; });
// in the webhook endpoint, after EnableBuffering() and reading the raw body:
var result = verifier.Verify(rawBody, headers);
if (result.Outcome != WebhookOutcome.Verified) { return Results.BadRequest(); }
// dedupe on (result.Event!.ChargeId, result.Event.Status) before acting
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Configuration (>= 10.0.9)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.9)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.9)
- Microsoft.Extensions.DependencyInjection (>= 10.0.9)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.9)
- Microsoft.Extensions.Http (>= 10.0.9)
- Microsoft.Extensions.Logging (>= 10.0.9)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.9)
- Microsoft.Extensions.Options (>= 10.0.9)
- Themia.Payments (>= 0.70.0)
-
net8.0
- Microsoft.Extensions.Configuration (>= 10.0.9)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.9)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.9)
- Microsoft.Extensions.DependencyInjection (>= 10.0.9)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.9)
- Microsoft.Extensions.Http (>= 10.0.9)
- Microsoft.Extensions.Logging (>= 10.0.9)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.9)
- Microsoft.Extensions.Options (>= 10.0.9)
- Themia.Payments (>= 0.70.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.70.0 | 49 | 11/21/2026 |
| 0.69.0 | 95 | 11/18/2026 |
| 0.68.0 | 66 | 11/18/2026 |
| 0.67.2 | 76 | 11/18/2026 |
| 0.67.1 | 76 | 11/18/2026 |
| 0.67.0 | 82 | 11/17/2026 |
| 0.66.0 | 79 | 11/17/2026 |
| 0.65.0 | 87 | 11/16/2026 |
| 0.64.0 | 135 | 11/15/2026 |
| 0.63.2 | 98 | 11/15/2026 |
| 0.63.1 | 120 | 11/14/2026 |
| 0.63.0 | 92 | 11/14/2026 |
| 0.62.1 | 93 | 11/14/2026 |
| 0.62.0 | 96 | 11/14/2026 |
| 0.61.1 | 105 | 11/14/2026 |
| 0.61.0 | 94 | 11/13/2026 |
| 0.60.0 | 123 | 11/10/2026 |
| 0.59.0 | 93 | 11/10/2026 |
| 0.58.0 | 91 | 11/9/2026 |
| 0.57.2 | 103 | 11/8/2026 |