Integration → WordPress & WooCommerce

WordPress & WooCommerce

The official Vittas Payments plugin adds bank transfer checkout to WordPress — as a WooCommerce payment gateway, or as a [vittas_pay] button on any page. You never write the session-creation code: the plugin calls the Vittas API from your server and hands the widget the resulting client secret.

Download latest release Source on GitHub

Requirements

Component	Minimum	Notes
WordPress	`6.0`	WooCommerce itself now requires 6.9+, so a WooCommerce store needs the higher floor.
PHP	`7.4`	Tested on 7.4 and 8.2.
WooCommerce	`7.0`	Only needed for store checkout. The shortcode works without it.
Store currency	`NGN`	The gateway hides itself on stores using any other currency.

Install the plugin

Download vittas-payments-<version>.zip from the latest release.
In WordPress, go to Plugins → Add New → Upload Plugin and upload the zip.
Click Activate.

Updates arrive automatically

Once installed, the plugin watches the repository's releases and shows Update available on your Plugins screen, exactly like a WordPress.org plugin. Security fixes reach your store without you tracking releases.

Connect it to Vittas

Open Vittas Payments in the WordPress admin menu. Two values must be registered in your Vittas dashboard as well — the settings screen shows both, ready to copy.

1. Choose a mode and paste your secret key

Pick Test or Live, then paste the matching secret key (sk_test_… or sk_live_…). Press Test connection to confirm Vittas accepts it.

Your public key is not needed

The plugin creates every payment session server-to-server with the secret key. The browser only ever receives the short-lived cs_… client secret that comes back, so there is nothing for a public key to do.

2. Allow your site's origin

In your Vittas widget settings, add your site origin (for example https://yourstore.com) to Allowed origins. The widget refuses to open on a page whose origin is not listed, and the settings screen prints the exact string to copy.

3. Register the webhook

Add this URL under Developers → Webhooks in your Vittas dashboard, then copy the signing secret it returns back into the plugin's webhook secret field:

bash

https://yourstore.com/wp-json/vittas/v1/webhook

Webhooks are what actually settle orders

The plugin also re-verifies server-side when the shopper returns, so a site without a public URL still works during development. But a shopper who closes the tab mid-payment is only settled by the webhook — do not skip this step in production.

WooCommerce checkout

Go to WooCommerce → Settings → Payments and enable Bank Transfer (Vittas). You can change the title and description shoppers see; the keys stay on the shared Vittas Payments screen so the shortcode can use them too.

That is the whole setup. At checkout the flow is:

Shopper picks Bank Transfer (Vittas) and places the order.
The plugin creates a session from your server and sends the shopper to the order-pay page.
The widget opens with a virtual account number and a countdown.
The shopper transfers; Vittas confirms and the order moves to Processing.

Works on classic and block checkout

Both checkout experiences are supported. The Checkout block reads a registry separate from the classic gateway list, and the plugin registers with both.

How a payment is confirmed

Two independent paths race, and both are safe to run twice. The webhook is authoritative. The browser return is only there for instant feedback — it triggers a fresh server-side read of the session with your secret key, and nothing about the outcome is taken from the shopper's browser.

If a payment arrives that does not cover the order total, the order is put on hold with an explanatory note rather than completed, so nothing ships on an underpayment.

Pay buttons on any page

For donations, deposits or one-off payments, drop the [vittas_pay] shortcode into any post or page. WooCommerce is not required. A Vittas Pay Button block is also available in the editor.

Fixed amount

html

[vittas_pay amount="2500" label="Donate ₦2,500" reference="DONATION"]

Payer chooses the amount

html

[vittas_pay amount="0" min="500" max="500000" label="Donate"]

Attributes

Attribute	Default	Description
`amount`	`0`	Amount in naira, not kobo. `0` lets the payer enter their own.
`currency`	`NGN`	ISO 4217 currency code.
`label`	`Pay now`	Button text.
`description`	—	Copy shown above the button.
`reference`	`WP`	Prefix for the generated payment reference.
`redirect`	—	URL to send the payer to after a confirmed payment.
`min` / `max`	`100` / —	Bounds in naira, used only when `amount` is `0`.

The amount cannot be tampered with

The session endpoint has to be callable by logged-out visitors, so the plugin signs the amount into the button and re-derives it on the server. A modified request is rejected rather than charged.

Hooks for custom fulfilment

Sites without WooCommerce — or with custom fulfilment — can hook the plugin instead of polling the API.

Hook	Fires when
`vittas_webhook_received`	Every verified webhook, before order handling. Use this to fulfil on non-WooCommerce sites.
`vittas_shortcode_payment`	A shortcode payment is confirmed server-side.
`vittas_order_paid`	A WooCommerce order is marked paid.
`vittas_order_mismatch`	A wrong-amount payment puts an order on hold.
`vittas_order_reference`	Filter — change the reference sent to Vittas.
`vittas_order_metadata`	Filter — change the metadata echoed back in webhooks.

functions.php

php

<?php
// Fulfil a donation made with [vittas_pay] on a site without WooCommerce.
add_action( 'vittas_shortcode_payment', function ( $session ) {
    // $session: sessionId, status, reference, amount, paidAmount, currency
    if ( 'successful' !== $session['status'] ) {
        return;
    }

    my_record_donation( $session['reference'], $session['amount'] );
} );

// Every verified webhook, including ones with no matching order.
add_action( 'vittas_webhook_received', function ( $event, $data ) {
    error_log( 'Vittas ' . $event . ' for ' . $data['reference'] );
}, 10, 2 );

Troubleshooting

Symptom	Cause and fix
Widget never opens; console shows not authorised	Your site origin is missing from Allowed origins in the Vittas dashboard. Copy the exact value shown on the plugin settings screen.
Bank Transfer (Vittas) missing at checkout	Either the store currency is not NGN, no secret key is set for the selected mode, or the gateway is disabled under WooCommerce → Settings → Payments.
Orders stay Pending after payment	The webhook is not reaching your site. Confirm the URL is registered, the signing secret matches, and that the site is publicly reachable over HTTPS.
Order went On hold instead of Processing	Vittas reported an amount that did not cover the order total. The order note records both figures — review before fulfilling.
Invalid client secret	The key and the mode disagree — a `sk_test_` key in Live mode, or the reverse. Use Test connection to check.

Turn on Debug logging on the settings screen to record every API call and webhook. Entries appear under WooCommerce → Status → Logs with source vittas, or in the PHP error log on sites without WooCommerce. Keys are masked before they are written.

Limits

NGN only. The gateway hides itself on stores using any other currency.
No automatic refunds. Refund from the Vittas dashboard and record it manually in WooCommerce.
One merchant account can serve several sites. Every session carries its originating site URL, and a webhook meant for one site will not alter orders on another.

Try it before you install

The repository ships a example/ folder with a Docker Compose store — WordPress, WooCommerce, a seeded product and a donation page — so you can exercise the whole flow end to end before touching your live site.