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 Bank Giro and SE Plus Giro drafts may omit draftId (the server generates one).
2. Update the draft incrementally as payment details become available
3. Check availability — poll GET /payments/drafts until the draft appears with isValid: true (why this matters)
4. 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 guides).

Drafts are approved through the Signing Baskets batch approval flow.

PATCH updates fields that are present in the request body with non-empty values; omitted fields are left unchanged. The exception is kidNumber on domestic credit transfer drafts: omit it or send null to keep the existing value, and send an empty string ("") to clear it.

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 payment-type guides.

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.

Payment-Type Draft Guides

Drafts share the lifecycle and signing-basket approval flow described here. Choose a payment type for its fields, validation rules, and examples:

• Domestic Credit Transfer Drafts — national transfers in Denmark, Norway, and Sweden, including KID payments in Norway.
• SE Bank Giro Drafts — Swedish Bank Giro payments.
• SE Plus Giro Drafts — Swedish Plus Giro payments.

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:

Wait for draft availability

Draft creation and updates are processed through an event-based system. The draft list and signing-basket approval flow are eventually consistent with the create and update responses. A successful 201 Created — even with isValid: true — does not mean the new draft is already visible to the approval flow.

Before approving, poll GET /payments/drafts until every draftId in the intended basket appears in the list with isValid: true. Match by draftId; the list may include other drafts, including invalid ones. Use bounded retries with a delay or backoff rather than a fixed sleep or an unbounded loop. If the drafts do not appear, report that approval is not ready instead of submitting the batch.

If approval immediately after creation returns 404 NOT_FOUND, no drafts in that batch were approved. Recheck the list and submit a new approval request with a fresh requestId only after all selected drafts appear as valid. If an ID still does not appear after your retry window, verify the ID and caller’s access rather than treating every 404 as a propagation delay. Poll GET /payments/drafts/approve/{requestId}/status after approval, not to check whether a newly created draft is available.

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. Before submitting, wait for each draft to appear in the list with isValid: true.

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 while the request is progressing, but FAILED is a permanent outcome for that specific requestId — it does not recycle back to CREATED. The draft itself becomes approvable again and can be retried, but only its own live view (GET /payments/drafts/{type}/{id} or GET /payments/drafts) reflects that; the retry is tracked under a new requestId with its own independent status.
• 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.