Spring til indhold
Forta Pay
English Log ind Book en samtale

Reference

Betalinger og tilbageførsler

Forta Pay API v1

7 operationer

Modtagne betalinger (filtre: invoice_id, debtor_id, rail, settlement_id, received_after)

GET /payments

Parametre

cursor

query · string · valgfri

limit

query · integer · valgfri

rail

query · string · valgfri

invoice_id

query · string · valgfri

debtor_id

query · string · valgfri

settlement_id

query · string · valgfri

status

query · string · valgfri

received_after

query · string (date-time) · valgfri

updated_after

query · string (date-time) · valgfri

K5: alle lister har updated_after

external_ref

query · string · valgfri

TILFØJET (pay-sikkerhed3 §8). Kun betalinger med præcis denne external_ref (klientens egen reference fra mark-paid) — så en registrering kan efterprøves på klientens nøgle

possible_duplicate

query · boolean · valgfri

true → kun betalinger der LIGE NU indgår i en uafgjort «mulig dublet»: en manuel registrering + automatisk betaling (samme faktura, beløb og valuta, højst 14 dage imellem) eller samme FI-post i to filer. Samme prædikater som kreditorfladens fane. false → de øvrige

Svar

200

OK · Page

curl
curl -X GET https://api.fortapay.dk/v1/payments \
  -H "Authorization: Bearer $FP_KEY"

Hent betaling (payment_method er ét entydigt objekt)

GET /payments/{paymentId}

Parametre

paymentId

path · string · påkrævet

Svar

200

OK · Payment

curl
curl -X GET https://api.fortapay.dk/v1/payments/{paymentId} \
  -H "Authorization: Bearer $FP_KEY"

Refundér (hel/delvis). Kort/MobilePay via PSP; BS/LS/FI/manuel kun som registrering (`mode: external`) (scope admin — som i kreditorfladen; pay-sikkerhed2 T6-10)

POST /payments/{paymentId}/refund

mode: external (BS/LS/FI og manuelle registreringer): kreditor har SELV betalt tilbage fra egen konto. Forta Pay flytter ingen penge (B1) — svaret er 201 med en Reversal i status: completed, settlement_id: null, og betaling og faktura er opdateret i samme kald. Samme regler for beløb (422 refund_exceeds_payment) og invoice_effect. En betaling der gik gennem Forta Pays PSP → 422 refund_mode_not_allowed; uden mode på en ikke-PSP-betaling → 422 refund_not_supported_for_rail.

mode: psp (standard): svaret er 201 med en Reversal i status: pending — udfaldet kommer fra PSP'en senere (reversal.completed / reversal.failed). Højst én refund i gang pr. betaling (409 refund_in_progress). Beløbet må ikke overstige det der endnu ikke er refunderet (422 refund_exceeds_payment). invoice_effect er påkrævet: credit = kreditnota for samme beløb (fakturaen forbliver lukket); reopen = fakturaen genåbnes hvis der er noget at skylde bagefter, og rykkerforløbet genoptages. Går PSP'ens svar tabt, sendes refunden ALDRIG igen automatisk: reversalen får review_reason (reversal.review_required) og spærrer en ny refund på betalingen, til den er afklaret.

Fire øjne: har kreditoren slået fire øjne til, og er det samlede refunderede på betalingen inkl. dette beløb mindst kreditorens grænse (pay-sikkerhed2 T6-6: kumuleret, ikke pr. kald), svarer kaldet 202 med en ApprovalRequest (status: pending) i stedet for at refundere. En ANDEN person på kreditoren godkender den i kreditorfladen; først da oprettes reversalen (result_id). Kaldet prøves først: et kald der ville fejle nu, får samme fejl som uden fire øjne. En åben anmodning på samme betaling → 409 four_eyes_pending (approval_request_id). Slået fra (standarden) er svaret uændret.

