Download the PHP package ivo-wmg/borica without Composer

Borica

Borica APGW (EMV 3DS) card payments for PHP and Laravel — and, more usefully, a written record of the failures the specification does not warn about.

Two production integrations reached the same conclusions independently, one a shop on pre-authorization, one a subscription service on tokenized recurring payments. The protocol layer here is tested byte-for-byte against the worked examples in Appendix 1 of P-OM-41 v5.0.

The repository holds three things:

Install

Laravel discovers the provider. Publish the config and the log table:

Keys belong outside the repository and outside the web root. The public key is Borica's, used to verify their callbacks; the private key is yours, used to sign your requests.

The part worth reading

P_SIGN is RSA-SHA256 over a string where each field is its byte length followed by its value, and an empty field is a bare -:

That final - is the RFU slot. On a merchant-initiated transaction it holds MERCH_TOKEN_ID instead, length-prefixed. Signing an MIT with the bare dash that works everywhere else returns RC -17 — "terminal denied access" — which reads as a certificate problem and is not one.

Usage

A one-off payment

$fields is an array to POST to the gateway from an auto-submitting form. The browser goes to the bank; your callback hears the result.

The callback

Verify, dispatch, redirect. Nothing else belongs here — see below.

Telling the customer what happened

Keep them apart. Nobody buying groceries can act on "error in the RRN field", and a shop that shows the technical text to a customer whose bank is still deciding tells them they were refused — so they pay somewhere else while the authorization lands.

Completing and reversing a pre-authorization

Recurring payments

Rules the package cannot enforce for you

1. Verify every callback, and fail closed. A missing public key is an error, never a skipped check.
2. A valid signature proves the sender, not the amount. Compare AMOUNT and CURRENCY to what you asked for.
3. Return from the callback immediately. Do the work in a queued job. Anything slow here times out and Borica retries, giving you the payment twice.
4. Never cancel on an in-progress code. -31, -33, -40 mean the customer is still at their bank.
5. Never downgrade a successful authorization. Late duplicate declines arrive.
6. Make every write idempotent. Callbacks repeat.
7. ORDER is six digits. Plan the reverse lookup before you need it.
8. Never log the POST body. It can carry a PAN.

skill/reference/traps.md explains what each of these costs when ignored.

The skill

skill/ is a Claude Code skill holding the same knowledge in a form an AI assistant will pick up on its own when it sees Borica work.

Use it in one project:

Use it everywhere:

The assistant loads it by its description when a task mentions Borica, APGW, P_SIGN, MAC_GENERAL, TRTYPE or MERCH_TOKEN_ID. Nothing needs invoking by hand.

With another tool. The files are plain Markdown with no Claude-specific syntax beyond the frontmatter. Point any assistant that reads files at skill/SKILL.md and it will work — for Cursor, .cursorrules; for Copilot, .github/copilot-instructions.md; otherwise paste skill/reference/traps.md into the conversation before starting.

What it contains

Testing

The signature tests reproduce both Appendix 1 examples byte for byte. If you change SignatureBuilder, those must still pass — they are the only check on this string that does not need a live terminal.

Going live

The dev gateway is open and useful. Production needs a different host, a different terminal id, and different keys. The certificate comes from B-Trust separately from the terminal credentials, and neither works without the other. On both integrations behind this package, waiting for those was longer than writing the code.

Licence

MIT. Not affiliated with or endorsed by Borica AD. Field definitions belong to their specification; what is here is the experience of implementing against it.