Link de Pagamento API · OAuth 2.0 · Pix / Boleto / Credit card
Tick the override checkboxes on individual fields to set per-store values.
Migration from v1.0.0 — the legacy MerchantId, PublicKey, SecretKey fields have been removed. Enter your new Client ID and Client Secret from the PicPay merchant portal before turning on checkout. The 3DS option is no longer offered because PicPay does not publicly expose 3DS through the Link API.
Credentials
OAuth 2.0 client credentials
Enabled — buyers see PicPay on the payment step
Maps to ShowInCheckout in PicPayPaymentSettings.
Use Sandbox Sandbox
Sandbox base URL: https://api-sandbox.picpay.com. Switch off for production. Maps to UseSandbox.
From PicPay → Configurações → API → Link de Pagamento. Maps to ClientId.
Never stored in plain text. Maps to ClientSecret — re-saving requires re-entering.
Connected to PicPay (sandbox) · Token TTL 60 min
Checkout options
What buyers see on the storefront
Use PicPay Link de Pagamento
Master kill-switch for the new API. When off, PicPay is not registered as a payment method even if Show in checkout is on. Maps to EnablePaymentLink.
At least one method must remain enabled. Maps to EnabledMethods (CSV).
%
Applied to the order total when the buyer selects Pix. Shown as a badge on the storefront radio. Maps to PixDiscountPercentage.
%
Maps to BoletoDiscountPercentage.
min
5 – 1440 minutes. Recommended 30 – 60 min. After expiry the buyer must restart the order. Maps to PaymentLinkExpiryMinutes.
Auto-generated from the store URL. Paste into PicPay portal → Configurações → Webhooks. Computed at runtime — never stored.
Used to validate X-PicPay-Signature (HMAC-SHA256). Regenerating invalidates the existing secret — you must paste the new value into the PicPay portal. Maps to WebhookSecret.
Signature OK · 200 from /Webhook · 142 ms
POSTs a synthetic payment.paid event to the URL above using the current secret, then echoes the response.
Internal notes
Visible only in admin
Never shown on the storefront. Maps to AdditionalConfigurationNotes.
Show in checkout toggle → ConfigurationModel.ShowInCheckout.
Sandbox toggle → UseSandbox. Environment badge re-renders based on toggle state.
Client ID → ClientId (new field). Validated as non-empty before Test connection.
Client Secret → ClientSecret (new field, replaces SecretKey). Rendered type="password", never echoed back after save.
Test connection button → new controller action PaymentPicPay/TestConnection. Calls the OAuth endpoint with current credentials, returns { ok, message, tokenTtlSeconds }.
Payment Link API toggle → EnablePaymentLink (new). Kill-switch independent of Show in checkout.
Enabled methods checkboxes → EnabledMethods (CSV). Server-side validation: at least one must be set.
Pix / Boleto discount → PixDiscountPercentage, BoletoDiscountPercentage (retained). Range 0 – 100 with two decimals.
Link expiry → PaymentLinkExpiryMinutes (new). Range 5 – 1440.
Webhook URL — computed at runtime as {storeUrl}/Plugins/PaymentPicPay/Webhook. Not persisted.
Webhook secret → WebhookSecret (retained). Regenerate writes a new random 32-byte value, base64-encoded.
Test webhook button → new controller action PaymentPicPay/TestWebhook. POSTs a synthetic event, surfaces upstream status + signature validation result.
Removed fields — MerchantId, PublicKey, SecretKey, EnableThreeDsWhenSupported are dropped from PicPayPaymentSettings via a migration in InstallAsync.
Override checkboxes — each field gets a standard nopCommerce nop-override-store-checkbox. The Configure for dropdown at the top selects scope (All / specific store).