GamiPress Purchases - WordPress Plugin

Guide to Setting Up and Using GamiPress Purchases

GamiPress Purchases is built for WordPress sites where an internal system of points, achievements, and ranks needs to work not only as a reward for activity, but also as a paid way to access gamified elements. This guide focuses on the practical side rather than marketing copy: what to prepare before installation, where to define point value, how to display purchase forms, how to verify payments, and what to check if a user does not receive the reward they bought.

The plugin lives inside the GamiPress ecosystem, so it should not be evaluated in isolation from the point types, achievements, ranks, logs, and site pages you already have in place. The most common first-time mistake is trying to place a payment form on a page right away without first validating the point economy and payment statuses. The form may appear, but the price, the purpose of the reward, or the post-payment delivery may still be unclear to both the user and the administrator.

Below is a step-by-step working setup: from preparing a test site and core GamiPress elements to a point purchase form, paid achievement unlocks, Stripe setup, emails, payment history, and troubleshooting. Where the official source only describes configuration, this guide adds safe ways to verify the outcome and practical notes for site owners.

What point, achievement, and rank purchases are actually for

Core GamiPress builds a gamified system around user actions: logging in, publishing posts, commenting, completing courses, making store purchases, participating in the community, and other events can all award points, achievements, or ranks. GamiPress Purchases adds a second path to those same gamified assets: the user can pay for points, access to an achievement, or a rank upgrade through a form on the site.

This does not replace the standard GamiPress requirements. It is better understood as a second reward channel. If students on an educational site earn "Credits" for completing lessons, the administrator may allow them to buy additional credits. If a private community uses ranks for access levels, you can offer a paid upgrade to a specific rank, but only if that approach does not undermine the community's rules. If an achievement is normally unlocked through a chain of actions, paid access should be used carefully: the user needs to understand exactly what they are buying and why it does not devalue the genuine accomplishments of other members.

The product is especially useful when gamified elements already carry clear value inside the project. Points rarely sell well on their own. They become meaningful when tied to access to content, bonuses, status, internal currency, community level, or a faster path through part of the user journey. That is why GamiPress Purchases should be set up starting not with the payment method, but with one question: what practical outcome will the user get after paying.

The key difference from WooCommerce-based setups is that GamiPress Purchases revolves around GamiPress elements rather than a standard product cart. If your goal is to let customers pay for WooCommerce products with points, that is a different class of solution. If the goal is to let a user buy the points themselves, an achievement, or a rank, then this product is a closer fit.

Where the plugin makes sense

A good use case for GamiPress Purchases starts where the gamified economy is clear and limited. For example, the project may have one point type, several achievements with clear descriptions, and one rank that unlocks an extra section. The user understands why the points matter, and the site owner can verify every payment in the payment history.

• Educational portal. Points can work as an accelerator for access to bonus assignments, extra quizzes, or symbolic rewards, as long as they do not replace required learning.
• Community site. A paid rank can work as voluntary project support or a way to unlock expanded profile features, provided the community rules are transparent.
• Membership site. An achievement can serve not as a "medal for merit," but as an access marker for a club program, participation in a private challenge, or a bundle of perks.
• Content-driven project. Points can be sold as an internal unit for unlocking materials if the access restriction is handled by another confirmed GamiPress mechanism.

When a different approach is better

The plugin may be unnecessary if the site does not yet have a well-designed GamiPress system. Selling points without a clear purpose quickly turns into a confusing payment form. It also should not be used as a substitute for a full subscription system, a product store, legally complex payments, or shipping calculations. Those use cases are usually better handled by a dedicated commerce platform, with GamiPress kept as the rewards and motivation layer.

Quick decision check: if you cannot explain in one sentence what the user gets after paying and where they will see it, the purchase form is not ready for a public page yet.

What to prepare before installing it on WordPress

Preparation matters for more than process. GamiPress Purchases relies on existing point types, achievements, and ranks. If those are set up chaotically, the payment layer will only amplify the chaos: the user will pay for one thing, the administrator will go looking for another, and the payment log will not give a clear answer about why the reward was not delivered.

Before installation, review your base GamiPress setup. The main GamiPress plugin must already be installed and active on the site, because Purchases is an add-on for it. On WordPress.org, base GamiPress is described as working with points, achievements, and ranks, with support for blocks, shortcodes, widgets, logs, and integrations. Those are the elements that will become the purchasable entities inside GamiPress Purchases.

Minimum product map

Create a short internal map that you could show to an editor, administrator, or client. It should be simpler than a financial plan, but more precise than a general list of ideas.

1. Point type. Its name, purpose, and a practical example of how it is used. For example, "Credits" for access to bonus assignments.
2. Point pricing. How many points correspond to a monetary amount, and why that value does not break the balance.
3. Paid achievements. Which achievements can be purchased, and which should remain rewards for actual actions only.
4. Paid ranks. Which ranks can reasonably be unlocked through payment, and what the user will see after upgrading.
5. Result page. Where the user will check their balance, newly received achievement, current rank, or purchase history.
6. Responsible administrator. Who handles disputed payments, refunds, emails, and manual status changes.

Technical preparation without putting the site at risk

A payment plugin should not go live on a production page with real traffic right away. Prepare a site copy or a private test page. If you do not have a site copy, use a non-public WordPress page restricted to administrators and a test point type with small placeholder values. That lets you test the form, email, payment history, and reward delivery without interfering with real user balances.

Before installation, document your current GamiPress setup: which point types exist, which achievements matter, and which ranks depend on requirements. There is no need to export secrets or connect to the database manually. A clear internal description and a standard site backup through your hosting provider or a typical WordPress backup tool are enough.

Also review the theme and any plugins that affect payment pages: caching, JavaScript optimization, page builders, security plugins, consent forms, and email delivery plugins. Official GamiPress troubleshooting notes that some issues are often caused by outdated software, conflicts with the theme or third-party plugins, and incorrect element configuration. That matters even more for Purchases, because both the payment form and reward delivery depend on several layers working together.

Installation and the first post-activation check

GamiPress Purchases is installed as an add-on to GamiPress. The official pro add-ons instructions describe the standard path: upload the add-on ZIP from your account, go to Plugins > Add New in the WordPress admin, use the plugin upload option, and then click Activate. This guide does not cover buying the add-on itself or any activation workarounds. The practical goal here is different: enable a legitimate plugin file safely and confirm that it appears in the right GamiPress areas.

After activation, do not jump straight into payments. First confirm that the GamiPress menu now includes Purchases-related sections, add-on settings, and the payment history screen. The payment management documentation points to GamiPress > Payment History. If that menu item is missing, check the user role, verify that the main GamiPress plugin is active, and rule out admin caching conflicts.

Initial walkthrough

Do a simple pass through the admin area. It does not require real payments and helps catch installation issues before any user sees the form.

1. Open GamiPress and confirm that your main point types, achievements, and ranks are available for editing.
2. Open GamiPress > Settings and look for the Add-ons tab or section where Purchases and payment method settings are placed.
3. Open GamiPress > Payment History and make sure the screen loads without PHP errors or blank white pages.
4. Create or open a test WordPress page where the purchase shortcode will later be placed.
5. Confirm that the selected user has a regular WordPress account, not just guest access, if your setup requires awarding points to a specific user.

Bottom line: installation is only truly successful when you can see the Purchases settings, view payment history, and connect the future form to a specific point type, achievement, or rank.

What not to enable on day one

Do not connect every payment method at once, do not place multiple forms on a public page, and do not assign prices to every achievement all at once. The first test should stay narrow: one point type, one form, one payment method in test mode or one manual method, and one user. That makes it much easier to identify whether the problem is in point conversion, the form, the payment method, the email, the payment status, or reward delivery.

Point value and paid access to achievements or ranks

The most important setting for point purchases is conversion. The GamiPress Purchases documentation explains that each point type edit screen includes a metabox where you define the monetary value of that point type. Their example is simple: if 100 points equal 1 unit of currency, then buying 1000 points will cost 10 currency units. The specific numbers are not the point. What matters is that conversion is configured separately for each point type and then used by the purchase forms.

That gives you flexibility, but it also requires discipline. A single site may include "Credits," "Coins," and "Experience." If all of them are sold at the same rate, the economy stays easier to understand. If each one has a different value, the page needs to make that distinction clear. Otherwise, pricing feels arbitrary: some points seem cheaper, others more expensive, and the reason is never explained.

How to choose a conversion rate for your first launch

For the initial rollout, choose one easy-to-understand point type and a simple conversion rate. Do not try to make the economy feel "game-like" with dozens of coefficients. In a WordPress project, transparency matters more: the user should immediately understand what they are buying, and the administrator should be able to verify the math quickly.

A practical setup looks like this:

1. Open the point type in GamiPress and find the Purchases metabox used to configure the conversion rate.
2. Set a simple ratio, such as 100 points per one unit of cost, if that fits your site economy.
3. Save the point type and do not change the rate while running a test payment.
4. Display the purchase form on a test page via shortcode and confirm that the total shown by the form matches the expected calculation.
5. Record the chosen conversion rate in an internal note for editors so the price is not changed accidentally later.

If you use multiple point types, add a short explanation next to the forms. For example, "Credits are used for bonus materials" or "Coins are used for cosmetic badges." That is page copy, not a plugin setting, but it reduces user confusion.

Buying an achievement or a rank

The GamiPress Purchases documentation shows that achievement and rank edit screens also gain an access price metabox. An achievement can be displayed with the [gamipress_achievement_purchase] shortcode or the GamiPress: Achievement Purchase Form widget. A rank can be displayed with [gamipress_rank_purchase] or the GamiPress: Rank Purchase Form widget. If the user already has the achievement or is already in a higher rank, the purchase form should not appear.

That behavior needs to be considered in page design. If the user does not see the form, that may be correct state checking rather than an error. For that reason, it helps to place a note near the paid achievement or rank saying something like, "If access is already unlocked, the form will not appear." That keeps support from treating every missing form as a bug.

How not to devalue real achievements

Not every achievement should become a paid item. If an achievement in your project represents a real action, an exam, a community contribution, or a verified skill, selling it can undermine trust in the system. GamiPress Purchases is better suited to access-style achievements, club markers, bonus bundles, or faster progression, not to rewards that are meant to prove merit.

The same principle applies to ranks. If a rank represents experience level, selling it may feel unfair. If it represents an access tier, club status, or a decorative profile level, a paid upgrade makes more sense. Before assigning a price, validate what the rank means, not just whether the plugin technically allows a price to be set.

Purchase forms: fixed, custom, and options without confusing the user

For point purchases, the documentation describes the [gamipress_points_purchase] shortcode. It supports multiple form modes through the form_type attribute: a fixed quantity, user-entered values, or a set of predefined choices. This is one of the most product-specific parts of GamiPress Purchases, because the form directly shapes how a person understands the site's internal currency.

Common attributes include points_type, form_type, amount_type, getaways, acceptance, acceptance_text, and button_text. The documentation also makes it clear that the selected point type must already have a conversion rate configured. Without that, the form cannot calculate the cost correctly.

When to use fixed

fixed works best for a single package. For example, "1000 credits for a bonus course." The user cannot change the amount or choose among options, so the form stays simpler and support can reconcile payments more easily. This mode is especially good for a first launch because it reduces the number of variables.

[gamipress_points_purchase points_type="credits" form_type="fixed" amount_type="points" amount="1000" button_text="Purchase"]

If your WordPress editor includes a visual block or field for shortcodes, insert the line there. If you use a page builder, choose a standard shortcode block or HTML snippet block, but do not place the code directly into the theme file. After saving, open the page as a test user and confirm that the form shows a clear point amount and the expected total.

When to use custom

custom lets the user enter the desired number of points or a monetary amount if amount_type is set to money. The documentation notes that the total updates without reloading the page when the value changes. That is convenient for an experienced audience, but it is riskier for a first launch: users may enter values that are too small or too large if the page does not explain the boundaries clearly.

Use this mode only where the user already understands the site's economy. For example, in the account area of a returning member rather than on the first public product page they see.

When to use options

options displays a set of predefined choices. In many cases, this is the best mode for a public page: the user picks from ready-made packages while you stay in control of the economy. The documentation shows that you can pass a list of values through options and allow user entry through allow_user_input.

[gamipress_points_purchase points_type="credits" form_type="options" amount_type="points" options="100,500,1000" allow_user_input="no" button_text="Purchase"]

For a commercial page, it is often better to disable free-form entry and keep three clear package options. If you need more options, check the mobile version of the page first: a long form with tiny option selectors tends to convert worse and leads to more selection errors.

How to place the form on a page without creating extra friction

The purchase form should sit next to an explanation of the outcome. A separate page that shows only a form and no context is a poor choice. A better layout is a compact block explaining what the user is buying, how much they get, where they will see the result, and what to do if something goes wrong. If this is a rank purchase, the rank benefits should be listed nearby. If it is an achievement purchase, the page should explain why that achievement can be purchased.

Do not place several different purchase forms on the same page without clear visual separation. If you need points, an achievement, and a rank, it is better to separate them into page builder tabs or distinct content blocks with different headings. This guide can explain the principle, but on a live site the page itself should stay calm and easy to understand.

Payment methods and statuses: what happens after the form is submitted

GamiPress Purchases supports multiple payment methods, including manual bank transfer, PayPal Standard, and Stripe. In the payment method settings, the documentation points to GamiPress > Settings > Add-ons, and for Stripe it separately describes the key fields, test mode, and webhook URL. This is not just a matter of "connecting payments." Reward delivery depends on payment status: points, an achievement, or a rank should be granted when the payment reaches the completed state, and revoked if the payment is refunded.

If you use Stripe, the documentation recommends configuring a webhook and selecting the events charge.failed, charge.refunded, and charge.succeeded. The reason is straightforward: Stripe needs to tell the site whether a payment succeeded, failed, or was refunded. Without that connection, the site may not learn the outcome in time, especially if the user closes the page after paying.

Bank Transfer as a safe starting point and a manual verification path

In the documentation, Bank Transfer is described as a manual method: it does not communicate with the bank automatically, and the administrator manually completes the payment once the transfer is actually received. That is inconvenient for high-volume sales, but it is useful for testing the GamiPress Purchases workflow because every step stays visible: the user creates a payment, the payment waits for confirmation, the administrator changes the status, and the reward is granted.

For a first rollout, you can enable Bank Transfer on a test page and walk through the full path without any external payment service. The key point is easy to miss: if the payment method is manual, the user must get a clear message that access will be granted only after the administrator reviews the payment, not instantly. Otherwise, the delay will be perceived as a malfunction.

Stripe and webhooks

Stripe is more convenient for automated card payments, but it requires discipline. In the settings, you need to enable the gateway in the payment methods section, enter the keys, use Test Mode if needed, copy the webhook URL from GamiPress, and add the endpoint in Stripe. The GamiPress Purchases documentation describes this exact setup because, without the webhook, the site cannot reliably stay in sync with payment and refund statuses.

Do not store keys in notes sent to editors or contractors, and do not place them in public tasks. They are not needed in the article itself. For verification, it is enough to know where they are entered and how to confirm the outcome: a test payment should appear in payment history, receive a status, create a note, and assign the intended GamiPress object.

PayPal Standard and refunds

PayPal Standard is listed in the documentation as a separate payment method, and on the payment actions screen GamiPress Purchases may add gateway-related actions. From an administrator's perspective, the real issue is not the button itself but status verification: if the payment is completed, the reward should be granted; if a refund is processed, the assignment should be revoked through the proper status transition.

For disputed payments, do not edit fields that are controlled by the payment method. The payment management documentation specifically notes that the purchase key and transaction ID are handled by the gateway. Changing them manually only makes it harder later to match the record in GamiPress, the record in the payment service, and the user's email.

Payment history, assignments, and refunds in GamiPress Purchases

The Payment History screen is the administrator's main tool after launch. It shows the payment number, buyer, date, status, payment method, and total. Clicking through opens the payment screen with order details, user data, line items, assignments, notes, and actions. This is the place where it becomes clear why the user did or did not receive what they purchased.

The payment management documentation highlights an important mechanic: payment items can be linked to an assignment, meaning the point type, achievement, or rank the user will receive when the payment is completed. Those assignments are granted when the payment moves into completed status and revoked when it is refunded. If you add an assignment to a payment that is already completed, it will not be granted automatically. To trigger manual delivery through the status workflow, you first need to move the payment back to pending, save it, then change it to completed and save again.

The "purchase - assignment - reward" flow

To work with GamiPress Purchases correctly, it helps to think of a purchase as three layers. The first layer is the form on the public page. It captures the user's choices: point type, amount, payment method, consent, and submission. The second layer is the payment record in the admin area. It stores the status, user, line items, and the payment method's internal data. The third layer is the GamiPress assignment that grants or revokes the points, achievement, or rank when the correct status transition occurs.

That model explains why a simple check of "the form is there" or "the form is missing" is not enough. The form may be correct, but the gateway may never return a successful status. The payment may be completed, but the line item may not be linked to an assignment. The assignment may be present, but added too late, after the required status transition already happened. That is why troubleshooting should always move from top to bottom: what the user submitted, what record was created, what status that record has, what assignment is attached, and what outcome is visible to the user.

Input: what enters the system

GamiPress Purchases does not receive an abstract "purchase." It receives a specific choice. For points, that means the point type slug, the form mode, and either a quantity or a monetary amount. For an achievement or rank, that means a specific GamiPress object with a defined price. If the wrong slug is used at this stage, the user may pay for something that does not match the page. If the page does not explain the purchased item clearly, even a technically successful payment can still create a support issue.

Product workflow: what the plugin processes

Next, GamiPress Purchases calculates the cost, creates the payment record, sends the user to the selected gateway or shows a manual instruction, and then waits for a status change. The important point is that reward delivery is tied to payment state. Do not manually add points to a user immediately after creating a pending payment if the payment has not actually been confirmed yet. Otherwise, if the payment is canceled or refunded, the payment history and the real balance will no longer match.

Output: where the outcome appears

The outcome should be visible in two places. On the public side of the site, the user should see the updated balance, achievement, rank, or access if access depends on that rank. In the admin area, the administrator should see the payment, its status, line items, notes, and, if needed, a refund or resend-email action. If the outcome is visible only to the administrator, the user will not trust the payment. If it is visible only to the user and the history has no clear record, support will not be able to resolve disputes with confidence.

Failure symptom: how to tell which layer is broken

If the amount is already wrong on the page, check the form and the conversion rate. If the amount is correct but the payment does not complete, check the gateway, webhook, or manual confirmation step. If the payment is completed but the reward does not appear, check the assignment and the status transition. If the reward appears but the email never arrives, check the email templates and WordPress mail delivery. That order is much more effective than changing settings at random.

How to read the payment screen

The details section is usually split between order data and user data. In the order section, look at the status, payment method, IP address, amount, tax, and technical identifiers. In the user section, look at the name, email, and address fields submitted during the purchase. The same user may have different address details across different payments because the record stores the data for that specific transaction.

The payment items show exactly what was purchased. If a line item is linked to an assignment, look for the assignment description. If no assignment is present, it may be a custom line, a fee, or the result of manual editing. For reward-based payments, the critical part is the line item-to-assignment link, not just the final amount.

Payment notes as a troubleshooting log

Payment Notes are used both by GamiPress Purchases itself and by the administrator. Internal entries may show that a payment succeeded, an email was sent, the payment failed, or an action was retried. You can also add your own notes for support, for example, "User inquiry reviewed, bank transfer confirmed." The documentation notes that notes can be added without saving the entire payment each time.

For support, this is far more practical than keeping the history in a separate messenger thread. If a user asks why a rank did not unlock, the administrator checks the status, assignment, and notes. If the payment is still pending, the reward should not have been granted yet. If the status is complete but there is no assignment, the next step is to inspect the payment line item and the original form.

Emails, consent, and user trust

A payment flow is not finished if the user does not receive clear feedback. The GamiPress Purchases email settings documentation points to GamiPress > Settings > Emails, in the Email Templates section. There you can configure email content, disable specific emails, preview them, and send a test email. Each email supports tags that are dynamically replaced with purchase data.

Start by checking two message types: the user receipt and the new sale notification for the administrator, if that notification is enabled in your setup. The user-facing email should explain what was purchased, what the payment status is, and where to verify the outcome. The administrator email should help process the payment, not just announce that "something was purchased."

Consent in the purchase form

The point purchase shortcode supports the acceptance attribute along with acceptance_text. The documentation describes it as a required consent checkbox that matters for compliance around data handling. Do not disable it mechanically just to make the form shorter. It is better to write the consent text in the language of your site and confirm that it does not turn into a long legal paragraph inside a small form.

If your site serves users across multiple jurisdictions, review consent and payment data retention requirements with legal counsel or whoever is responsible for your privacy policy. GamiPress Purchases can provide the technical checkbox and emails, but it does not replace the business's legal configuration.

Checking email delivery

If emails are not arriving, do not start by rewriting the template. First send a test email from the email settings, then check your WordPress mail plugin or SMTP setup. For payment-related messages, it is better to use reliable delivery through SMTP or a transactional email service, because standard hosting mail often lands in spam or gets lost.

Outcome check: after a test purchase, the user should be able to see at least three traces of it: a record in Payment History, an email or successful test send, and a balance, achievement, or rank change when the payment status is completed.

Taxes, currency, and clear pricing

There is one part of the payment flow that is often postponed: how the price is actually shown to the user. In the documentation for payments and Purchases settings, you will see references to amount, total, taxes included, currency, symbol position, and number separators. This is not cosmetic. If the form displays the price in a confusing way, users trust the purchase less, and administrators get more support requests over simple questions.

First, choose a currency that matches both your site and your payment method. Some gateways have their own currency limitations, so do not promise a payment method to users until you confirm it in the selected service's documentation. Then review the format: symbol before or after the amount, thousands separator, decimal separator, and number of decimal places. One format may feel natural for a Russian-language audience, while another is better for an international audience. The most important thing is consistency: the form, the email, and the payment history record should all show the amount the same way.

How to explain pricing without unnecessary legal weight

On a point purchase page, a short block next to the form is enough. There is no need to turn it into a long agreement, but the user should understand three things: how much they get, when the outcome appears, and what happens in the case of manual review or a refund. For a fixed package, that can be explained in one paragraph: "After the payment is completed, 1000 credits are added to your account balance. If bank transfer is selected, the credits are applied after administrator review."

If taxes are used, do not hide that detail until the last step. In GamiPress Purchases, payment history shows the total with taxes included, so it helps to state on the public page whether tax is already included in the final amount or calculated separately by your payment process. Do not include specific tax rules in the guide if they depend on the country, business type, or payment service. Give users a clear pricing structure and verify it with a test payment.

Decision table for initial pricing setup

This table does not replace the documentation, but it helps you choose a safe starting option for a first rollout. After launch, it can be turned into an internal instruction sheet for the site administrator.

How to choose a pricing mode and purchase form

Situation	What to choose	How to verify it
You need to sell one clear point package	A fixed form, one point type, and a simple conversion rate	Compare the form total with a manual calculation and verify the crediting after the status changes to complete
You want the user to choose a package	An options form with 3-4 choices and no free-form input	Test every option, the email, and the record in Payment History
You need a flexible amount for experienced members	A custom form with a note on the page explaining the minimum sensible value	Test extreme values, the mobile version, and the total updating without a page reload
A rank is sold as club access	A price set on the rank edit screen and a separate page explaining the access terms	Verify the rank change, access to the restricted page, and form hiding for users who already qualify

Once you choose a mode, do not change the conversion rate on the same day you enable a new gateway. First verify the economy with a manual or test payment, then enable the external service. If an error appears, you will know only one link in the chain changed.

Administrator roles and operating workflow

GamiPress Purchases adds more than a form on the site. It also creates a new operational responsibility. Someone has to review payments, understand statuses, read notes, resend receipts, handle refunds, and reply to users. If no one owns that role, even a technically correct setup will look unstable: one administrator will change a status manually, another will not understand why, and a third will change the price of an achievement without testing the form.

For a small site, one responsible administrator and a short internal process are usually enough. For an educational portal or a community with multiple editors, it is better to separate responsibilities: editors describe rewards and purchase pages, while payment statuses are changed only by someone who understands the consequences. In WordPress, that is a matter of roles, access to GamiPress, and team discipline, not a separate "magic" Purchases setting.

Mini workflow for a disputed payment

Create an internal five-step process. It is especially useful for Bank Transfer, refunds, and situations where a user says, "I paid, but I did not receive the points."

1. Find the payment in GamiPress > Payment History by user, email, date, or amount.
2. Check the status, payment method, payment items, and assignment.
3. Review the payment notes: was there a failure, an email resend, a manual action, or a gateway message?
4. Verify the external payment service only with the administrator who is authorized to view that data.
5. Apply the fix through the status, a payment action, or the form settings, then add a short note explaining why.

This process reduces the risk of accidentally granting points twice. Be especially careful with refunds. If a payment has actually been refunded but the site still shows it as completed, the user may keep the purchased reward. If the status is changed too early, the user may lose access before the real review is finished.

What to record in payment notes

Payment Notes should not turn into a long correspondence thread, but short technical entries are extremely helpful. A good note answers one question: why did the administrator take this action? For example, "Bank transfer confirmed, status changed to complete" or "Refund confirmed in payment service, status changed to refunded." Do not put secrets, full card numbers, private data, or gateway key fragments in the notes.

If the issue came from a form setting, note that too: "Corrected slug for points_type to credits, test payment repeated." When a similar report comes in a month later, the team will find the cause much faster.

Practical example: a credit package and a paid club rank

Imagine a WordPress learning site. GamiPress is already in place: users earn "Credits" for completing lessons and can use them to unlock extra materials. The owner now wants to add two options: a fixed credit package for purchase and a separate paid club rank called "Club Member." This is a strong fit for GamiPress Purchases because the purchased item is clear and the outcome is easy to verify.

Goal of the setup

The goal is to create a page where a user can buy 1000 credits and a separate block for buying the club rank. After the payment is completed, the credit balance or current rank should change in GamiPress, and the administrator should see a record in payment history.

Preparation

Before configuration, both GamiPress and GamiPress Purchases should already be active. In GamiPress, the point type credits or another real point-type slug must already exist. The rank that may be unlocked through payment must also exist. The test page should have space for the form and a short explanation of the outcome.

Setup steps

1. Open the "Credits" point type and define its conversion rate in the Purchases metabox. For the first test, choose a simple price you can verify manually.
2. Create a test page called "Add Credits" and insert the fixed package form with [gamipress_points_purchase points_type="credits" form_type="fixed" amount_type="points" amount="1000" button_text="Purchase"].
3. Open the club rank for editing and set an access price in the Purchases metabox.
4. On the same page or on a separate rank page, insert the rank purchase form using the documented [gamipress_rank_purchase] shortcode, selecting the attributes through the official shortcode editor or your version's documentation.
5. Enable one payment method for testing. If you only need to validate the status workflow, start with Bank Transfer. If you are testing Stripe, use test mode and a webhook.
6. As a test user, submit the credit purchase form and move the payment all the way to completed status.
7. Check the user's balance, the Payment History screen, the payment notes, and the email.

Expected outcome

After completion, payment history should contain a record with the user, payment method, status, and amount. The payment items should show what was purchased and which GamiPress object it is assigned to. The user should see the updated credit balance or new rank if the payment was completed correctly.

Common pitfall

If you change the assignment on a payment that is already completed, GamiPress Purchases does not have to grant the new reward automatically. The documentation explains delivery through status transitions. That means the sequence matters for manual corrections: change the assignment, move the status back to pending, save, then change it to completed and save again. On a live site, this should only be done after a backup and with a payment note so another administrator can see why it happened.

How to verify the outcome on the public site and in the admin area

Testing GamiPress Purchases has to cover two sides: what the user sees and what the administrator sees. If you only look at the form on the page, you may miss a reward delivery problem. If you only look at payment history, you may miss the fact that the user does not understand the outcome or never receives the email.

User-side verification

Open the purchase page as a regular user. Check the heading, the text next to the form, the selected package, the button, the consent checkbox, and the final amount. After a test payment or manual completion, the user should be able to find the outcome without contacting support.

• The point balance has changed in the block, shortcode, account area, or wherever you display GamiPress points.
• The achievement appears in the user's achievement list if the purchase was for achievement access.
• The rank has changed in the profile or GamiPress block if the purchase was for a rank.
• The purchase form for the achievement or rank is hidden if the user already has the object and your version's documentation describes that behavior.
• The email arrives at the test address, does not land in spam, and clearly explains the outcome.

Administrator verification

In the admin area, open GamiPress > Payment History. Find the test record. Check the status, payment method, amount including taxes, user, payment items, assignment, and notes. If Stripe is in use, also confirm that the test payment appears in Stripe and that the webhook does not show a delivery error.

If Bank Transfer is in use, confirm that the manual payment completion action leaves a clear trace in the notes. That is useful in disputed cases: when a user contacts support, you can reconstruct the chain without reviewing external message threads.

Verification after settings changes

Treat every change to the conversion rate, rank price, shortcode option set, or payment method as its own mini release. Do not change everything at once. First the setting, then the test form, then the test payment, then payment history, then the user-facing outcome. That order only looks slower. In practice, it saves time because the issue is isolated to one changed area.

Safe improvements for the purchase page

With GamiPress Purchases, there is no need to invent unverified hooks or edit plugin files. It is safer to improve the page around the form: create a clear content block, add classes in the WordPress editor or page builder, review the email, and style warnings carefully. That approach does not interfere with the internal payment mechanics and is easy to roll back.

A small CSS enhancement for the form block

If your WordPress editor or page builder allows you to assign a CSS class to a group, wrap the purchase form in a block with the class gp-purchase-offer. Then add CSS through Appearance > Customize > Additional CSS or through a child theme. This snippet does not depend on GamiPress Purchases internal classes: it styles only your container and the standard fields inside it.

.gp-purchase-offer {
  border: 1px solid #d9e2ef;
  border-radius: 8px;
  padding: 24px;
  background: #ffffff;
}

.gp-purchase-offer form {
  display: grid;
  gap: 14px;
}

.gp-purchase-offer input,
.gp-purchase-offer select,
.gp-purchase-offer button {
  max-width: 100%;
}

After adding it, open the page in both desktop and mobile views. Confirm that the form does not overflow its container, the button is easy to read, the consent checkbox does not break the line, and the total amount remains visible. Rolling it back is simple: remove the class from the block or remove the CSS from where you added it.

A practical pairing with access restriction

If a paid rank is supposed to unlock restricted material, do not present that pairing as an official integration unless you have a source confirming it. A safe CMS-level setup looks like this: GamiPress Purchases grants the rank, while another confirmed GamiPress mechanism or a separate access-control plugin checks that rank before showing the content. In that structure, responsibilities stay separate: Purchases handles payment and rank delivery, while the access restriction mechanism controls page access.

The configuration order should be: first create the rank, then configure access to a test page based on that rank, then set the rank price, then run a test payment, then verify access. If access does not open after payment, do not change the payment method immediately. First confirm whether the rank was actually granted. If it was, the issue is most likely in the access restriction layer or page caching. If the rank was not granted, go back to the payment status and assignment.

Troubleshooting common issues

Problems with GamiPress Purchases usually happen at the intersection of the form, conversion rate, payment method, status, and GamiPress object delivery. That is why troubleshooting should follow the chain rather than jumping randomly between settings. Below are practical symptoms that are especially common with this kind of payment add-on.

The point purchase form appears, but the amount looks wrong

Symptom: the user sees the form, chooses a point package, but the final price does not match what the administrator expects.

Possible cause: the selected point type has no conversion rate configured, or the shortcode uses a different points_type. Another possible cause is confusion between amount_type="points" and amount_type="money".

What to check: open the point type, review the conversion rate, then compare the point type slug with the shortcode attribute. After that, confirm that the form is using the intended fixed, custom, or options mode.

How to fix it: save the correct conversion rate, update the shortcode, and repeat the test without page cache. If the form is placed in a page builder, clear both the builder cache and any optimization cache.

The user paid, but the points, achievement, or rank did not appear

Symptom: the payment exists, but the reward is not visible in the profile or balance.

Possible cause: the payment never reached completed status, the payment item has no assignment, the webhook never reported a successful payment, or the administrator changed the assignment only after the payment had already been completed.

What to check: open Payment History, then open the payment screen. Review the status, line items, assignment, and notes. For Stripe, check the webhook. For Bank Transfer, confirm whether the payment was manually marked as paid.

How to fix it: if the payment is still awaiting confirmation, complete it only after the payment is actually verified. If the assignment was added after completion, use the safe status sequence from the documentation: pending, save, complete, save. Add a note explaining why.

The achievement or rank purchase form disappeared

Symptom: the purchase block used to be on the page, but a specific user no longer sees it.

Possible cause: the documentation explains that the achievement form does not appear if the user already has the achievement, and the rank form does not appear if the user is already in a higher rank. That may be correct behavior rather than an error.

What to check: compare the display for a brand-new test user versus a user who already has the achievement or a higher rank. Also confirm that a personalized page is not being cached for all visitors.

How to fix it: add a note to the page explaining that the form is hidden once access is already granted. If caching is the cause, exclude the purchase page and account area from aggressive caching.

A Stripe payment succeeded, but the site status did not update

Symptom: the payment is successful in the external payment dashboard, but in GamiPress Purchases it stays pending or does not update the reward.

Possible cause: the webhook URL was not added, the wrong event set was selected, the endpoint is returning an error, test and live keys were mixed up, or the site is blocking the callback request.

What to check: open the Stripe settings under GamiPress > Settings > Add-ons > Purchases > Stripe and verify the test mode, keys, and webhook URL. In Stripe, check the charge.succeeded, charge.failed, and charge.refunded events.

How to fix it: correct the endpoint, repeat a test payment, and then review the payment notes. Do not manually edit the transaction ID unless you fully understand the consequences.

Emails do not arrive after purchase

Symptom: the payment exists, but the user or administrator does not receive an email.

Possible cause: the email is disabled in the templates, the message was filtered into spam, the site sends mail unreliably, or the template assumes the wrong tags.

What to check: open GamiPress > Settings > Emails, find Email Templates, send a test email, and review the preview.

How to fix it: enable the needed template, configure SMTP or transactional delivery, simplify the message so the outcome is clear, and repeat the test.

The reward stayed with the user after a refund

Symptom: the payment was refunded, but the points, achievement, or rank are still visible.

Possible cause: the payment status never moved to refunded, the refund was processed only in the external service, Bank Transfer was manually reversed without changing the site status, or the webhook never delivered the refund event.

What to check: open the payment record and review the status, actions, payment notes, and assignment. For Bank Transfer, the documentation explains that after a real bank refund you need to change the status from Complete to Refunded so the assigned elements are revoked.

How to fix it: align the status with the actual refund and verify that the assignment has been revoked. If you are unsure, make a backup first and leave an administrative note.

Questions about setting up GamiPress Purchases

Can I start with a single point purchase form?

Yes. That is the safest way to begin. Choose one point type, define a clear conversion rate, and use a fixed form. Once you have successfully verified the balance, the email, and payment history, you can add options or paid ranks.

Why is the achievement purchase form not showing for the user?

If the user already has the achievement, the form may not appear. That behavior is described in the documentation. Test the page with a new test user and make sure cache is not serving a personalized outcome to all visitors.

Do I need to use a Stripe webhook?

For automatic status synchronization, a Stripe webhook is practically essential. The GamiPress Purchases documentation describes the webhook URL along with successful payment, failure, and refund events. Without it, the site may not receive the correct signal about the payment outcome.

Can I edit a completed payment manually?

You can open the payment and review the details, but it is best not to edit technical fields such as the purchase key and transaction ID. If you need to grant an assignment manually, follow the status transitions described in the documentation and leave a payment note.

Is this plugin suitable for subscriptions?

GamiPress Purchases is designed for buying points, achievements, and ranks. If you need a more complex subscription setup with renewals, pricing tiers, access rules, and cancellations, a dedicated membership or commerce tool is a better fit, with GamiPress added as a rewards layer.

How do I confirm that a refund revoked the reward?

Open the payment record, set or verify the refund status so it matches the actual refund, and then check the user's balance, achievement, or rank. The payment notes should show that the action took place. For Stripe, also verify the refund webhook event.

Should I disable caching on the form page?

On pages with personalized forms, user-specific statuses, and payment outcomes, aggressive caching can interfere with correct behavior. At a minimum, exclude the purchase page, the account area, and any pages where the user checks their balance or rank if you notice stale data.

When GamiPress Purchases is the right choice

GamiPress Purchases is a strong fit when your site already has a clear GamiPress system and you want to add a paid channel for obtaining points, achievements, or ranks. Its strength is the direct connection: a point type gets a conversion rate, an achievement or rank gets a price, the form is displayed with a shortcode or widget, and payments are verified through history and status changes.

Before launch, keep your focus on three things: a transparent economy, a payment path you can verify, and a clear outcome for the user. If all three are in place, you can get the GamiPress Purchases file, install it on a test copy of the site, and walk through your first setup using a single point type.

If you do not yet have a well-designed points and ranks system, start with base GamiPress first: create the rewards, configure how they are displayed, review the logs, and only then add payments. The payment layer strengthens a working gamified system, but it does not replace planning it.