external_ref (valgfri, pay-refund-dedup): kildens EGEN reference for refunden (fx kassens retur-id). Unik pr. betaling, uden tidsgrænse — Idempotency-Key gælder kun 24 t. Samme external_ref + samme beløb og invoice_effect → 200 med den EKSISTERENDE Reversal (ingen ny reversal, ingen ny hændelse, ingen fire-øjne-anmodning; også når betalingen siden er blevet refunded). Samme external_ref + andet beløb eller anden invoice_effect → 409 refund_external_ref_conflict (reversal_id, registered_amount, registered_invoice_effect). En failed refund tæller ikke: samme ref kan prøves igen. Uden external_ref: uændret (to ens kald med hver sin nøgle er to refunds). To samtidige kald med samme ref giver én refund.

Parametre

paymentId

path · string · påkrævet

Idempotency-Key

header · string (uuid) · påkrævet

Obligatorisk på alle POST/PATCH/DELETE. Lever 24 timer.

Krop · RefundRequest

amount

Money · påkrævet

reason

string · valgfri

invoice_effect

string · påkrævet

Påkrævet, ingen standard. credit = kreditnota for refundbeløbet MINUS en eventuel overbetaling (refunden dækker først overskuddet; 1.200 på 1.000 + refund 200 = saldo 0 uden kreditnota); fakturaen forbliver lukket. reopen = refunden genåbner saldoen; rykkerforløbet genoptages hvis der er noget at skylde.

credit · reopen

mode

string · valgfri

psp = Forta Pay sender pengene tilbage via PSP'en (kun kort/MobilePay betalt gennem Forta Pay). external = kreditor HAR selv betalt tilbage uden om Forta Pay (BS/LS/FI, manuelle registreringer): en registrering, ingen overførsel (B1); reversalen er completed straks og indgår ikke i nogen afregning. Forkert valg → 422 (refund_not_supported_for_rail / refund_mode_not_allowed).

psp · external

external_ref

string · valgfri

Kildens egen reference for refunden (fx kassens retur-id). Unik pr. betaling uden tidsgrænse: samme ref + samme beløb og invoice_effect → 200 med den eksisterende Reversal; andet beløb/effekt → 409 refund_external_ref_conflict. Uden: kun Idempotency-Key (24 t).

Svar

200

OK · Reversal

201

OK · Reversal

202

Fire øjne: anmodningen (202 = oprettet, intet udført endnu) · ApprovalRequest

409

`refund_in_progress` · `payment_not_refundable` · `four_eyes_pending` · `refund_external_ref_conflict` (samme `external_ref`, andet beløb eller anden `invoice_effect`) · Problem

422

Fejl (RFC 9457) · Problem

curl
curl -X POST https://api.fortapay.dk/v1/payments/{paymentId}/refund \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "amount": {
    "amount": 0
  },
  "invoice_effect": "credit"
}
JSON

Træk en MANUEL registrering tilbage — «samme betaling» i en mulig dublet, eller en enlig registrering (fx kasseretur)

POST /payments/{paymentId}/withdraw-registration

Modpostering (Reversal.kind = registration_withdrawn), ingen penge flyttes og intet PSP-kald. Betalingen går matched → reversed. Fakturaen genåbnes KUN hvis saldoen efter tilbageførslen er > 0 (Reversal.reopens_invoice siger om den gjorde); ellers forbliver den paid og meldes som invoice.updated. Kun en manuel registrering (payment_method.source = external) — en betaling Forta Pay selv har set (BS, kort, FI) trækkes aldrig tilbage ad denne vej (409 not_a_registration). To former: indgår registreringen i en markering (mulig dublet), står afgørelsen på PARRET (duplicate_decisions); automatic_payment_id er påkrævet når den indgår i flere par. Indgår den i INGEN markering (fx CRM's kasseretur af sin egen mark-paid), er det samme modpostering uden par-afgørelse. Kommer fakturaen fra et regnskabssystem, og viser det sidst sete restbeløb dér MINDRE end det Pay nu vil opkræve, lægges fakturaen straks i hold (rykkerpause + manuel opkrævning, kilde_saldo_faldet). Fejl: 409 not_a_registration · not_a_possible_duplicate (kun med automatic_payment_id der ikke er registreringens modpart) · registration_already_withdrawn; 422 validation_failed.

Parametre

paymentId

path · string · påkrævet

Idempotency-Key

header · string (uuid) · påkrævet

Obligatorisk på alle POST/PATCH/DELETE. Lever 24 timer.

Krop · RegistrationWithdraw

reason

string · påkrævet

Hvordan ved du at det er samme betaling? Må ikke være tom

automatic_payment_id

string · valgfri

Den automatiske betaling i parret. Påkrævet når registreringen indgår i flere par

Svar

201

OK · Reversal

404

Fejl (RFC 9457) · Problem

409

Fejl (RFC 9457) · Problem

422

Fejl (RFC 9457) · Problem

curl
curl -X POST https://api.fortapay.dk/v1/payments/{paymentId}/withdraw-registration \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "reason": "…"
}
JSON

