Payment gateway modules
A gateway is one PHP class: it says what settings it needs, starts a payment, reads what the provider sends back, and can refund and charge stored methods.
The class#
Every gateway extends CoreInto\Gateways\Gateway. A configured gateway is a row in CoreInto's modules with its settings; fields of the kind secret are encrypted. The class is given those settings, opened, in $this->conf.
| Method | Required | What it does |
|---|---|---|
title() | Yes | The name in the list of gateways |
about() | One line of set-up help shown in the settings | |
fields() | Yes | The settings: key, label, kind (text, secret, bool, textarea, select), help, options, default |
start(Payment $p) | Yes | Starts a payment and returns what to do next |
callback($kind, $query, $post, $body, $headers) | Reads what the provider sent to the return (return) or notification (notify) address | |
notifyReply($what) | The answer the provider wants after a notification, when it is not plain "OK" | |
refund($tx, $amount, $currency) | Sends money back and returns the provider's reference | |
charge($method, Payment $p) | Charges a stored payment method without the client | |
payDirect(Entry $e, Payment $p) | Charges card or bank details typed on CoreInto's own page | |
instructions(Payment $p) | What a manual gateway shows on the invoice | |
region(), kind(), currencies() | Where it works, what clients pay with, which currencies it takes | |
manual(), multiple(), canRefund(), canStore(), form() | What the gateway is and can do | |
enableProblem($conf) | Why it cannot be turned on with these settings |
Starting a payment#
start() receives a Payment: the invoice id and number, the amount in minor units, the currency, a description, the client, and three addresses CoreInto made for this gateway: returnUrl, cancelUrl and notifyUrl. It returns one of:
['redirect' => 'https://provider.example/pay/abc'] // send the client there
['post' => 'https://provider.example/pay', 'fields' => [...]] // an auto-submitted form
['html' => '<p>Transfer the amount to …</p>'] // manual gatewaysReading the answer#
When the provider calls back, CoreInto passes the request to callback(). Check it with the provider (signature, or a call to its API) and return a Result:
return new Result(Result::PAID, invoiceId: $id, amount: $minor, currency: 'USD', transId: $ref, fees: $feeMinor, raw: $payload);Statuses are PAID, PENDING (the provider will confirm later), FAILED, DISPUTE_OPENED and DISPUTE_CLOSED. A result may carry keep, a token to store as the client's payment method, or next, a further step such as 3-D Secure. Return null for events you do not use. CoreInto records the transaction, marks the invoice paid, logs the raw answer in the Gateway Log and does everything that follows a payment.
Rules#
- Never trust the return address alone: confirm with the provider before returning
PAID. - Amounts are integers in minor units.
- Never log or keep card details typed on CoreInto's page.
Shipping a gateway#
Gateways are listed in CoreInto's gateway registry and released with CoreInto, so they are tested with every update. If you have written a gateway for a provider CoreInto does not have, send it to us through the partner program: we review it and ship it in a release with credit to you.
Frequently asked questions
How are gateway secrets stored?
Settings fields of the kind secret are encrypted with AES-256-GCM in the database.
Can a gateway store cards?
Yes. Return a token in the result's keep field and implement charge() for later payments, and canStore() to say so.