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.

KID payments in Norway

A KID (kundeidentifikasjon) is a structured Norwegian payment reference, often printed on an invoice. The recipient uses it to match an incoming payment to the correct invoice or customer. It is separate from the recipient’s bank account number (BBAN).

KID payments are supported only when both the sender and recipient accounts are Norwegian. For a Norwegian (NOK) domestic credit transfer draft between Norwegian accounts, set kidNumber when the recipient provides a KID. Send it as a string so any leading zeroes are preserved. The direct-initiation endpoint does not expose a KID field; use a draft to make a payment with a KID.

Whether a KID is required depends on the recipient’s account. Check the draft’s validation result: KID_REQUIRED means you need to provide one, INVALID_KID means you need to correct it, and KID_NOT_SUPPORTED means you should clear it or choose a different recipient account. See Validation Requirements for details.

When available on the resulting transaction, the KID reference is exposed as additionalInformation.kidNumber in Transactions v2. The value remains a string, preserving leading zeroes. The key is omitted when no non-empty KID reference is available; use this structured field rather than title or message to read the payment reference.

Validation Requirements

Before a domestic credit transfer draft can be approved, it must pass validation. Every create, update, and get response includes isValid, which tells you whether the payment details are valid. Because availability for approval is eventually consistent, also wait for the draft to appear as valid in GET /payments/drafts before calling 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:

For KID-related results, set or correct kidNumber in response to KID_REQUIRED or INVALID_KID. For KID_NOT_SUPPORTED, clear kidNumber or select a receiver account that accepts KID payments.

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