«To betalinger»: afvis en mulig dublet på den postering markeringen står på

POST /payments/{paymentId}/dismiss-duplicate

To slags par: registration (den AUTOMATISKE betaling mod en manuel registrering af samme beløb) og resent (den SENERE af to ens FI-poster meldt i to forskellige 0602-filer). paymentId er den automatiske hhv. den senere postering. Afgørelsen gælder PARRET, ikke betalingen: en registrering skrevet ind senere markeres igen. Bogføringen røres ikke. counterpart_payment_id er påkrævet når betalingen indgår i flere par. Svarer med betalingen, hvor afgørelsen står i duplicate_decisions. Fejl: 409 not_a_possible_duplicate · duplicate_already_dismissed; 422 validation_failed.

Parametre

paymentId

path · string · påkrævet

Idempotency-Key

header · string (uuid) · påkrævet

Obligatorisk på alle POST/PATCH/DELETE. Lever 24 timer.

Krop · DuplicateDismiss

reason

string · påkrævet

Hvorfor er det to forskellige betalinger? Må ikke være tom

counterpart_payment_id

string · valgfri

Den anden halvdel af parret. Påkrævet når betalingen indgår i flere par

Svar

200

OK · Payment

404

Fejl (RFC 9457) · Problem

409

Fejl (RFC 9457) · Problem

422

Fejl (RFC 9457) · Problem

curl
curl -X POST https://api.fortapay.dk/v1/payments/{paymentId}/dismiss-duplicate \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "reason": "…"
}
JSON

Match en umatchet betaling (fx FI uden gyldig reference) til en faktura

POST /payments/{paymentId}/match

Beløbsværn (FI-2): er betalingen STØRRE end fakturaens rest, afvises matchet med 409 amount_exceeds_balance, medmindre allow_overpayment: true — så går fakturaen paid med negativ saldo, og invoice.overpaid udsendes. Kreditor betaler selv overskuddet tilbage fra egen konto (B1).

Parametre

paymentId

path · string · påkrævet

Idempotency-Key

header · string (uuid) · påkrævet

Obligatorisk på alle POST/PATCH/DELETE. Lever 24 timer.

Krop · object

invoice_id

string · påkrævet

allow_overpayment

boolean · valgfri

Tillad at betalingen overstiger restbeløbet (overbetaling)

Svar

200

OK · Payment

curl
curl -X POST https://api.fortapay.dk/v1/payments/{paymentId}/match \
  -H "Authorization: Bearer $FP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "invoice_id": "…"
}
JSON

Tilbageførsler (BS-indsigelse/tilbageførsel, chargeback, refund, bank-reimbursement)

GET /reversals

Parametre

cursor

query · string · valgfri

limit

query · integer · valgfri

payment_id

query · string · valgfri

invoice_id

query · string · valgfri

updated_after

query · string (date-time) · valgfri

K5: alle lister har updated_after

Svar

200

OK · Page

curl
curl -X GET https://api.fortapay.dk/v1/reversals \
  -H "Authorization: Bearer $FP_KEY"