Signing Baskets & Drafts

Payment Type Roadmap

Draft support is being rolled out per payment type. The table below shows the current status and planned timeline.

Drafts

Drafts provide a staged payment preparation workflow. Instead of submitting a fully populated payment in a single request, you can:

1. Create a draft — name is always required. Domestic credit transfer drafts also require a client-provided draftId; SE Giro drafts may omit draftId (the server generates one).
2. Update the draft incrementally as payment details become available
3. Approve the draft through the POST /payments/drafts/approve endpoint, which initiates the actual payment

Drafts do not have individual approve endpoints — all approval goes through the general Signing Baskets batch approval flow, even when approving a single draft. This is useful when payment details are collected across multiple steps or screens in your application.

Draft Lifecycle

Draft Endpoints

Each supported payment type has its own set of draft endpoints under /payments/drafts/{payment-type}/. The operations are the same across payment types, but the required fields and validation rules differ depending on the payment type (see the payment-type-specific sections below).

Drafts are approved through the Signing Baskets batch approval flow.

PATCH only updates fields that are present in the request body with non-empty values. Omitted fields are left unchanged. Sending an empty string does not clear an existing value — supply a new non-empty value to change a field.

All draft endpoints require the PSP_PI (Payment Initiation) scope.

Common Fields

Every draft has the following fields regardless of payment type:

The redirectUrl for Strong Customer Authentication is supplied on the batch approve request, not on the draft itself.

Additional fields are payment-type-specific — see the sections below.

Draft Response

All draft endpoints return a response with this common structure:

Payment-type-specific fields (e.g. giroNumber, amount) are included when set.

The validationErrors array currently contains a single aggregated entry — not a per-field breakdown:

Example — single missing field (a SE Giro draft with no giroNumber):

{
  "draftId": "1f4a9c3e-2b7d-4e8a-9f10-6c8b3d5e7f01",
  "status": "CREATED",
  "isValid": false,
  "name": "Invoice 123",
  "validationErrors": [
    {
      "field": "draft",
      "message": "Giro number is missing"
    }
  ]
}

Example — several fields missing (message is aggregated, not one entry per field):

{
  "draftId": "1f4a9c3e-2b7d-4e8a-9f10-6c8b3d5e7f01",
  "status": "CREATED",
  "isValid": false,
  "name": "Invoice 123",
  "validationErrors": [
    {
      "field": "draft",
      "message": "Several required fields are missing"
    }
  ]
}

Draft Statuses

Error Handling

All draft endpoints return errors in a consistent format:

Common error codes:

Errors specific to the batch approve flow (ALREADY_USED, MISSING_DRAFT_IDS, MISSING_REDIRECT_URL, TRANSFER_DENIED) are documented on the Approve Drafts endpoint.

Sender Account Access

When senderAccountId is supplied on create (POST) or update (PATCH) for any draft type that supports it (domestic credit transfer and SE Giro), Lunar verifies that the caller has access to that account. Access is granted when any of the following holds:

• The caller is the direct owner of the account (private accounts).
• The caller is a party on the organisation that owns the account (organisation/business accounts).
• The caller has been granted explicit shared access to the account by its owner.

If none of these apply, the request is rejected with 403 ACCOUNT_ACCESS_DENIED and no change is made to the draft.

Automatic clearing of senderAccountId

A draft’s senderAccountId can become unusable after the draft is created — for example when the account is closed, ownership changes, or a shared-access grant is revoked. When this happens, Lunar automatically clears senderAccountId on affected drafts that are still in CREATED status. The draft reverts to isValid: false with a validation error indicating the sender account is missing, and will continue to appear in GET /payments/drafts so the TPP can prompt the user to pick a new sender account before re-approving.

Domestic Credit Transfer Drafts

Domestic credit transfer drafts use /payments/drafts/domestic-credit-transfer. They follow the same draft lifecycle and are approved through signing baskets.

In addition to the common fields, domestic credit transfer drafts support:

All payment fields except draftId and name are optional at creation time and can be added later via PATCH. See Sender Account Access when setting senderAccountId.

Validation Requirements

