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 with only a name
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.

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.

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.

Sender Account Access

When senderAccountId is supplied on create (POST) or update (PATCH), 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.

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.

Signing Basket Flow

List Drafts

GET /payments/drafts

Returns all drafts 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.

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 aligns 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.