Payment request leaf: raising a request from another app
Another app asks shillinq for money through the shillinq-payment-requests leaf.
It reaches the leaf through OpenRegister's integration registry, in PHP. The leaf
offers two ways to raise a request. They differ in who is allowed to ask.
A person asks: create
$provider = $registry->get('shillinq-payment-requests');
$request = $provider->create($register, $schema, $objectId, $payload);
The signed-in user must carry the payment.request action. Administrators carry
it. Map the action to groups in the paymentActionGroups app config:
occ config:app:set shillinq paymentActionGroups --value '{"payment.request":["finance"]}'
requestedBy on the request is the user id. This is also the path OpenRegister's
HTTP route takes (POST /api/objects/{register}/{schema}/{id}/integrations/shillinq-payment-requests).
An app asks: createAsApp
Use this when nobody who may ask is signed in. Larpinq does: a player takes a free place, or its daily job moves a waitlisted registration up.
$provider = $registry->get('shillinq-payment-requests');
if (method_exists($provider, 'createAsApp') === true) {
$request = $provider->createAsApp('larpinq', $register, $schema, $objectId, $payload);
}
An administrator grants the action to the app in the paymentActionApps app
config. No app carries it by default:
occ config:app:set shillinq paymentActionApps --value '{"payment.request":["larpinq"]}'
- The app must be named for
payment.requestand be enabled. Otherwise the leaf throws aRuntimeExceptionwhose message starts with403, and writes nothing. - A signed-in administrator does not lend the action to an app.
requestedByon the request isapp:<appId>, for exampleapp:larpinq.- Shillinq reads and writes the request as the system, so it works without a user.
- The one-open-request-per-type rule still holds. A second pending request of the
same type on the same object throws an
InvalidArgumentException. - OpenRegister's HTTP route never calls
createAsApp. A request body that names an app does not opencreate.
Payload
Both methods take the same fields: amount, currency (default EUR),
requestType, description, debtor, dueAt, subjectType,
paymentGateway (default mollie), paymentReference, invoiceRequested and
administrationId. The host object becomes the request's
subject. Unknown keys are ignored.
requestType is one of leges, dwangsom, deposit, contribution, event-fee
(the fee for taking part in an event) and other. An administrator maps each
type to a revenue account in paymentRevenueAccounts, for example
{"event-fee": "8050"}.
paymentReference is the reference the payer quotes on a bank transfer, for
example WC26-0042. It is optional, at least 6 characters, and only one open
(pending or authorized) request may carry it, compared without case; the
leaf refuses a second one.
invoiceRequested: true asks for an invoice behind the request. Shillinq finds
or creates the debtor's customer (by debtor.customerMasterId, else by
debtor.email in the administration, else a new one from debtor.name and
debtor.email), issues one invoice for the description and the amount, and sets
the request's invoiceReference to it. A payment then settles that invoice, so
the income is booked once. Such a call also needs administrationId, the
administration that bills the invoice; without it, or without a debtor, the leaf
throws an InvalidArgumentException and writes nothing. The amount is gross. A
type is exempt from VAT unless an administrator maps a rate in
paymentRequestVatRates, for example {"event-fee": 21}.
When the request is settled (paid online, or money recorded by hand) and the
debtor has an email, shillinq mails the debtor one receipt with the
description, the amount, the date, the reference and the confirmation
summary, and records receiptSentAt.
A bank statement line (file import or connected bank account) that quotes a
pending request's paymentReference as a whole word is matched to it. With
exactly one such request and the full open amount, the match is confirmed at
once: the request gets a bank-transfer settlement and settledVia: bank-transfer, and the receipt is posted with the bank account debited (or
the invoice behind the request is paid). Another amount, or two quoted
requests, leaves a pending match for the bookkeeper to confirm or reject.
Both return the created request as an array, with its id and state: pending.
Read its later state from the PaymentRequest object events, or with list.
Refund or credit a settled request
The app a request stands on can ask shillinq to give the money back, or to
keep it as credit for the payer's next request. It dispatches one of two typed
events with IEventDispatcher::dispatchTyped() and reads the answer from the
same object:
$event = new \OCA\Shillinq\Event\PaymentRefundRequestedEvent(
sourceApp: 'larpinq',
paymentRequestId: $paymentRequestId,
reason: 'Cancelled by the player',
correlationId: $registrationId,
);
$dispatcher->dispatchTyped($event);
if ($event->isHandled()) {
$state = $event->getResult()['state']; // refund_requested
} else {
$error = $event->getError();
}
Look the class up with class_exists() first, so your app keeps working
without shillinq. The answer is {contractVersion: 1, paymentRequestId, state}.
Shillinq accepts the command only for a request on an object that your app
owns (named on the subject, raised by your app through createAsApp, or on
your app's register), that is settled, and that was not refunded or credited
before. Anything else comes back with an error and changes nothing.
PaymentRefundRequestedEvent: the request moves torefund_requestedwith the full amount inrefunds. Finance approves and pays it; the request then readsrefunded. Approving (POST /api/payment-requests/{id}/refund/approve) books the income back into the refunds payable account set inpaymentRefundAccount; marking it paid (POST /api/payment-requests/{id}/refund/paidwithbankReferenceandbankAccount) clears that account against the bank. Both need thepayment.administeraction. Finance takes both steps from Refunds to pay in the menu: the payment requests list filtered onrefund_requested(/bookkeeping/payment-requests?state=refund_requested).PaymentCreditRequestedEvent: shillinq moves the income to the customer credit account set inpaymentCreditAccount, records aDebtorCreditfor the payer's customer record or, without one, their email address, and the request readscredited. A debtor with neither gets an error and no credit.
Open credit pays the debtor's next request first. When your app raises a
request for a debtor with open credit in the same administration (the same
customer record, or the same email address), shillinq uses that credit, oldest
first, up to the amount. The request then carries a settlement with method
credit; when the credit covers it whole it is settled at once
(settledVia: credit, settledAt stamped) and reaches your app as the same
object event a payment does. What the credit does not cover stays due.