Online payment: WooCommerce plugin

Accept Yavin online payments in a WordPress store without writing code. The Yavin WooCommerce plugin adds Yavin as a payment method at checkout, sends the customer to the Yavin-hosted payment page, and updates the WooCommerce order once the Yavin API confirms the payment.

At a glance

Before you start

• A Yavin account with online payment enabled. Contact partnerships@yavin.com to get one, as well as a sandbox account
• Your API key for each environment, available on my.yavin.com (sandbox: my.sandbox.yavin.com) in the API tab
• Administrator access to your WordPress back office
• A store reachable from the internet over HTTPS. Yavin must be able to send an unauthenticated POST to https://your-store.example/wp-json/yavin/v1/webhook/, and your server must be able to call api.yavin.com
• WordPress permalinks set to anything other than Plain (Settings → Permalinks), otherwise /wp-json/ does not answer

How it works

The order is created in WooCommerce with the Pending payment status before the customer leaves your store. Yavin webhooks are not signed, so the plugin never trusts their content: it only reads the cart_id, checks that it belongs to the order, then asks the Yavin API for the payment status, amount and transaction. The redirect that brings the customer back never changes the order status.

Installation

1. Download yavin-woocommerce-gateway.zip, the latest release. All versions and their changes are listed on the releases page
2. In WordPress, go to Plugins → Add New Plugin → Upload Plugin, and upload the zip
3. Activate Yavin WooCommerce Gateway in the Plugins list
4. Go to WooCommerce → Settings → Payments and open Yavin

If WooCommerce is not active, the plugin shows an error notice in the back office and does nothing else.

To update, upload the new zip the same way and choose Replace current with uploaded. Your settings are kept.

Configuration

Only administrators see the environment, API key, API URL, debug and refund settings. A shop manager can only change the title, description and logos.

What the plugin sends

For each payment attempt, the plugin creates one payment link with:

• amount: the order total, in cents, and currency: the store currency
• items: one line per order item, with its name, quantity and total in cents
• reference and order_number: the WooCommerce order number, so you can find the order from the Yavin back office
• customer: billing first name, last name, email, phone, address, city and postcode
• cart_id: 16 random hexadecimal characters followed by the WooCommerce order ID, for example 9f86d081884c7d65-1234. Each new attempt on the same order gets a new cart_id
• webhook_url: your store's /wp-json/yavin/v1/webhook/ endpoint
• return_url_success: the order confirmation page, and return_url_cancelled: the checkout page

Order lifecycle

Once paid, the order follows the standard WooCommerce flow: Processing for physical products, Completed for virtual and downloadable products.

Refunds

Since version 1.3.0, you can refund a Yavin payment from the WooCommerce order with the standard Refund button. Turn on Refunds in the settings first, and choose which roles may refund.

• One refund per payment. A second refund is only possible if the first one was rejected
• Partial refunds are possible, after a second confirmation
• Only orders paid with version 1.2.0 or later. Refund older orders from my.yavin.com

Refunds are processed asynchronously. The order note says whether the refund is pending, or waiting for approval in my.yavin.com. WooCommerce sends its "order refunded" email as soon as you request the refund. If Yavin rejects the refund, the order is put On hold and the administrator is notified. The WooCommerce refund is not reversed: handle it manually. A daily check flags refunds still pending after 15 days.

Test in sandbox

1. Set API Environment to Sandbox, with your sandbox key and https://api.sandbox.yavin.com
2. Place an order on your store and choose Yavin
3. On the sandbox payment page, click Pay: no card is needed, the payment is validated immediately
4. Check that the order is paid and that its notes contain the Yavin transaction ID

To go live, switch API Environment to Live with your live key and https://api.yavin.com.

Troubleshooting

• The order stays in Pending payment after a successful payment: the webhook did not reach your store, or your store could not reach the Yavin API. Check that:
  • https://your-store.example/wp-json/yavin/v1/webhook/ accepts unauthenticated POST requests from the internet. Security plugins, firewalls, bot protection, a password-protected staging site or a disabled REST API all block it
  • Permalinks are not set to Plain
  • Your server can call api.yavin.com
• Yavin does not appear at checkout: your checkout page uses the Checkout block. Switch it to the [woocommerce_checkout] shortcode
• "Payment failed. Please try again." at checkout: the payment link could not be created. Check the API key and API URL of the selected environment
• Caching: exclude /wp-json/yavin/* and return URLs containing cartId from your page cache
• Logs: go to WooCommerce → Status → Logs and pick the yavin source. Errors are always logged. Turn on Debug log for more detail. Logs contain order IDs, cart IDs, statuses and transaction IDs, never customer details or API keys

For anything else, contact technical_support@yavin.com with your order number and the matching log entries.