Integrating Yappy and Panama payments with Laravel and WordPress

Integrating Yappy in a Panamanian merchant involves more than adding a payment button. You need a clear flow, server-signed amounts, states that survive user interruptions, and a backend that can explain why an order was paid or not.

This article describes the backend-first pattern with Laravel and, when the front end is WordPress or WooCommerce, keeps the CMS as the storefront and checkout UI while moving sensitive logic out of the theme. It applies to integrations with Yappy, BAC Credomatic, Paguelo Fácil, and unified gateways.

What Yappy looks like in practice

Yappy (Banco General) is a widely used payment method in Panama. In typical commercial integrations:

1. Merchant onboarding and credentials (merchantId / secret) in the commercial portal.
2. Generation of a payment URL or payment intent from the server.
3. The user completes payment in the Yappy flow (app / redirect).
4. The system receives the result via redirect + endpoint notification and updates the order.

Golden rule: payment starts in the backend

Before showing the button on the front end, the server must:

1. Create or retrieve the order with items, currency, and taxes.
2. Calculate the total on the server (never trust the browser JSON).
3. Save a payment record in pending state with an internal order_id.
4. Request the payment URL / token from Yappy with those figures.
5. Redirect or return to the front end only what is needed to continue.

WordPress / WooCommerce without polluting the theme

On WordPress sites with Elementor, custom themes, or WooCommerce, secrets must not live in functions.php or page builder snippets.

Recommended pattern:

• WooCommerce creates the local order.
• A thin endpoint or plugin calls the Laravel API (gateway).
• Laravel talks to Yappy / BAC / Paguelo Fácil.
• WordPress reflects the state when the backend confirms.

Laravel implementation

1. Order + Payment models with normalized states.
2. PaymentGateway service with adapters behind an interface.
3. Protected endpoint to start payment: validates cart, calculates total, persists pending.
4. Callback/IPN endpoint: verifies signature, is idempotent, dispatches reconciliation job.
5. Return page that queries DB state; does not mark paid from query string.
6. Queue for retries when the bank notifies late.
7. Secrets only in host env (Coolify: service variables, not .env in Git).

Normalized states

Technical checklist

1. Credentials only in environment variables.
2. Sandbox vs production separated.
3. Idempotency: the same order_id does not create two charges.
4. Persist payload for auditing.
5. Validate what the provider sends back.
6. Jobs for reconciliation retries.
7. Logs without secrets or card data.
8. Result page that queries the backend.
9. Healthcheck and workers alive on deploy.
10. Runbook for secret rotation and IPN reprocessing.

Common production mistakes

• Confirming a sale only because the user reached /pago-exitoso.
• Leaving the secret in a WordPress plugin versioned in Git.
• Mixing Yappy, BAC, and Paguelo Fácil logic in one giant if.
• Forgetting the "user paid and closed the app" case without a callback.
• Deploying with latest and secrets baked into the Docker image.

This integration connects with Docker, CI/CD, and Coolify, security auditing, and online payments .