YooKassa Integration in a PHP Store

YooKassa integration in a PHP store means accepting payments on your domain: card, often fast payments, and other methods enabled in the YooKassa account. The script creates a payment, the buyer goes to the form, your endpoint receives a webhook, and the order status changes. Without a webhook, you live on "probably paid", which is not acceptable.

Cart and checkout: store, payment.

What to take from the YooKassa account

• shopId;
• secret key, different for live and test stores;
• notification settings: webhook URL on your https site;
• understanding which methods are enabled, such as card and fast payments.

Do not commit keys to git or expose them in frontend code. Server only. Run test mode before the first ads.

URLs that must match

1. Return URL: where to send the buyer after payment, such as success/fail store pages.
2. Webhook / notification URL: where YooKassa sends server events.
3. The domain must be https with a non-expired certificate.

Return URL does not make the order paid. The user can close the tab. Status paid is only after notification validation, authenticity checks according to API rules, and amount comparison with the order.

Status idempotency

A webhook can arrive more than once. The handler must:

• find the order by payment_id or metadata;
• compare amount and currency;
• if it is already paid, return success and exit without writing stock off again;
• log the raw event for conflict analysis.

Stock write-off happens once when status changes to paid. Reserving stock before payment is a separate policy; do not mix two models in one item.

Order link in the admin panel

The order card should show:

• internal order number;
• YooKassa payment id;
• payment status;
• amount;
• time when it became paid.

Otherwise morning reconciliation becomes a quest across two dashboards. For partial payments and refunds, design statuses in advance, even if launch starts with full prepayment only.

Typical implementation errors

1. Live keys on a test domain, or test keys in production.
2. Webhook on http or localhost "to be changed later".
3. Creating a payment for the amount before promo discount while the order uses the discounted amount. Promo: here.
4. Delivery not included in the payment amount. Delivery: tariffs.
5. Success page says "paid" before the webhook, creating a false feeling.
6. No canceled processing, so the reserve slot hangs forever.

Minimum test

1. Item qty 1 to checkout to test success: order paid, stock -1.
2. Repeated webhook if possible: stock does not become -2.
3. Cancel/failure: order is not paid, product remains available.
4. Promo -10%: payment amount matches final total.
5. Size variant: correct SKU in the order. Variants.

Ecommerce on your hosting: overview, product: PHP store. YooKassa handles acquiring without a custom cashier; your responsibility is honest statuses, webhook handling, and reconciliation. Configure keys, URLs, and idempotency, and checkout stops being a roulette wheel.

Live launch without drama

Checklist for switching from test to live:

1. Live shopId and key are entered in the store admin panel.
2. YooKassa webhook points to the production https URL.
3. A low-value real payment or refundable transaction is tested.
4. Order became paid and stock was written off once.
5. Buyer email/account does not promise shipment before paid if you require prepayment.

After that, remove test keys from config or keep them only on staging. Test/live confusion is the most common reason for "the client says they paid, but we see nothing".

Refunds and partial payments

At launch, I often forbid partial payment: one order equals one payment for the full amount. Refund is made from the YooKassa account plus store status refunded with manager comment. If the script can initiate refund API, fine, but the button should be admin-only. Automatic refund on order cancellation is dangerous until packing rules are clear.

• Do not delete an order after payment; only change status.
• Store payment_id next to the order permanently.
• Log and alert amount mismatches instead of silently overwriting them.

Weekly reconciliation: paid in the store vs YooKassa turnover. If you find an orphan payment without an order, investigate manually; it can happen when the session breaks after payment creation. Put order_id into payment metadata and do not rely only on session.

Buyer messages about payment

Return URL text should be calm: "if money was charged, status will update within a few minutes; do not pay again". A "pay again" button on the same order must lead to the same or a controlled new payment, not create duplicates without control. Email after paid should include items, amount, and what happens next with delivery. YooKassa integration at this point connects to warehouse operations: do not promise packing before the manager sees the order.

If you use fast payments and cards, test both paths. Different methods can differ in webhook speed. Never consider payment complete by front return. Server callback and idempotency are mandatory, not phase two. Then checkout stops creating night surprises for support.

Test and live environments

Keep staging with test keys and production with live keys. Never copy .env from live to a demo domain "just to check for a minute". YooKassa integration breaks most often through human factors, not API. The deploy checklist should include "which key is currently in config". After changing domain, update webhook URL in the YooKassa account the same day.

Document who has access to the payment account. After an employee leaves, rotate the secret. Rotate webhook logs but do not store full card data; it should not be there at all. payment_id, amount, status, and order_id are enough for reconciliation and disputes. Then acquiring on your domain remains controlled instead of becoming a black box.