gln_modify_standing_order

Declared in <galanthus/c_api/gln_capi.h>.

GLN_API gln_status_t GLN_CALL gln_modify_standing_order(
    gln_backend_t*                             in_backend,
    const gln_modify_standing_order_request_t* in_request,
    gln_backend_result_t**                     out_result);

Family: Backend operations
Return type: gln_status_t

Purpose

gln_modify_standing_order submits a FinTS standing-order modification request and returns a gln_backend_result_t envelope.

Backend support is operation-specific. Use gln_check_backend_operation_support to check whether a backend supports this operation before calling it. Unsupported operations return an envelope whose status is GLN_ERR_NOT_SUPPORTED.

When To Use

Use this operation after obtaining the bank order reference for an existing standing order, usually from gln_get_standing_order_reference on a list result.

Expect action-required envelopes for TAN, decoupled approval, or VoP confirmation.

Call Contract

GLN_OK from the function means an envelope was produced in *out_result; it does not mean the backend operation succeeded. Inspect the envelope with gln_get_backend_result_outcome, gln_get_backend_result_status, and gln_get_backend_result_kind.

out_result == NULL is the no-envelope invalid-argument case. In that case the function returns GLN_ERR_INVALID_ARG directly.

For gln_modify_standing_order_request_t, initialize the struct with gln_default_modify_standing_order_request. The request carries order_reference, source identity, recipient identity, amount, currency, purpose, optional end_to_end_reference_or_null, and schedule fields first_execution, interval, execution_day, and optional last_execution_or_null; the default helper sets currency to EUR and interval to M.

The parameter table is binding for required handles and output slots.

Return

Returns GLN_OK when the call produced a gln_backend_result_t envelope in out_result. Operation success, caller action, provider rejection, and operation errors are reported inside that envelope.

Type	Nullability	Ownership
`gln_status_t`	value	value

Parameters

Name	Direction	Type	Nullability	Ownership
`in_backend`	input	`gln_backend_t*`	nonnull	borrowed
`in_request`	input	`const gln_modify_standing_order_request_t*`	nonnull	borrowed
`out_result`	output	`gln_backend_result_t**`	nonnull	transferred_out

Success Result

Successful operation envelopes have outcome GLN_BACKEND_OUTCOME_SUCCESS, status GLN_OK, and kind GLN_BACKEND_RESULT_KIND_STANDING_ORDER_SUBMISSION.

Borrow the typed success view with gln_get_backend_result_standing_order_submission.

Use gln_get_backend_result_standing_order_submission only when the envelope outcome is GLN_BACKEND_OUTCOME_SUCCESS and the kind is GLN_BACKEND_RESULT_KIND_STANDING_ORDER_SUBMISSION.

Action-required envelopes carry interrupt details and a continuation instead of this typed success view. TAN and decoupled continuations can be resumed to produce a later success envelope; unsupported VoP confirmation resume paths return the envelope described under Outcomes.

gln_get_standing_order_submission_status returns the FinTS submission status. VoP accessors return NULL when no VoP block is present and a non-null empty string when the block is present but the field value is empty.

Outcomes

GLN_BACKEND_OUTCOME_SUCCESS: read the GLN_BACKEND_RESULT_KIND_STANDING_ORDER_SUBMISSION typed view.
GLN_BACKEND_OUTCOME_ACTION_REQUIRED: FinTS standing-order write flows can require caller action, usually a TAN, decoupled step, or VoP confirmation. TAN and decoupled continuations follow the normal resume path; unsupported VoP confirmation resume paths return an envelope from gln_resume_continuation with status GLN_ERR_NOT_SUPPORTED and issue type unsupported_vop_confirmation_backend. Inspect gln_get_backend_result_interrupt_info. For TAN and decoupled action requirements, take the continuation with gln_take_backend_result_continuation and resume with gln_resume_continuation.
GLN_BACKEND_OUTCOME_REJECTED: inspect gln_get_backend_result_status and gln_get_backend_result_error for FinTS rejection details.
GLN_BACKEND_OUTCOME_ERROR: inspect gln_get_backend_result_status and gln_get_backend_result_error. Other backends use this outcome with status GLN_ERR_NOT_SUPPORTED.

Ownership And Lifetime

The envelope returned through out_result is caller-owned and must be released with gln_destroy_backend_result.

Typed views, result rows or fields, borrowed strings, and the JSON string are borrowed from the envelope. They become invalid when the envelope is destroyed. Copy strings or row data before destroying the envelope when the caller needs to keep them.

For action-required envelopes, gln_get_backend_result_interrupt_info returns borrowed interrupt details. gln_take_backend_result_continuation transfers continuation ownership to the caller; destroy that continuation with gln_destroy_continuation after it has been saved or resumed.