Before a domestic credit transfer draft can be approved, it must pass validation. Every create, update, and get response includes isValid — use it to decide whether the draft is ready for POST /payments/drafts/approve.

When isValid is false, read validationErrors[0].code for programmatic handling and validationErrors[0].message for display. Pass X-Language (en, sv, da, nb) to localize the message; defaults to en. See Draft Response for the full response shape.

Minimum fields — all four must be populated before Lunar runs full domestic credit transfer validation (same rules as direct initiation):

If any minimum field is missing, isValid is false and validationErrors describes that required fields are still missing.

Full DCT validation runs once all minimum fields are present. The same rules as direct initiation apply, including:

Example — minimum fields not yet populated:

{
  "draftId": "1f4a9c3e-2b7d-4e8a-9f10-6c8b3d5e7f01",
  "status": "CREATED",
  "isValid": false,
  "name": "Rent May",
  "validationErrors": [
    {
      "field": "draft",
      "code": "MISSING_REQUIRED_FIELDS",
      "message": "Several required fields are missing"
    }
  ]
}

Example — full validation ran but a value is invalid:

{
  "draftId": "1f4a9c3e-2b7d-4e8a-9f10-6c8b3d5e7f01",
  "status": "CREATED",
  "isValid": false,
  "name": "Rent May",
  "receiverAccountBban": "11112222333344",
  "amount": "100.00",
  "currency": "DKK",
  "senderAccountId": "acc-123",
  "validationErrors": [
    {
      "field": "draft",
      "code": "INVALID_RECEIVER_ACCOUNT",
      "message": "The receiver account is invalid"
    }
  ]
}

Validation error codes — domestic credit transfer drafts return a single aggregated entry with field: "draft". The code identifies the reason. Only codes the TPP can resolve by updating draft fields are listed:

Norwegian KID payments can fail backend validation with KID_REQUIRED or INVALID_KID, but the Open Banking draft API does not expose a KID field — those errors are not actionable through this API. Use a different receiver account or payment type.

Use code for programmatic handling; use message for localized display.

Payment failure and cancellation

When a previous approval or payment attempt fails, the draft returns to CREATED and GET /payments/drafts/domestic-credit-transfer/{id} includes previousFailureReason — a localized string describing the failure (pass X-Language; supported values: en, sv, da, nb). The same failure is surfaced as localized paymentError on GET /payments/drafts.

Pass X-Language on GET (and on create/patch responses) to localize validationErrors[].message and previousFailureReason on domestic credit transfer drafts. Use validationErrors[].code for programmatic handling — it is language-independent. Defaults to en if omitted or unrecognized.

To cancel an in-flight payment linked to a draft:

DELETE /payments/drafts/domestic-credit-transfer/{id}/payment

Returns 204 No Content when the in-flight payment is cancelled. The operation is idempotent when the payment is already cancelled. Returns 409 Conflict when the draft has no in-flight payment to cancel (for example, the draft is still in CREATED with no prior approval).

Example: Domestic Credit Transfer Draft

SE Bank Giro & SE Plus Giro Drafts

SE Bank Giro and SE Plus Giro share the same draft fields and validation rules. The only difference is the endpoint path: /payments/drafts/se-bank-giro vs /payments/drafts/se-plus-giro.

Payment-Type Fields

In addition to the common fields, SE Giro drafts support:

All of these fields are optional at creation time and can be added later via PATCH.

Validation Requirements

A SE Giro draft must have the following fields populated before it can be approved (isValid: true):

If any of these fields are missing or invalid, the draft response will include isValid: false and a validationErrors array describing what needs to be fixed.

See Sender Account Access when setting senderAccountId.

Example: SE Bank Giro Draft

Signing Baskets (Batch Approval)

A signing basket lets you group multiple drafts — potentially across different payment types — and approve them all at once through a single authorization flow. This is particularly valuable when a user needs to pay several invoices in one go: each invoice is a separate draft, and the batch approval triggers a single authentication challenge for the entire set.

When mixing payment types in one basket, your application must track which payment type each draftId belongs to — neither GET /payments/drafts nor the approval status response includes payment type (see Get Approval Status).

