Udviklere
Forta Pay API v1 · kontrakt 1.0.0-draft1 · sha256 660d0eda5644
Nye felter, nye enum-værdier og nye hændelsestyper er ikke brud — tolerér det ukendte. Et brud kommer som
/v2, og /v1 lever mindst 24 måneder derefter.
POST /payments/{id}/refund: nyt valgfrit felt external_ref, unikt pr. betaling uden tidsgrænse. Samme ref med samme beløb og invoice_effect svarer 200 med den eksisterende refund; et andet beløb eller en anden effekt svarer 409 refund_external_ref_conflict. Reversal.external_ref viser referencen.
Refusion ved kreditering (bag et slukket flag): POST/GET /creditors/{id}/refund-orders, GET …/{id}, POST …/{id}/cancel og POST …/{id}/allocations/{id}/receipt (altid fire øjne). Hændelserne refund_order.*. POST /invoices/{id}/credit med external_ref spejler kildens kreditnota — idempotent, også på en betalt faktura.
Bank Connect pr. fra-konto (bag et slukket flag): GET /creditors/{id}/debit-accounts/{id}/bankconnect samt POST …/activate, …/renew, …/revoke og …/account-data. Aktiveringskoden bruges én gang og gemmes aldrig.
GET /invoices: to nye filtre. exclude_status udelader en eller flere statusser (kommasepareret, fx draft; ukendt værdi svarer 422). shadow filtrerer på fakturaens shadow-felt; shadow=false skjuler skyggefakturaer.
POST /invoices/{id}/mark-paid: external_ref er unik pr. faktura. Samme reference og samme beløb er en gensendelse og svarer 200 med fakturaen som den står, uden en ny registrering, også med en ny Idempotency-Key. Et andet beløb svarer 409 external_ref_conflict. Uden external_ref er alt som før.
Leverandørbetaling (bag et slukket flag; slukket svarer alle ruterne 404): PUT /creditors/{id}/payees/{payeeRef}, PUT/GET …/debit-accounts (kanal, aftalestatus og godkendelsesform pr. fra-konto), GET …/approvers, POST/GET …/payment-orders med godkendelsesbevis, samt cancel, resume og resolve (altid fire øjne). Kræver licensen pay.supplier_payments tildelt kreditoren. Intet sendes til en bank eller partner.
Debtor.payment_profile: betalingsadfærd i tal (åbne og forfaldne fakturaer, andel betalt til tiden, gns. dage for sent, rykkere, fejlede træk, inkassosager, afdrag og indsigelser) og et beskrivende bånd green|yellow|red efter den offentliggjorte regel band-1 med reasons. Feltet findes KUN for debitorer med CVR; forbrugere får null. Skifter båndet, kommer hændelsen debtor.profile_changed. Båndet er en visning og må aldrig afgøre noget uden et menneske. Og invoice.updated fra en statusændring kommer nu højst én gang pr. faktura pr. transaktion, med details.sources.
Invoice.status_summary: én beregnet status pr. faktura (fase, kort dansk etiket, tone, rykker, inkasso, indsigelse, afdrag, pause, træk, levering og revision), uden fritekst og persondata. Feltet er additivt, og phase er en åben liste: ukendte værdier vises neutralt. Når en indsigelse, en betalingsmelding, en afdragsordning, et træk, et mandat, en rykker, en levering eller en inkassosag flytter statussen, kommer der én invoice.updated med details.changed, details.revision og details.source. POST /invoices/{id}/mark-paid har fået initiated_by (user|system, standard system) og actor_ref: en registrering fra en bruger går altid gennem fire øjne, når fire øjne er slået til.
POST /invoices på en live-konto: fakturaens indledende rykkerniveau sættes af Forta Pay, så rykkerforløbet altid følger renteloven. reminder_level_initial > 0 giver 403 reminder_level_platform_only; udeladt eller 0 virker som før, og interest_applies: false kan stadig sættes. Fordringer der allerede er rykket i FarPay, tages ind gennem POST /imports. Og PATCH /creditors/{id}/document-settings kræver nu en konto-bred nøgle med admin-scope for alle felter (før kun for branding, templates og collection_agency). Sandkassen er uændret.
POST /dunning-plans og PATCH /dunning-plans/{id} på en live-konto: rykkerplanen styres af Forta Pay, så den altid følger renteloven. Oprettelse og ændring af trin, dage, frister, gebyrer og rente giver 403 dunning_plan_platform_only; planens name kan stadig rettes. Sandkassen er uændret.
Beskrivelserne af DunningPlanCreate.collection_partner og CollectionCaseCreate.partner samt eksemplet på CollectionCase.partner: partnerkoden aftales med partneren. Ingen ændring i felter eller værdier.
To nye hændelser (webhook og /events): approval_request.created — en fire-øjne-anmodning er oprettet (fra API'et eller kreditorfladen); data.object er anmodningen som i approval_request.decided. Og debtor.paid_claim — debitor har på betalingssiden oplyst at have betalt («Jeg har betalt»); data.object er det nye skema PaidClaim. Det er en påstand, ikke en betaling: saldoen er uændret. Additivt — et abonnement på * eller approval_request.* får den nye hændelse med.
CollectionPartnerUpdate.partner_event_id (valgfri): partnerens eget hændelses-id. Samme id igen registreres ikke igen (genlevering); samme id med andet indhold giver 422 partner_event_reused.
PUT /reconciliation/consumer-snapshots/{date}: hver række kan bære det tidligere systems dom — previous_system_status (paid, marked_paid, bs_scheduled, open eller null), previous_system_paid_oere og previous_system_seen_at. Felterne er valgfri som gruppe: udeladt betyder «ikke sendt»; sendes ét, skal alle tre med (422). Et billede uden felterne behandles og hashes som før.
Sikkerhed — to handlinger mere kræver scope admin (før write), som i kreditorfladen: POST /legal-holds/{id}/release (stadig også rettigheden privacy:erase) og POST /reenrollment-campaigns (også med dry_run). En write-nøgle får 403 insufficient_scope.
Sikkerhed — strammere adgang (ikke additivt). ① POST /creditors/{id}/settlement-account-changes/{changeId}/approve svarer nu altid 403 approval_requires_person: en ny afregningskonto godkendes af en administrator i kreditorfladen (Indstillinger → Kreditor), ikke med en API-nøgle. To nøgler er ikke to personer. …/reject er uændret. ② Seks handlinger kræver nu scope admin (før write), som i kreditorfladen: POST /collection-cases, /reenrollment-campaigns/{id}/apply, /imports/{id}/apply, /foreign-receipts/{id}/resolve, /legal-holds/{id}/review og /payments/{id}/refund. ③ Fire øjne: POST /invoices/{id}/mark-paid svarer 202 med en ApprovalRequest (action: api-mark-paid), når beløbet er mindst kreditorens grænse eller hele restbeløbet; refusionens grænse gælder nu det samlede refunderede på betalingen. Med fire øjne slået fra er ③ uændret.
POST /invoices/{id}/credit for en kreditor i skygge: en delvis kreditering af en faktura med en planlagt opkrævning svarede 409 creditor_in_shadow. Nu aflyses opkrævningen, der planlægges ingen ny i skygge, og kaldet svarer 200 som en fuld kreditering. Kaldet sender, bogfører og opkræver intet.
Kun en beskrivelse: POST /invoices/{id}/credit (kreditering uden dokument) skrives aldrig i kreditorens regnskabssystem — den spejler en kreditnota der er udstedt og bogført dér. Skal Forta Pay udstede og bogføre kreditnotaen, er vejen POST /invoices/{id}/credit-notes. Adfærden er uændret.
Kun beskrivelser: kontakten hedder nu «Forta Pay», og beskrivelserne nævner ikke længere andre udbydere end som kilde ved skiftet. Ingen operationer, parametre, felter eller enum-værdier er ændret.
POST /charges/{id}/stop stopper nu også et varslet MobilePay-træk via QuickPay: svaret er stop.status = requested, og opkrævningen bliver cancelled, når QuickPay har bekræftet annulleringen. Fristen er dagen før betalingsdagen kl. 23.00 (409 charge_stop_deadline_passed). Et kort-træk kan stadig ikke stoppes — det hæves i samme kald.
Fire øjne gælder også kreditnotaen: har kreditoren slået fire øjne til, svarer POST /invoices/{id}/credit-notes 202 med en ApprovalRequest (action: api-credit-note), og kreditnotaen udstedes og sendes først når en anden person har godkendt den. Slået fra er svaret uændret (201). De fem kreditnota-operationer har fået operationId.
Hændelsen approval_request.decided: når en fire-øjne-anmodning er godkendt, afvist eller trukket tilbage (også når fire øjne slås fra med åbne anmodninger), får I præcis én hændelse (webhook og /events) med anmodningen i data.object — samme form som GET /approval-requests/{id}. Godkendt: handlingen er udført, og result_id er det den skabte. Afvist: intet er udført, og decision_note er grunden. Trukket tilbage (withdrawn): intet er udført. I behøver ikke længere at polle.
Fire øjne på API'et: har kreditoren slået fire øjne til (i kreditorfladen), svarer POST /payments/{id}/refund (fra kreditorens beløbsgrænse), POST /invoices/{id}/credit, POST /invoices/{id}/cancel og POST /collection-cases nu 202 med en ApprovalRequest i stedet for at udføre handlingen. En anden person på kreditoren godkender den; først da udføres den (én gang). Følg den med GET /approval-requests/{id} (result_id når den er godkendt). Et kald der ville fejle, får samme fejl som før. Slået fra (standarden) er alt uændret.
Rykkerstyring: GET og PATCH /creditors/{creditorId}/dunning-control. Kreditoren tænder og slukker selv sine rykkere (admin-nøgle); dry_run: true ændrer intet og viser i preview, hvilke rykkere en tænding ville planlægge. approval er each_reminder (hver rykker sendes først, når I har godkendt den) eller automatic; automatic svarer 409 dunning_automation_locked, så længe Forta Pay ikke har åbnet for automatiske rykkere (approval_locked).
GET /invoices/{id}/reminder-evidence (format=json|pdf): rykkerbeviset — hver skrivelse, hver leverance med post-/mailjournalens række og leverandørens kvitteringer, og hjemlen pr. gebyr og rente. reference er sha256 af beviset og er den samme i JSON og PDF; ?reference= svarer 409 evidence_changed, hvis forløbet har ændret sig siden. reconciliation afstemmer journalen mod fakturaen, med eftergivne restgebyrer og -renter (write_offs) for sig.
PATCH /creditors/{id} FLETTER nu distribution_defaults: felter der ikke er med, bevares; et felt sat til null fjernes (og får standarden). Før erstattede en PATCH hele objektet, så fx en PATCH med kun sender_name tavst satte payment_receipt: false tilbage til true. Kvitteringsmailen (payment_receipt) sendes nu også, når debitor betaler og tilmelder sig på samme side (purpose: pay_and_mandate).
/openapi.json er nu selve kontrakten (den samme som API-dokumentationen viser): med securitySchemes, tags, fejlsvar og et operationId på hver operation (fx create_invoice). Før var det en autogenereret beskrivelse uden godkendelse og fejltyper. Fejlsvarets type peger på /errors/{code} på API-værten, som nu svarer (før: en adresse der gav 404). code er uændret og stadig det man bygger på.
Recovery og undtagelseskøen: GET /creditors/{creditorId}/recovery giver indbetalt efter forfald pr. mekanisme (inkasso, afdrag, SMS, betalingslink, rykker 3/2/1, påmindelse), afstemt mod alt indbetalt (reconciled), samt aldersfordeling og DSO. GET /creditors/{creditorId}/exceptions lister fakturaer hvor der intet sker, med grundene og rykkermotorens port.
Rykkerværnet: en faktura der reelt er betalt — FarPay-betalt i skiftets import, lukket ved skiftet, eller penge Forta Pay har modtaget som fremmed kvittering — rykkes aldrig og sendes aldrig til inkasso, uanset om regnskabet stadig viser den åben. GET /dunning-runs/next har den nye grund paid_elsewhere i not_planned; POST /collection-cases og POST /collection-cases/{caseId}/partner-update (handed_over) svarer 409 invoice_paid_elsewhere med paid_signal.
Kaldeloft pr. API-nøgle: 600 kald pr. 60 s (glidende, fælles for alle servere) og højst 4 samtidige (flere venter kort i kø). Alle svar bærer RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset og RateLimit-Policy; over loftet svares 429 rate_limited med Retry-After, og kaldet er ikke udført. Et idempotent replay genafspiller nu også Location, Content-Disposition m.fl. fra en fast liste. Sandbox-simuleringen bank_day_closed er bygget (var 501): target_id er en dato, der lukkes i kontoens bankdagskalender, og planlagte BS-træk planlægges om.
Kreditnotaen som dokument: POST /invoices/{id}/credit-notes udsteder en kreditnota pr. linje (lines) eller beløb (amount) med eget nummer i kreditorens nummerserie, PDF (GET /credit-notes/{id}/pdf), OIOUBL CreditNote (GET /credit-notes/{id}/oioubl) og udsendelse på fakturaens kanal. settlement er påkrævet: credit_balance (tilgodehavende) eller refund (pengene tilbage via refund-vejen). Nye: GET /invoices/{id}/credit-notes, GET /credit-notes/{id}, hændelsen credit_note.created, e-conomic-koblingens credit_note_ledger_account og credit_note_vat_ledger_account og bilagstypen credit_note. POST /invoices/{id}/credit er uændret.
Kreditoren har debtor_attribute_source (PATCH /creditors/{id} og i svaret): pr. debitorfelt (name, address, type, cvr, email, phone, ean) hvem der er sandheden, når en import møder en debitor Pay allerede har. existing: debitoren som den står vinder, og rækken er exists_identical med noten kilde_eksisterende:<felt>; stop: exists_different med diff:<felt>. Standard: existing for navn, adresse og type. Importen overskriver aldrig en eksisterende debitor.
Overgangsafstemningen (POST /reconciliations) har fem nye koder i ReconciliationItem.code: afventer_bogfoering_i_kladde og kladde_ubogfoert_over_30_dage (indbetalingen ligger ubogført i en kassekladde i e-conomic), markeret_betalt_i_farpay_aaben_i_economic, kortafregning_undervejs og bs_aftale_hos_tidligere_dataleverandoer — alle forventet. Det kreditor/bogholderen skal rette, står samlet i sources.kreditor_handling.
MobilePay kun til privatkunder (Vipps MobilePay's vilkår): POST /hosted-sessions til en debitor der er en virksomhed (type: business, cvr eller ean) svarer 422 mobilepay_kun_privat når allowed_rails kun er mobilepay; sammen med andre rør falder MobilePay bort og står i dropped_rails med samme kode.
Afregningskontoen på en live-kreditor ændres med fire øjne: PATCH /creditors/{id} med en ny settlement_account svarer 202 med en ventende settlement_account_change, og kontoen er uændret, til en ANDEN konto-bred admin-nøgle godkender med POST /creditors/{id}/settlement-account-changes/{changeId}/approve (samme nøgle: 409 second_approver_required). Nye: …/reject og GET …/settlement-account-changes. Alle kreditorens administratorer får en mail. Ændringen udløber efter 7 dage. Sandbox: straks, som før. Et FI-kreditornr. kan kun stå på én live-kreditor (409 fi_creditor_number_in_use).
branding.color skal have en kontrast på mindst 4,5:1 mod hvid (WCAG AA); en lysere farve (fx #FFEE00) afvises med 422 validation_failed. En farve gemt før bruges ikke på PDF og mail (husets standardfarve i stedet). Faktura-PDF'en har nu en QR-kode til betalingslinket.
distribution_defaults.payment_receipt (boolean, standard true): kvitteringsmail til debitor, når en betaling på betalingssiden (kort/MobilePay) er gennemført. Kun e-mail; kreditor kan slå den fra.
Hændelsen mandate.deregistration_failed: en Betalingsservice-afmelding kunne ikke dannes og nåede ikke BS. Tilmeldingen er afmeldt hos jer, men stadig aktiv hos BS; status_reason er deregistration_failed, og details.reason siger hvorfor. Ret årsagen og afmeld igen.
Kontrakten følger nu appen: cursor/limit på GET /invoices/{id}/reminders og /timeline; kroppen WebhookEndpointUpdate på PATCH /webhook-endpoints/{id}; HostedSessionCreate.language er da|en|fo|kl; CollectionPartnerUpdate.status tager ikke none/ready/withdrawn (dem sætter Forta Pay selv). distribution.channels er email|sms|eboks|letter|ean; interest på PATCH /dunning-plans/{id} har sine felter; payment.amount er påkrævet i POST /collection-cases/{id}/partner-update. HostedSession.success_url/cancel_url kan være null. servers: sandbox og live deler api.fortapay.dk — nøglen afgør miljøet. Fejl der kan komme på alle kald, er beskrevet ét sted. Ingen adfærd i API'et er ændret.
HostedSession.dropped_rails: de betalingsrør der faldt fra ved oprettelsen, med rail, code og detail — [] når intet faldt fra.
Invoice.shadow betyder nu præcist «Forta Pay opkræver ikke denne faktura»; overtagne fakturaer svarer shadow: false og udsender invoice.updated ved aktiveringen. mark-paid tager imod betalingen uanset ejerskab.
POST /payments/{id}/withdraw-registration virker nu også på en enlig registrering (fx en kasseretur af din egen mark-paid), ikke kun på en mulig dublet.
Payment.external_ref og filteret GET /payments?external_ref=.
Gentilmeldingslinkets standardlevetid (expires_after_days) er 28 dage (før 14).
POST /invoices/{id}/dunning/advance (ryk et trin frem, med dry_run) og GET /invoices/{id}/installment-plan/calculation (beregn en afdragsordning). Nye hændelser: hosted_session.payment_authorized, .authorization_aging, .authorization_cancelled. Import.row_errors[].messages.
InvoiceCreate.attachments (bilag som base64). ReenrollmentCampaign.mobilepay_mode (reenroll|partner_switch). Skift uden FarPay: previous_system på kreditoren (farpay|regnskabssystem|andet), source_cursor_at_switch og POST /cutovers/{id}/attest-change-window. I PUT /reconciliation/consumer-snapshots/{date} må fakturanr. og kundenr. være tekst (fx Uniconta), og 409 consumer_not_registered er ny.
GET /hosted-sessions med filtrene creditor_id, debtor_id, purpose, status. GET /debtors?has_active_mandate=. Payment.invoice_external_ref. Uniconta-integrationen: /creditors/{id}/integrations/uniconta (opret, hent, ret, verify, webhook, PDF).
