Ga naar hoofdinhoud

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.request and be enabled. Otherwise the leaf throws a RuntimeException whose message starts with 403, and writes nothing.
  • A signed-in administrator does not lend the action to an app.
  • requestedBy on the request is app:<appId>, for example app: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 open create.

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 to refund_requested with the full amount in refunds. Finance approves and pays it; the request then reads refunded. Approving (POST /api/payment-requests/{id}/refund/approve) books the income back into the refunds payable account set in paymentRefundAccount; marking it paid (POST /api/payment-requests/{id}/refund/paid with bankReference and bankAccount) clears that account against the bank. Both need the payment.administer action. Finance takes both steps from Refunds to pay in the menu: the payment requests list filtered on refund_requested (/bookkeeping/payment-requests?state=refund_requested).
  • PaymentCreditRequestedEvent: shillinq moves the income to the customer credit account set in paymentCreditAccount, records a DebtorCredit for the payer's customer record or, without one, their email address, and the request reads credited. 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.