RMA
Hyvä POS is on the App Store
The free app is out for iPhone, iPad and Mac: install it from the App Store, connect your Magento store and sell. PRO, the Magento module with a license per terminal, follows shortly. News and pricing are at hyva.io/pos.
| Method | Route | Purpose |
|---|---|---|
GET |
/V1/pos/rma/order/:orderId |
Existing returns for an order |
GET |
/V1/pos/rma/:rmaId |
A single return |
GET |
/V1/pos/rma/open |
Open returns across all orders (the pending-returns inbox) |
GET |
/V1/pos/rma/options |
The active provider's reasons, conditions and resolutions, with ids |
GET |
/V1/pos/rma/eligibility/:orderId |
Whether the order and each line can still be returned, and for which resolutions |
POST |
/V1/pos/rma |
Create a return; optionally auto-approve and receive in one call |
PUT |
/V1/pos/rma/:rmaId/status |
Transition a return's status |
POST |
/V1/pos/rma/:rmaId/comment |
Add a comment |
POST |
/V1/pos/rma/:rmaId/cancel-refund |
Cancel a parked in-store refund: back to received, settlement chosen again |
POST |
/V1/pos/rma/:rmaId/close |
Close an open return; what the receive restocked goes back out |
POST |
/V1/pos/rma/:rmaId/receive |
Staged flow: record physical receipt and inventory routing |
POST |
/V1/pos/rma/:rmaId/resolve |
Staged flow: record per-line resolutions |
POST |
/V1/pos/rma/:rmaId/settle |
Settle an awaiting_refund return: create the credit memo, close |
POST |
/V1/pos/rma/process |
Collapsed flow: create RMA + credit memo + resolution in one call |
POST |
/V1/pos/rma/:rmaId/process |
Fast-track an existing (e.g. online-submitted) return in store |
POST |
/V1/pos/refunds/preview |
The credit memo a refund would book, never saved |
GET |
/V1/pos/rma/refund-attempts/:attemptId |
One refund attempt through the original payment's gateway |
POST |
/V1/pos/rma/refund-attempts/:attemptId/reconcile |
Ask the gateway again about an uncertain attempt |
POST |
/V1/pos/rma/refund-attempts/:attemptId/resolve |
Record what the provider's own records show for an uncertain attempt |
POST |
/V1/pos/refund-approvals |
A manager's approval of one refund payout |
POST |
/V1/pos/refund-operations/authorize |
Authorize a payout the register makes itself, before the money leaves |
POST |
/V1/pos/refund-operations/:operationId/complete |
Complete an authorized register payout that no return's settle books |
All routes require the Hyva_Pos::locations ACL resource, except POST /V1/pos/refund-approvals (Hyva_Pos::staff_manage). POST /V1/pos/rma, /rma/process, /rma/:rmaId/process and /rma/:rmaId/settle run Hyva\Pos\Api\RegisterRefundServiceInterface, which checks a refund's authorization before the returns provider is called; see Refund Authorization. Admin credit memos are not affected. The service delegates to the single configured returns provider (a bridge module implementing RmaProviderInterface, such as the Adobe Commerce RMA bridge). POST /V1/pos/rma/process also works on stores without any RMA module: it skips RMA creation and creates the credit memo directly.
Status Vocabulary
Every bridge reports status using the canonical vocabulary from Hyva\Pos\Api\RmaStatusVocabulary; the vendor's own human-readable name goes in status_label.
- Open (in flight, needs attention):
pending,authorized,partially_authorized,received,received_partially,approved,awaiting_refund - Terminal (settled end state):
resolved,closed,processed_closed,rejected,denied
Terminal states are sticky: a provider never moves a return out of one. This makes settle retries idempotent: settling an already-closed return is a no-op, not an error.
The Return Shape
Every route that returns a return uses this shape:
{
"id": 18,
"increment_id": "000000018",
"order_id": 2043,
"order_increment_id": "000002043",
"customer_id": 1287,
"status": "awaiting_refund",
"status_label": "Awaiting Refund",
"items": [
{
"entity_id": 31,
"order_item_id": 5120,
"product_name": "Strive Shoulder Pack",
"product_sku": "24-MB04",
"qty_requested": 2,
"qty_authorized": 2,
"qty_approved": 2,
"qty_returned": 2,
"reason": "Wrong Size/Color",
"condition": "Unopened",
"resolution": "Refund",
"status": "authorized"
}
],
"comments": [],
"created_at": "2026-08-12 11:02:44",
"updated_at": "2026-08-12 11:02:47",
"refund_method": "cash",
"credit_memo_id": null,
"credit_memo_increment_id": null
}
refund_method is the settlement channel (original_payment, cash, terminal, exchange, store_credit, manual_card), derived server-side; null when unknown. credit_memo_id / credit_memo_increment_id are set once the return has been settled with a memo.
Since module 1.3.0 the shape carries more fields where they apply:
| Field | Meaning |
|---|---|
pos_sale_id |
The register sale the return was created for; absent for a return created without one |
reused |
On a create's answer only: true when the sale already had a return and that return is returned with nothing created, false when this create made it |
ready |
For a return created with a sale id: true once the create's initialization (approve, receive, park or settle) has finished. A return that reads false is held, never settled |
refund_legs |
The credit legs the settle's memo gave back, per kind |
base_refund_total |
The settle's refund before credit netting, base currency |
base_handback |
What the memo sent back by the original tender: the refund less every credit leg |
refund_difference |
One sentence on how the booked legs differ from the expectedLegs the settle was sent; null when they match or none were sent |
refund_attempt_id / refund_attempt_state |
The return's newest refund attempt and its state (started, booked, uncertain, failed); absent when the return has none |
Read Routes
GET /V1/pos/rma/order/:orderId: array of returns for one order. The POS order-detail view uses it to show return history and block double returns.GET /V1/pos/rma/:rmaId: a single return.GET /V1/pos/rma/open?limit=200: returns in non-terminal statuses across all orders, one request. Backs the POS pending-returns inbox, so a cashier can complete an online-initiated return without looking up the source order. When thelimitcap is hit, offer "search by order number" for older returns.
Return Options and Eligibility
GET /V1/pos/rma/options?storeId=1: the active provider's reasons, item conditions and resolutions, in the backend's order, with labels at the store view (the request's store view when storeId is omitted):
{
"provider_code": "pos_builtin",
"store_id": 1,
"reasons": [{ "id": "Wrong Size/Color", "label": "Wrong Size/Color", "behavior": null, "is_store_credit": null }],
"conditions": [{ "id": "Unopened", "label": "Unopened", "behavior": null, "is_store_credit": null }],
"resolutions": [
{ "id": "Refund", "label": "Refund", "behavior": "refund", "is_store_credit": false },
{ "id": "Exchange", "label": "Exchange", "behavior": "exchange", "is_store_credit": false },
{ "id": "Store Credit", "label": "Store Credit", "behavior": "refund", "is_store_credit": true }
]
}
The built-in provider (abridged above) uses each label as its id; a vendor bridge returns the backend's own ids. A create sends an option's id back as reason_id, condition_id or resolution_id. A resolution's behavior (refund, exchange or unsupported) is what the register does with it, decided by the provider from the backend's own record; is_store_credit is true on a refund to store credit. Both are null on reasons and conditions.
GET /V1/pos/rma/eligibility/:orderId: whether the order, and each of its lines, can be returned now. For example, on a store whose Amasty Return Rules allow a refund (resolution id 1) within 14 days and an exchange (id 2) within 30, at day 20:
{
"order_id": 2043,
"outcome": "allowed",
"reason_code": null,
"reason": null,
"period_days": 30,
"lines": [
{
"order_item_id": 5120,
"name": "Strive Shoulder Pack",
"outcome": "allowed",
"reason_code": null,
"reason": null,
"qty_returnable": 2,
"period_days": 30,
"allowed_resolution_ids": ["2"],
"resolution_periods": [
{ "resolution_id": "1", "period_days": 14 },
{ "resolution_id": "2", "period_days": 30 }
]
}
]
}
outcome is allowed or forbidden; a forbidden order or line gives a reason_code (quantity, not_returnable, outside_period, vendor_rule) and a sentence. period_days 0 means no window applies. qty_returnable is null when the provider sets no limit. allowed_resolution_ids lists the resolutions a line can still be returned for (empty on a forbidden line, null when the backend sets no limit per resolution); resolution_periods is set where the backend keeps a period per resolution, such as Amasty's Return Rules. A line the answer does not list carries no restriction of its own. The built-in provider allows every resolution.
Create a Return
POST /V1/pos/rma: creates a return. This is the endpoint behind the POS walk-in return wizard.
{
"orderId": 2043,
"customerId": 1287,
"items": "[{\"order_item_id\":5120,\"qty_requested\":2,\"reason\":\"Wrong Size/Color\",\"condition\":\"Unopened\",\"resolution\":\"Refund\",\"inspected_condition\":\"pristine\",\"return_to_stock\":true}]",
"comment": "Walk-in return",
"autoApprove": true,
"locationId": 3,
"refundMethod": "cash",
"posSaleId": "9F3C2A1B-7D4E-4A61-8C0B-2E5F1A9D3C77",
"staffSessionToken": "…",
"operationId": "6f1e2d3c-4b5a-4978-8695-a4b3c2d1e0f9"
}
items is a JSON-encoded string, not a nested array; the service contract declares it as a string. Each row carries:
| Field | Purpose |
|---|---|
order_item_id |
The order item being returned |
qty_requested |
Quantity the customer is returning (drives the refund) |
reason |
Return reason, free vocabulary (the POS sends e.g. Wrong Item, Defective, Wrong Size/Color) |
condition |
Declared condition (Unopened, Opened, Damaged) |
resolution |
Per-line resolution label (Refund, Exchange, Store Credit) |
reason_id / condition_id / resolution_id |
Optional: the option ids GET /V1/pos/rma/options returns, in place of the labels |
inspected_condition |
Inspection verdict: pristine, damaged, or dispose. Ignored unless autoApprove is true |
return_to_stock |
Whether the line restocks; defaults to true when absent |
qty_received |
Optional partial receive; see the quantity contract below. Capped at qty_requested |
target_source_code |
Optional explicit MSI destination source, overriding the condition-based routing |
With autoApprove: false (the default) the return is created in pending for the back office to process. With autoApprove: true the server moves it through requested → approved → items_received in one round-trip using the inspection metadata on each row: pristine lines restock to their origin source, damaged lines route to the location's configured damaged-stock source, dispose lines are written off. locationId is required in this mode because damaged-stock routing reads the location's damaged_stock_source_code.
refundMethod (honored only with autoApprove: true) decides what happens next: original_payment (through the original gateway) and store_credit settle in the same call and close the return; both need authorization. cash, terminal, manual_card and exchange leave the return in awaiting_refund for the cashier to finish at the register.
staffSessionToken, refundApprovalToken and operationId (all optional) carry the refund's authorization: a create that pays out needs operationId and one of the other two. A create that parks its return needs none of them.
Response: the created return in the shape above. The auto-approve fast path is best effort: if the approve or receive step fails, the return is already persisted and the error surfaces to the caller so the client can show a partial-success warning; a manager finishes it from admin.
posSaleId (optional, at most 64 characters) is the register's sale id, the same one a sale's order carries as pos_sale_id, and makes the create idempotent: one return per sale. The module records the sale with the provider's return in one transaction and runs the return's initialization (approve, receive, park or settle, as autoApprove and refundMethod ask) under Magento's order mutex. A create whose sale is already recorded creates nothing and returns that return with reused: true, after finishing an initialization the first create had not finished; two creates of one sale at once end with one return. The answer of a create with a sale id carries pos_sale_id, ready and reused. A create without one is unchanged.
Before anything is created, the provider's eligibility is read again. Refusals:
| HTTP | parameters.outcome |
When |
|---|---|---|
400 |
return_not_eligible |
The order or a requested line is forbidden, or a quantity exceeds what a line can still return (a row's own, and the rows of one order item summed). parameters carries reason_code, period_days and order_item_id (0 for the order). Outside the return period the message gives the period and the Magento admin as the way out; there is no override. A resolution whose behavior is unsupported (reason_code resolution_unsupported) or that the line's allowed_resolution_ids leave out (resolution_not_allowed) is refused the same way, with resolution_id and allowed_resolution_ids |
409 |
sale_return_conflict |
The sale id is recorded for another order, under another provider, or its return can no longer be read |
409 |
sale_return_being_created |
The sale's return exists but its initialization cannot be finished now (the order lock is held past the wait, or the return is in a status the module does not know) |
The Quantity Contract
The refund follows the requested/approved quantity, not the received one. A cashier receiving 3 of 5 items as restockable still refunds all 5; only the restock drops to the received count. qty_received feeds inventory routing, never the credit memo. Do not build integrations that expect a partial receive to shrink the refund.
Status and Comments
PUT /V1/pos/rma/:rmaId/status: body { "status": "approved", "comment": "Approved at the register" } (comment optional). Returns the updated return. Use vocabulary codes for status.
POST /V1/pos/rma/:rmaId/comment: body { "comment": "Customer will pick a replacement tomorrow", "notifyCustomer": false }. Returns true.
POST /V1/pos/rma/:rmaId/cancel-refund: body { "comment": "Customer wants it on the card" } (comment optional). Moves an awaiting_refund return back to received: the items stay received and restocked, no credit memo exists, and the settlement is chosen again. The audit trail gets the line "In-store refund cancelled at the register." followed by the comment, and refund_method reads null until the return is parked again. A return already on received is returned unchanged; any other status is refused with a 400.
POST /V1/pos/rma/:rmaId/close: body { "comment": "Customer kept the goods" } (comment optional). Closes an open return. Every line the register restocked when it received the return goes back out of the source it went to, never below zero; the audit line reads "Return closed at the register. Taken back out of stock: 1 × sku from source." followed by the comment. No credit memo is created. A return already closed, processed or rejected is returned unchanged.
Staged Flow: Receive and Resolve
For back-office style processing the lifecycle can be walked step by step instead of collapsed into create.
POST /V1/pos/rma/:rmaId/receive: records physical receipt and routes inventory; transitions approved → items_received. itemsJson rows are keyed by rma_item_id (the entity_id from the return's items, not the order item id):
{
"itemsJson": "[{\"rma_item_id\":31,\"condition\":\"pristine\",\"qty_received\":2,\"return_to_stock\":true}]",
"locationId": 3
}
POST /V1/pos/rma/:rmaId/resolve: records each line's resolution (refund, store_credit, exchange, repair, dispose) and triggers the downstream action; transitions to resolved once every line carries one:
{
"resolutionsJson": "[{\"rma_item_id\":31,\"resolution_mode\":\"refund\",\"refund_method\":\"cash\"}]"
}
Settle a Refund
POST /V1/pos/rma/:rmaId/settle: finishes an awaiting_refund return once the cashier has handed money back, reversed on the card terminal, or closed the exchange sale. Creates the credit memo (offline for cash / terminal / exchange / store_credit, online for a resumed original_payment) and closes the return.
{
"method": "terminal",
"reference": "re_4qqhO89gsT",
"rawPayload": "{\"resource\":\"refund\",\"id\":\"re_4qqhO89gsT\"}",
"adjustmentNegative": 5.0
}
reference(optional): PSP refund id or linked exchange-order increment. When present and the memo creates successfully, asales_payment_transactionrow of typerefundis written so the refund shows in Magento's Transactions tab and accounting exports. Omit for cash.rawPayload(optional): raw PSP response stored on the transaction'sadditional_information.adjustmentPositive/adjustmentNegative(optional, ex-tax): goodwill credit on top of, or a restocking fee subtracted from, the items refund, stamped on the memo's adjustment fields.shippingAmount(optional): explicit refunded shipping; omitted or zero lets Magento distribute per its memo defaults.expectedLegs(optional): the credit legs of the refund preview the register acted on. The settle books what Magento's collectors produce whatever these say; a difference is recorded on the return as a status-history comment and returned inrefund_difference.staffSessionToken,refundApprovalToken,operationId(optional): the refund's authorization. A settle byoriginal_paymentorstore_creditneedsoperationIdand a session or an approval. A register-paid settle underoperationIdbooks only that authorized operation.authorizationProtocol(optional, int):1from a register that authorizes the refunds it pays before it pays them.handoverUnconfirmed(optional, defaultfalse): the register could not confirm that the customer received the money. The settle books and records the operation ashandover_unconfirmed, with a comment on the order for the staff to reconcile the drawer or the terminal.notifyCustomer(optional, defaultfalse): send Magento's own credit memo email, the one core REST'snotifyand the admin's Email Copy of Credit Memo send. Honored fororiginal_payment,store_creditandterminal; ignored forcash,exchangeandmanual_card. A retry that reuses the memo of an earlier attempt sends nothing.
Response: the settled return, now carrying credit_memo_id and credit_memo_increment_id, and the booking: refund_legs, base_refund_total, base_handback, refund_difference, refund_attempt_id and refund_attempt_state. The credit memo quantities follow the quantity contract above. Idempotent: settling an already-closed return returns it unchanged, so it is safe to retry after a timeout. Under an operation, a repeat returns the first result. A memo Magento refuses because another refund used up the order responds that nothing is left to refund, identifies the memo that took it, and leaves the return parked with a comment.
A return created with a sale id whose initialization has not finished (ready: false) is finished first and then settled; when that cannot happen now the settle returns 409 return_not_ready with return_id and books nothing.
Refund Preview
POST /V1/pos/refunds/preview: builds the credit memo a refund would create, through every vendor's collectors and with the store-credit provider's preparation applied as the settle applies it, and never saves it. The register reads its refund cap and handback from it.
{
"orderId": 2043,
"items": "[{\"order_item_id\":5120,\"qty\":1}]",
"channel": "original",
"adjustmentPositive": 0,
"adjustmentNegative": 0,
"shippingAmount": 0
}
channel is original (the original tender) or store_credit. The answer carries order_id, channel, currency_code, base_refund_total / refund_total (the refund before credit netting), base_handback / handback (what goes back by the original tender: the refund less every credit leg), base_returnable_max / returnable_max (the most the order can still refund), legs (the credit legs the refund gives back, per kind) and lines (per line: order_item_id, qty, base_row_total, base_credit_share, and for a points discount base_points_amount and points).
Refund Attempts
A refund through the original payment's gateway is recorded as a refund attempt before the gateway is called, and the memo and the attempt's move to booked commit together. After a rollback the attempt is failed when the gateway was not called or provably did not refund, and uncertain when it may have refunded. For an uncertain attempt the settle returns 409, parameters outcome: gateway_uncertain, refund_attempt_id, refund_attempt_state and return_id; the return stays parked and nothing is refunded for it until the attempt is reconciled or resolved. An order paid through Mollie's Orders API is refused before an attempt is written ("Refund this order from the Magento admin: its Mollie payment was made through the Orders API, which the register cannot track.").
GET /V1/pos/rma/refund-attempts/:attemptId: one attempt:attempt_id,order_id,return_id,payment_method,channel,state(started,booked,uncertain,failed),base_amount,credit_memo_id,credit_memo_increment_id,gateway_outcome,gateway_reference,message,resolved_by,resolution_note,created_at,updated_at.POST /V1/pos/rma/refund-attempts/:attemptId/reconcile: asks the gateway again. Refunded: the return's memo is booked without a second gateway call and the attempt returnsbooked. Not refunded:failed. A gateway that still cannot respond leaves ituncertain.POST /V1/pos/rma/refund-attempts/:attemptId/resolve: body{ "resolution": "refunded", "staffName": "Anna de Vries", "note": "Refund visible in the provider dashboard" },resolutionrefundedornot_refunded. Recorded on the attempt and as a comment on the return. Refunded books the memo without calling the gateway; not refunded fails the attempt and the next settle refunds anew.
All three return the attempt in the shape above. Mollie's and PAY.'s Magento modules keep nothing a refund could be found by afterwards, so their uncertain attempts are resolved by hand.
Refund Authorization
A refund at the register is authorized by Magento before money leaves. The four refund routes above (POST /V1/pos/rma, /rma/process, /rma/:rmaId/process and /rma/:rmaId/settle) run Hyva\Pos\Api\RegisterRefundServiceInterface, which checks the authorization before the returns provider is called. Admin credit memos are not affected. Two cases:
- Magento pays out. A create with
autoApproveandrefundMethodoriginal_paymentorstore_credit, a settle byoriginal_paymentorstore_credit, and a one-call return with therefundorstore_creditresolution. The call carries the authorization and anoperationId. - The register pays out. Cash, a terminal or manual card refund, an exchange that hands money back, a layaway cancel's hand-back, the refund of a terminal payment no order carries. The register authorizes the payout through
POST /V1/pos/refund-operations/authorizebefore it pays, then books it with the settle, or completes it.
A refund is authorized by one of:
staffSessionToken: a session fromPOST /V1/pos/staff/authenticatewhose staff member is active and whose active role grantsissue_refunds(Issue Refunds).refundApprovalToken: a manager's approval of exactly this payout fromPOST /V1/pos/refund-approvals. The operation uses it up.
A create that parks its return pays nothing out and needs neither. GET /V1/pos/config lists refund_authorization, refund_operation_authorize and refund_operation_complete under capabilities on a store that does this.
| Method | Route | ACL | Purpose |
|---|---|---|---|
POST |
/V1/pos/refund-approvals |
Hyva_Pos::staff_manage |
A manager's approval of one refund payout |
POST |
/V1/pos/refund-operations/authorize |
Hyva_Pos::locations |
Authorize a payout the register makes itself, before the money leaves |
POST |
/V1/pos/refund-operations/:operationId/complete |
Hyva_Pos::locations |
Complete an authorized register payout that no return's settle books |
The Payout
Approvals and authorizations describe the money with a payout object:
| Field | Type | Meaning |
|---|---|---|
order_id |
int or null | The order refunded; null only for a terminal payment no order carries |
return_id |
int or null | The return the refund settles, when it exists already |
operation_id |
string | The operation's UUID, or empty |
lines[] |
order_item_id (int), qty (float) |
The lines taken back |
parts[] |
destination (string), reference (string or null), amount (decimal string) |
Where the money goes |
exchange |
object or null | The split of an exchange that hands money back |
destination is cash, original_card, manual_card, original_payment, store_credit, gift_card, reward_points or invoice_credit. reference identifies the destination where it needs naming: the provider's payment ID for a card refund, a gift card's code. Amounts are decimal strings such as "30.00". The approval binds to the order, the return, the operation, the lines and each part's destination, reference and amount to the cent.
A payout without an order (order_id null) refunds a terminal payment taken for a sale that was never placed: no lines, no return, and every part to original_card with the provider's payment ID as reference. Any other payout without an order is refused with "The refund names no order." While one operation refunds a payment (authorized, booked or running), another operation for the same payment returns 409 operation_conflict with parameters.other_operation_id.
Exchanges That Hand Money Back
exchange splits the return's value:
| Field | Type | Meaning |
|---|---|---|
replacement_sale_id |
string, UUID | The pos_sale_id the replacement order carries |
returned_amount |
decimal string | What the return's credit memo books |
applied_credit |
decimal string | The part of it that pays for the replacement order |
adjustment_positive, adjustment_negative, shipping_amount |
decimal string or null | The memo's adjustments and refunded shipping |
parts are the money handed back. The authorization accepts the split only when it can be settled, before it reads the staff right or the approval:
- the return is the order's, is open, and returns the payout's lines;
- the refund preview of those lines and adjustments books
returned_amountto the cent; - the parts go to
cash,original_cardormanual_cardand total at mostreturned_amountlessapplied_credit, one cent of rounding allowed; - no other operation identifies the replacement sale;
- a replacement order placed already was paid with
applied_credit.
Otherwise the answer is 400 exchange_allocation_refused with parameters.problem, or 409 operation_conflict with other_operation_id. A manager's approval covers the parts only.
problem |
Meaning |
|---|---|
destination_not_allowed |
A part goes somewhere other than cash or a card |
payout_exceeds_return |
The money handed back exceeds the returned value less the credit |
returned_value_mismatch |
returned_amount is not what the return's memo books |
return_mismatch |
The return is not the order's, is settled, or returns other lines |
settle_mismatch |
The settle is not this exchange's, or identifies another replacement sale |
replacement_credit_mismatch |
The replacement order was not paid with this credit |
replacement_order_mismatch |
The replacement order resolves another return, is the original order, or was canceled |
The settle of such an exchange (method exchange, reference the replacement sale ID, operationId) books only once the order carrying that pos_sale_id exists, is not canceled, is not the original order, gives this return or none as pos_rma_id, and carries the applied credit as pos_exchange_credit_amount, and only when its credit memo books the returned amount. Before that order exists it returns 409 replacement_sale_pending and books nothing. A settle that does not match returns 400 exchange_allocation_refused. Either way the operation stays authorized for the next settle. A booked exchange comments on the original order and on the replacement order, identifying the credit memo, the original order, the return and the operation.
Approve a Refund (POST /V1/pos/refund-approvals)
ACL Hyva_Pos::staff_manage.
{
"approverStaffId": 3,
"approverPasscode": "482913",
"payout": {
"order_id": 2043,
"return_id": 18,
"operation_id": "6f1e2d3c-4b5a-4978-8695-a4b3c2d1e0f9",
"lines": [{ "order_item_id": 5120, "qty": 1 }],
"parts": [{ "destination": "cash", "reference": null, "amount": "45.00" }]
}
}
The passcode is checked as POST /V1/pos/staff/authenticate checks it, against the same lockout count. The approver is an active staff member whose role grants issue_refunds. The answer carries approval_token and expires_at. The token is used once and lapses after 15 minutes. Magento stores its SHA-256 in hyva_pos_refund_approval, never the token itself.
Authorize a Register Payout (POST /V1/pos/refund-operations/authorize)
Takes operationId, payout, staffSessionToken and refundApprovalToken. The payout is authorized as above and recorded as authorized in hyva_pos_refund_operation. The answer is operation_id and state: authorized; completed or handover_unconfirmed once the operation's settle booked it; not_refunded once a completion closed it with nothing paid. The same operation ID with the same payout responds again, also after the approval expired or was used by it. Another payout returns 409 operation_conflict.
The settle that books the operation (POST /V1/pos/rma/:rmaId/settle with this operationId) is accepted whenever it arrives, also after a connection loss and after the approval expired, when it books this payout: the same order, return and lines, and a credit memo of at most the authorized total plus one cent. A repeat returns the first result. A settle for an operation never authorized is refused. An operation authorized before its return existed (return_id null) is bound to the return of its first settle; a settle of another return under it returns operation_conflict.
Complete a Register Payout (POST /V1/pos/refund-operations/:operationId/complete)
For an authorized operation no return's settle books: the refund of a terminal payment no order carries, or a refund discrepancy's hand-back. Takes payout (the payout it was authorized with), outcome (refunded, not_refunded or handover_unconfirmed) and an optional providerRefundId. It returns operation_id and state. No credentials are needed; they went with the authorization. A repeat returns the state the first call recorded and changes nothing. Another payout, an operation Magento pays out, or a payout with lines returns 409 operation_conflict; an operation never authorized returns approval_required. A completed refund of a terminal payment is stored as a sale event (kind intervention, action refund_unbooked_payment). A completed payout of an order adds a comment to the order's history.
Operations Run Once
Each refund operation is recorded by its operationId before anything is paid out. A repeat that asks for another refund (another route, order, return, lines, channel or amount) returns 409 operation_conflict and refunds nothing. A repeat of the same refund returns the first result, 409 refund_in_progress while it runs, or 409 gateway_uncertain while its gateway refund has no answer. An operation that stopped where running it again could refund twice returns 400 refund_in_progress: read the order's returns before you refund again. A settle refused outright runs again under the same operation.
Registers Before This Release
A register before app 0.4.0 sends no staffSessionToken, refundApprovalToken, operationId or authorizationProtocol. This module responds to its calls as follows:
| Call from a register before app 0.4.0 | Answer |
|---|---|
POST /V1/pos/rma with autoApprove and refundMethod original_payment or store_credit |
400 register_outdated; no return is created and nothing is refunded |
POST /V1/pos/rma/:rmaId/settle with method original_payment or store_credit |
400 register_outdated; nothing is refunded |
POST /V1/pos/rma/process and POST /V1/pos/rma/:rmaId/process with resolution refund or store_credit |
400 register_outdated; nothing is refunded |
POST /V1/pos/rma without autoApprove, or with a refundMethod the register pays out |
Creates the return as before |
POST /V1/pos/rma/:rmaId/settle with method cash, terminal, manual_card or exchange |
Settles as before |
POST /V1/pos/rma/process and POST /V1/pos/rma/:rmaId/process with resolution exchange |
Processes the return as before |
POST /V1/pos/layaways/:orderId/cancel |
Cancels the layaway and refunds the deposit as before |
So when this module is installed before the registers run app 0.4.0, refunds to the original payment and to store credit stop on those registers until their app is updated; the register shows the refusal's message, "Update the register to refund from it." A refused call writes nothing: no credit memo, no refund operation, no used approval. Refunds paid out at the register, exchanges and layaway cancellations keep working. App 0.4.0 on a module before this release refunds as before, since that module's GET /V1/pos/config lists no refund capability; update the app first. See Upgrading.
Your own integration that refunds through these routes sends an operationId (a UUID) and a session or an approval.
With authorizationProtocol 1 and no operationId, a register-paid settle returns register_outdated, except an exchange without a pspRefundId, which settles as before unless a refund operation handed money back for its return or replacement sale (409 operation_conflict, giving it as other_operation_id). A layaway cancel with authorizationProtocol 1 and no operationId returns register_outdated unless it refunds nothing.
Refusal Reasons
Every refusal from the four refund routes, the settle, the layaway cancel and the operation routes carries parameters.reason, and parameters.operation_id where it concerns an operation.
| HTTP | reason |
When |
|---|---|---|
| 400 | staff_session_missing |
No session was sent, or its token or staff member is not valid |
| 400 | staff_session_expired |
The session expired |
| 400 | refund_permission_denied |
The session's role does not grant issue_refunds, and no approval was sent |
| 400 | approval_required |
No usable approval, or the operation was never authorized |
| 400 | approval_mismatch |
The approval was given for another payout |
| 400 | approval_expired |
The approval lapsed unused |
| 400 | register_outdated |
The request lacks what the module requires of a register refund |
| 400 | refund_in_progress |
The operation stopped where running it again could refund twice |
| 400 | exchange_allocation_refused |
An exchange's split cannot be settled; see problem |
| 409 | operation_conflict |
The operation ID identifies another refund or payout; may carry other_operation_id |
| 409 | refund_in_progress |
The operation is running |
| 409 | gateway_uncertain |
The gateway refund has no answer yet; the settle's own conflict carries outcome too |
| 409 | replacement_sale_pending |
An exchange's replacement order is not in Magento yet |
Recover an Exchange by Hand
When the register handed money back for an exchange under an authorized operation and its settle never booked, complete it from what Magento holds:
The command reads the operation's payout, its open return, and the one order that gives the return as pos_rma_id and was paid with exchange credit. It goes ahead only when the money handed back plus that credit equals the return's credit memo to the cent. It then books the memo offline as an exchange settle does, closes the return, completes the operation and comments on the orders. No drawer opens and no provider is asked to refund. Without --apply it prints what it would book and writes nothing. On an operation already completed as an exchange it prints what was booked and exits 0.
Collapsed Processing
POST /V1/pos/rma/process: create RMA (when a returns module is available), create the credit memo, and handle the resolution in one call. Body: { "orderId": 2043, "customerId": 1287, "items": "[{\"order_item_id\":5120,\"qty\":2,\"reason\":\"Defective\",\"condition\":\"Opened\",\"resolution\":\"Refund\"}]", "resolution": "refund", "isOnline": true, "comment": null }. resolution is the primary resolution (refund, store_credit, or exchange); isOnline: true refunds through the payment gateway, false creates an offline memo. Both routes also take staffSessionToken, refundApprovalToken and operationId; the refund and store_credit resolutions need authorization.
POST /V1/pos/rma/:rmaId/process: the same fast-track for an existing return (for example one submitted online). Body: { "resolution": "refund", "isOnline": true }.
Both respond with a process result rather than a return:
{
"success": true,
"error": null,
"rma_id": 18,
"rma_increment_id": "000000018",
"credit_memo_id": 77,
"credit_memo_increment_id": "000000077",
"refund_total": 118.9,
"store_credit_issued": 0.0,
"exchange_credit_amount": 0.0,
"is_online_refund": true,
"payment_method": "mollie_methods_ideal",
"transaction_id": "tr_WDqYK6vllg"
}
rma_id is null on stores without a returns module. The active provider runs the return; only its ReturnNotAttemptedException, raised before it wrote anything, lets the call go on to the next provider and then to the core's own credit memo. Any other exception from the provider stops the call with nothing else attempted and a status-history comment on the order identifying the provider and the failure: a definite refusal (LocalizedException) returns HTTP 400 with its message, an uncertain gateway refund 409 gateway_uncertain as the settle returns it, anything else 500. When no provider attempts an existing return, /V1/pos/rma/:rmaId/process returns 200 with success: false. A return the provider's eligibility forbids returns 400 return_not_eligible, as on create.
Error Behavior
Standard Magento web API envelope: 401 for a bad token, 404 (NoSuchEntityException) for unknown return or order ids, 400 for invalid payloads and provider-rejected transitions (LocalizedException). The 409 answers are listed with the routes that give them above. A refusal of a register refund carries parameters.reason; see Refusal Reasons.