Skip to content

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 the limit cap 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, a sales_payment_transaction row of type refund is 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's additional_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 in refund_difference.
  • staffSessionToken, refundApprovalToken, operationId (optional): the refund's authorization. A settle by original_payment or store_credit needs operationId and a session or an approval. A register-paid settle under operationId books only that authorized operation.
  • authorizationProtocol (optional, int): 1 from a register that authorizes the refunds it pays before it pays them.
  • handoverUnconfirmed (optional, default false): the register could not confirm that the customer received the money. The settle books and records the operation as handover_unconfirmed, with a comment on the order for the staff to reconcile the drawer or the terminal.
  • notifyCustomer (optional, default false): send Magento's own credit memo email, the one core REST's notify and the admin's Email Copy of Credit Memo send. Honored for original_payment, store_credit and terminal; ignored for cash, exchange and manual_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 returns booked. Not refunded: failed. A gateway that still cannot respond leaves it uncertain.
  • POST /V1/pos/rma/refund-attempts/:attemptId/resolve: body { "resolution": "refunded", "staffName": "Anna de Vries", "note": "Refund visible in the provider dashboard" }, resolution refunded or not_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 autoApprove and refundMethod original_payment or store_credit, a settle by original_payment or store_credit, and a one-call return with the refund or store_credit resolution. The call carries the authorization and an operationId.
  • 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/authorize before it pays, then books it with the settle, or completes it.

A refund is authorized by one of:

  • staffSessionToken: a session from POST /V1/pos/staff/authenticate whose staff member is active and whose active role grants issue_refunds (Issue Refunds).
  • refundApprovalToken: a manager's approval of exactly this payout from POST /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_amount to the cent;
  • the parts go to cash, original_card or manual_card and total at most returned_amount less applied_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:

bin/magento hyva:pos:complete-exchange-refund <operation-id> [--provider-refund-id=<id>] [--apply]

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.