Signing Basket Flow

List Drafts

GET /payments/drafts

Returns draft summaries for the current user that are still approvable, across all payment types that support drafts (see the Payment Type Roadmap). Drafts in CREATED are returned — including drafts that are not yet valid (isValid: false) and drafts whose previous payment failed and are awaiting retry (paymentError set). Drafts in PENDING, COMPLETED, or DELETED are excluded.

Use this endpoint for discovery — showing the user which drafts can be selected for approval, and surfacing paymentError after a failed payment. Use GET /payments/drafts/{payment-type}/{id} when you need the full draft payload, field-level validation (validationErrors including code on domestic credit transfer drafts), or previousFailureReason on a specific draft.

The list response does not include payment type — record the payment type when you create each draft. It exposes invalidReason when isValid is false, not the machine-readable validationErrors[].code available on the per-type GET response.

Pass the X-Language header (supported values: en, sv, da, nb) to receive localized values for invalidReason and paymentError, and for the fallback name when a draft was created without one. TPP-supplied name values are returned as-is. Defaults to en if omitted or unrecognized.

Response:

Each draft in the list contains:

Approve Drafts (Batch)

POST /payments/drafts/approve

Approves and initiates execution of one or more drafts. A unique requestId is required to track the approval — it can be used to poll for status afterward.

Response:

When authUrl is present, the TPP can redirect the PSU to it to complete Strong Customer Authentication. After the challenge, the PSU is redirected back to the redirectUrl supplied on the approve request (see Post-SCA Redirect).

Post-SCA Redirect

The batch approval flow follows the same authorization pattern as single-payment endpoints: the TPP redirects the PSU to an authorization URL, the PSU completes Strong Customer Authentication, and the PSU is then redirected back to a TPP-owned URL.

The redirectUrl is scoped to the approval request — each batch approve supplies its own single URL that the PSU is sent back to after completing SCA for that batch.

Get Approval Status

GET /payments/drafts/approve/{requestId}/status

Returns the current status of a batch approval request, including per-draft progress.

Response:

Each entry in drafts contains:

Errors:

Per-Draft Status

Approval Status

The overall approval status reflects the state of the authorization challenge:

Cross-layer Status Mapping

0.6.0-beta aligned the three status vocabularies that show up across a single signing-basket flow so a TPP only needs to learn one. All three layers use the same uppercase values, with controlled collapsing where the layers don’t have a 1:1 correspondence.

• Draft (DraftResponse.status) — the lifecycle of an individual draft (GET /payments/drafts/{type}/{id}). Values: CREATED, PENDING, COMPLETED, DELETED. The draft stays in CREATED while the basket approval is awaiting SCA and only transitions to PENDING once approval has succeeded — PENDING therefore covers awaiting clearing and awaiting settlement for future-dated payments, never awaiting SCA.
• Per-draft basket (DraftApprovalStatus.status) — the per-draft entry inside a basket approval response (GET /payments/drafts/approve/{requestId}/status). Values: CREATED, PENDING, COMPLETED, FAILED. Mirrors the draft layer, with FAILED as a side path when the underlying payment couldn’t be completed (the draft itself recycles back to CREATED so it can be retried).
• Basket overall (ApprovalStatus) — the overall approval/SCA challenge status returned by both POST /payments/drafts/approve and the status endpoint. Values: AWAITING_APPROVAL, APPROVED, EXPIRED, DECLINED. Models the SCA challenge itself, not the resulting payments.
• Underlying payment (e.g. SeBankGiroResponse.status) — the eventual payment’s lifecycle, looked up via the payment-type-specific endpoint. Values: AWAITING_APPROVAL, PENDING, APPROVED, COMPLETED, FAILED, DECLINED, CANCELLED. The fully detailed view — drafts only surface the post-approval lifecycle (the underlying payment’s PENDING and COMPLETED); AWAITING_APPROVAL and APPROVED on the payment never appear at the draft layer because the draft is only handed off for execution after the basket has already been approved. Same-day vs future-dated transitions and explicit cancellation surface only on the payment endpoint.