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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Themia.Payments.Beam" Version="0.70.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Themia.Payments.Beam" Version="0.70.0" />
                    
Directory.Packages.props
<PackageReference Include="Themia.Payments.Beam" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Themia.Payments.Beam --version 0.70.0
                    
#r "nuget: Themia.Payments.Beam, 0.70.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Themia.Payments.Beam@0.70.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Themia.Payments.Beam&version=0.70.0
                    
Install as a Cake Addin
#tool nuget:?package=Themia.Payments.Beam&version=0.70.0
                    
Install as a Cake Tool

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:

  • Environment must be Playground; any override with Production is refused.
  • It must be a bare origin (no user info, path, query or fragment).
  • http is accepted only for a loopback host (localhost, 127.0.0.0/8, ::1); any other host needs https.

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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed