WooCommerce ships with a handful of payment methods: cards (via Stripe, PayPal, WooPayments), bank transfer, cheque, and cash on delivery. If you need anything else — invoice terms, a purchase-order checkout, a hosted payment link, crypto instructions, or cash on pickup — WooCommerce expects you to build a payment gateway in PHP.
That is more work than most store owners want. A custom gateway class, checkout fields, order status handling, and block-checkout support are a developer project, not a settings-page task.
You do not need that. WooCommerce Custom Payment Gateway Pro lets you add one or more custom payment methods from the WordPress admin. You choose a template (or start from scratch), write the checkout copy, add fields, and decide who sees the method. No PHP, no child theme, no custom plugin.
This guide walks through the full setup: create the gateway, configure checkout, test it as an administrator, then turn it on for customers.
What “custom payment gateway” means here
A custom gateway in this plugin is a checkout payment method you control, for payments that happen outside a card processor.
Typical uses:
- Pay by invoice (order now, settle later)
- Bank or wire transfer with your account details
- Purchase orders with a PO number at checkout
- Manual payment links (Wise, PayPal.me, Stripe Payment Links)
- Cash on pickup / pay in store
- Crypto transfers you confirm by hand
The plugin does not charge cards, store card numbers, or replace Stripe or PayPal. Do not add fields for full card data or CVV. Use a PCI-compliant gateway for cards, and use this plugin for the methods those processors cannot cover.
What you can do without code:
- Show a titled method at checkout (classic and block checkout)
- Display instructions, account details, payment links, or QR codes
- Collect extra fields (text, email, file upload, signature, and more)
- Set the order to On hold, Pending payment, or another status
- Limit who sees the method (role, country, cart total, products, and so on)
- Optionally POST order data to an external API after checkout
Before you start
You will need:
- A WooCommerce store with WooCommerce Custom Payment Gateway Pro installed and licensed
- A clear process for what happens after the customer places the order (who reviews it, how they pay, when you fulfil)
- (Optional) any bank details, payment link, pickup address, or invoice terms you want to show at checkout
Write the process down first. The settings are easier when you already know the title customers should see, the message at checkout, and the fields your team actually uses.
Step 1: Create the gateway
- In WordPress, go to WooCommerce → Settings → Custom Payment Gateways.
- Under Create gateway, pick a starting point:
| Template | Use it when |
|---|---|
| Start from scratch | Your process does not match a template, or you want every field empty |
| Bank Transfer / Wire Transfer | Customers pay to your bank account |
| Pay by Invoice | B2B customers order now and pay later |
| Manual Payment Link | You show a hosted link (Wise, PayPal.me, Stripe Payment Links) at checkout |
| Cash on Pickup / Local Payment | Customers pay when they collect the order |
| Crypto Manual Payment | Customers send crypto; you confirm the transaction |
- Enter a name such as
Bank TransferorPurchase Order. This is an admin label; you can still change the customer-facing title later. - Create the gateway, then click Configure (or go to WooCommerce → Settings → Payments and click Manage).
Templates pre-fill a title, checkout message, order status, payment details, and a starter form. Start from scratch gives you a blank method you fill in yourself. Either way, every setting below is editable.
The rest of this guide uses a from-scratch gateway so you see every decision. If you picked a template, skip anything already filled in and adjust the copy to match your store.
Step 2: Enable the method and keep it admin-only while you test
On the gateway settings page:
- Check Enable Custom Payment.
- Check Enable Debug Mode.
Debug mode is the safe way to build a gateway. While it is on, only administrators see the method at checkout. Customers still see your usual card and PayPal options.
Leave debug mode on until you have placed a test order and checked fields, emails, and order status.
Step 3: Set the title, icon, and checkout message
These are the first things customers read.
Method Title — the label next to the other payment methods. Use something they will recognize:
Bank TransferPay by InvoicePurchase OrderPay in StoreRequest a Payment Link
Avoid internal names such as CPG-2 or Custom Gateway.
Gateway Icon (optional) — a full URL to a small image (invoice icon, bank logo, and so on). Leave it blank if you do not want an icon.
Customer Message — shown when the method is selected, above payment details and fields. Explain what happens before they place the order.
Example for a from-scratch purchase-order method:
Place your order with a purchase order. We will review the order and send payment instructions. Your order will not be fulfilled until payment is confirmed.Example for bank transfer:
Pay by bank transfer. Use your order number as the payment reference. We will process the order after the payment has been received.Keep it to a few sentences. Details such as IBAN, Net 30 terms, or a pickup address belong in payment details (templates) or an Instructions field (from scratch), not in this short message.
Step 4: Choose the order status after checkout
Set Order Status After The Checkout to match when money actually arrives.
| Status | Typical use |
|---|---|
| On hold | Invoice, bank transfer, PO, or any method you review before payment |
| Pending payment | Waiting on the customer to pay; you are not reviewing first |
| Processing | Payment is treated as in progress (common for cash on pickup) |
| Completed | Only if you treat checkout as fully paid — rarely right for manual methods |
For most custom gateways, On hold is the right default. The order is in WooCommerce, stock can be held, and nothing is marked paid until you confirm it.
Avoid Completed unless payment is genuinely finished at checkout. WooCommerce will treat the sale as done before you have the money.
Step 5: Add payment instructions customers should read
Customers need to know how to pay, not only that a method exists.
If you used a template, fill in the Payment details fields on the same settings page. Those appear at checkout, on the thank-you page, and in emails (when that option is enabled). Examples:
- Bank transfer: bank name, account holder, IBAN, SWIFT/BIC, transfer instructions
- Pay by invoice: invoice instructions, payment terms, accounts email
- Manual payment link: provider name, payment URL (shown as a button), optional QR image
- Cash on pickup: location, hours, contact phone, accepted methods
- Crypto: coin/network, wallet address, optional QR, transfer instructions
If you started from scratch, add an Instructions field in the field builder (next step) for any copy customers should read but not type — bank details, “include your order number on the transfer,” pickup hours, and so on.
Do not put secrets in checkout copy. Account numbers and wallet addresses are meant to be public payment destinations. API keys and admin-only notes are not.
Step 6: Build the checkout form (only the fields you need)
Scroll to Custom Form. The field builder has three panels: a field palette, a checkout preview, and field settings.
Add a field from the palette, select it in the preview to edit the label and help text, then save changes in the builder.
Useful field types:
| Field type | Typical use |
|---|---|
| Text | Company name, PO number, payment reference, transaction hash |
| Textarea | Extra notes |
| Billing or accounts contact | |
| File upload | Receipt, PO PDF, screenshot of a transfer |
| Date / time | Preferred pickup slot |
| Select / radio | Invoice by email vs post, department, cost center |
| Checkbox | Accept payment terms |
| Signature | Sign acceptance of terms |
| Instructions | Read-only copy inside the form |
Keep the form short. Every extra field is a reason to abandon checkout.
Example for a purchase-order gateway:
| Field type | Field label | Required | Help text |
|---|---|---|---|
| Text | Company name | Yes | Your registered company name |
| Text | Purchase order number | Yes | Your internal PO reference |
| Billing contact email | Yes | We will send invoices to this address | |
| File upload | Purchase order PDF | No | Optional. PDF, JPG, or PNG, max 5 MB |
Set Required to Yes only when checkout should fail without that value. Submitted values appear on the order in admin so your team does not have to email the customer for a PO number later.
Do not add password or text fields for card numbers, expiry, or CVV. The plugin’s old credit-card field is deprecated and cannot be added to new gateways.
Step 7: Add a thank-you note
Customer Note is shown after checkout on the thank-you page and as a customer-visible order note. It is different from the checkout Customer Message.
- Customer Message — what the method is, before they place the order
- Customer Note — what happens next, after they place the order
Example:
Thank you for your order. We will review it and email next steps within 1 business day. Quote your order number on all payments and messages.Include a real contact (accounts inbox or store phone) so they are not stuck waiting in silence.
Step 8: Show the gateway only to the right customers (optional)
An enabled gateway appears for everyone unless you add rules. Many custom methods should not.
On the gateway settings page:
- Enable Conditional Display Rules.
- Add one or more conditions. In the current version, all conditions must match.
Common setups:
Wholesale or trade accounts only
- Condition type: User role
- Operator: is
- Value: your wholesale role
Logged-in customers only
- Condition type: Logged-in status
- Operator: is logged in
One country only
- Condition type: Customer country
- Operator: is
- Value: your country
Minimum order value
- Condition type: Cart total
- Operator: greater than
- Value:
500
Specific products or categories
- Condition type: Products or Product categories
- Operator: cart contains
- Value: the products or categories that allow this method
If the rules do not match, the gateway stays hidden. Card and other methods still show as usual.
You can combine rules — for example, logged-in wholesale customers in the United Kingdom with a cart over £500.
Step 9: Place a test order
- Confirm Enable Debug Mode is still on.
- Log in as an administrator.
- Add a product to the cart and go to checkout (classic shortcode or block checkout — the plugin supports both).
- Select your custom method.
Check that:
- The title, message, and payment details appear
- Required fields block checkout when empty
- Optional file uploads accept the file types you configured
- The order is created with the status you chose
- Submitted fields are stored on the order
- The customer note appears on the thank-you page
If you enabled Add payment info to emails under WooCommerce → Settings → Custom Payment Gateways, confirm the submitted fields also appear in the order email.
When everything looks correct, turn Enable Debug Mode off and save. The method is then available to customers who match your rules (or to everyone, if you did not add rules).
Optional: send the order to another system
If you already create invoices, tickets, or payments in another tool, you do not have to copy orders by hand.
On the same gateway, open Advanced options and enable API requests. You can POST the order ID, total, billing email, and custom field values to an endpoint after checkout, or redirect the customer to an external URL.
Use Send Test Request and the API Logs on that settings page before you rely on it in production. The plugin is the checkout and data handoff; your other system still does the invoicing or payment collection.
For field mapping and headers, see the plugin’s API requests documentation.
After the order: keep a simple workflow
The gateway gets the order into WooCommerce in the right state. Your team still needs a process after that:
- Open the new On hold (or Pending payment) order.
- Read the submitted fields and any uploaded files.
- Send the invoice, confirm the transfer, email the payment link, or prepare the pickup — whatever you promised at checkout.
- When payment is confirmed, mark the order Processing or Completed and fulfil as usual.
If the order should not go ahead (failed credit check, missing PO, wrong entity), leave it on hold or cancel it and email the contact from the form. The checkout method does not replace that judgement; it stops the sale from falling out of the store into an email thread.
Custom gateway vs WooCommerce’s built-in methods
WooCommerce Direct bank transfer, Check payments, and Cash on delivery are fine when you only need a title and a block of instructions.
Create a custom gateway instead when you need any of the following:
- Extra checkout fields (PO number, tax ID, receipt upload, signature)
- Different copy, icons, or order status per method
- More than one offline method (invoice and bank transfer and pickup)
- Visibility limited by role, country, cart total, or products
- A handoff to an invoicing or operations API
You can run both. Many stores keep Stripe or WooPayments for retail cards, bank transfer for one-off wires, and a custom invoice or PO method for approved accounts.
Frequently asked questions
Do I need a developer to add a custom payment method?
Not with this plugin. You create and configure gateways in WooCommerce → Settings. You only need a developer if you want behaviour the plugin does not offer (for example, a fully custom card processor).
Does this charge the customer at checkout?
No. The customer places the order. You collect payment afterwards using the process you described. The plugin does not process cards.
Can I create more than one custom gateway?
Yes. Create as many as you need from templates or from scratch. Each has its own title, fields, rules, and API settings.
Will this work with the WooCommerce block checkout?
Yes. Test on whichever checkout your theme uses (classic shortcode or blocks) before you turn off debug mode.
Can I use this together with Stripe or PayPal?
Yes. Custom methods sit alongside your card gateways. Use conditional rules if you only want the custom method for some customers.
What if I already know I want Pay by Invoice?
Use the Pay by Invoice template and follow the dedicated walkthrough: How to add a Pay by Invoice payment method to WooCommerce.
Get a custom payment method on your store
If checkout currently stops at “pay by card,” add a method that matches how your customers actually pay — invoice, bank transfer, purchase order, pickup, or a hosted link — without writing a gateway class.
WooCommerce Custom Payment Gateway Pro includes templates for the common cases, a checkout field builder, admin-only debug mode, conditional display rules, and optional API handoff.
Install the plugin, create a gateway (template or from scratch), test as an administrator, then turn off debug mode when you are ready for customers to use it.
Need help choosing a template or mapping your accounts workflow? Contact WPRuby support.