Opsætning af Stripe-integration

Opsætning af integrationen

Du kan hurtigt forbinde din eksisterende Stripe-konto med Fenerum, eller oprette en ny Stripe-konto for at begynde at acceptere betalinger fra dine kunder i Fenerum.

Forudsætninger

Du skal have opsat din kortbetalingskonto og gebyrkonto i Fenerum, når du konfigurerer dit regnskabssystem.. Du kan ikke bruge Stripe-integrationen, før dette er gjort.

Tilslutning

Gå til integrationsindstillingerne i Fenerum og find Stripe-integrationen i "Betalinger"-sektionen.

Her skal du klikke enten på "Opret ny Stripe-konto" eller "Opsæt eksisterende konto". Dette vil omdirigere dig til Stripe, hvorfra du enten kan forbinde din eksisterende Stripe-konto, eller du kan oprette en ny, hvis du ikke allerede har en.

Når du har gennemført processen, vil du blive omdirigeret tilbage til Fenerum, og integrationen vil være opsat og klar til brug.

Tilføjelse af et betalingskort

Nu skal du knytte kreditkortdata til din kunde. Fenerum gemmer ikke følsomme kreditkortdata, så kortet skal oprettes i Stripe, og deres id skal videregives til Fenerum.

Der er to måder at gøre dette på:

• Hvis du håndterer kortoprettelsen i din backend, skal du kun videregive Stripe PaymentMethod ID til Fenerum ved hjælp af API-opkald: Opret et kort ved hjælp af API. En detaljeret guide til integration af Stripe og Fenerum med din applikation kan findes i afsnittet Registrer betalingskort i din applikation nedenfor.
• Du kan også lade Fenerum tage sig af det. For at gøre dette, henvises til denne guide.

Import af eksisterende data

Hvis du ønsker at importere eksisterende kreditkortdata til Fenerum, følg denne guide.

Registrer betalingskort i din applikation

Der er flere måder at registrere dine kunders betalingskort med Fenerum. Den mest bekvemme og enkle metode bruger et dedikeret link, som du kan generere og sende til din kunde eller omdirigere din bruger til. For at læse mere om dette emne, besøg venligst denne guide.

Når omdirigering af brugere fra din applikation til Fenerum ikke er din foretrukne måde at indsamle betalingskortdata på, følg venligst trinene i denne guide.

Opret en Setup Intent i Stripe

Før du viser betalingskortregistreringsformularen, skal du registrere en Setup Intent i Stripe. For en detaljeret beskrivelse af understøttede parametre, henvises til Stripe API guide.

Responsdataene fra Setup Intent oprettelsesendpointet indeholder client_secret feltet, som vil blive brugt til at bekræfte betalingskortdata med Stripe.

{  
    "id": "seti_1Iuxae2eZvKYlo2CbFMPr2HY",  
    ...  
    "client_secret": "seti_1Iuxae2eZvKYlo2CbFMPr2HY_secret_JY3ikTrSjRl5hcEgfCvE0MMQUpCrk5s",  
    ...  
}

Vis betalingskortformularen i din webapplikation

Efter at have opnået client_secret attributet af en Setup Intent er vi klar til at vise betalingskortregistreringsformularen. Vi vil bruge Stripe Elements biblioteket fra Stripe.js til at gøre det tunge løft. Eventuelle yderligere autorisationstrin, herunder 3D secure, håndteres automatisk af biblioteket.

<div class="sr-form-row">  
  <label>  
    Betalingsdetaljer  
  </label>  
  <div class="sr-input sr-element sr-card-element" id="card-element">  
    <!-- Et Stripe-kortelement vil blive indsat her. -->  
  </div>  
</div>  
<div class="sr-field-error" id="card-errors" role="alert"></div>  
<button id="submit">Link dit kort til din konto</button>

var stripe = Stripe(publicKey);  
var elements = stripe.elements();  
var card = elements.create("card");  
var button = document.getElementById("submit");  
  
card.mount("#card-element");  
  
button.addEventListener("click", function(event) {  
    event.preventDefault();  
  
    stripe  
      .confirmCardSetup(clientSecret, {  // client_secret fra det forrige trin  
        payment_method: {  
          card: card,  
          billing_details: { name: "John Smith" }  
        }  
      })  
      .then(function(result) {  
        if (result.error) {  
          var displayError = document.getElementById("card-errors");  
          displayError.textContent = result.error.message;  
        } else {  
          // Betalingsmetoden blev succesfuldt opsat.  
          registerNewPaymentCard(  
              result.setupIntent.payment_method  
          );  
        }  
      });  
  });  
};

Et komplet eksempel på en front-end applikation er tilgængelig i dette repository.

Registrer betalingskort i Fenerum

registerNewPaymentCard funktionen, der blev brugt i kodeeksemplet fra det forrige trin i denne guide, skal sende det nyligt oprettede Payment Method ID til backenden af din applikation, som skal oprette et nyt Payment Card objekt i Fenerum ved hjælp af API'et.

POST /api/v1/paymentcards/  
Authorization: Token XXX  
Content-Type: application/json  
X-Client-System: MyAwesomeCRM  
X-User: jsmith  
  
{  
    "account": "<Account.uuid>",  
    "gateway": "stripe_new",  
    "token": "<Payment Method ID>"  
}

(Valgfrit) Håndtering af udløbne autorisationer

Afhængigt af den specifikke opsætning af et betalingskort, kan den automatiske betalingsautorisation, der er givet af kortindehaveren, udløbe. Der er to måder at håndtere denne situation på:

• Fenerum sender en e-mail til modtagerne af kontoen, der ejer dette betalingskort. Beskeden indeholder et link til en dedikeret betalingswebsite i Fenerum. Du kan vælge denne adfærd - kontakt gerne vores Kundesupport for at opsætte det.
• Fenerum underretter din applikation om behovet for autorisation, og din applikation håndterer det i sin brugergrænseflade.

Hvis du foretrækker at håndtere udløbne autorisationer i din applikation, skal du aktivere payment.authentication_required Webhook. Når din applikation modtager det, skal du underrette din kunde og bede ham om at gå over til din betalingsforsøgsside.

Før du viser siden, skal du opnå client_secret attributet af den mislykkede Payment Intent ved at hente denne Payment Intent. Identifikatoren for dette objekt er tilgængelig i webhook-dataene i payment_gateway_id nøglen.

For at udløse autorisationsprocessen vil vi igen bruge Stripe.js biblioteket.

var button = document.getElementById("submit");  
  
button.addEventListener("click", function(event) {  
    var stripe = Stripe(publicKey);  
  
    stripe  
        .handleCardPayment(clientSecret, {  // client_secret fra det forrige trin  
            payment_method: paymentMethodId,  // setupIntent.payment_method opnået i et af de forrige trin  
            setup_future_usage: "off_session"  
        })  
        .then(function (result) {  
            if (result.error) {  
                alert(result.error.message);  
            } else {  
                // autorisation og betaling forsøgt igen med succes  
            }  
        });  
});

Tillykke! Du kan bruge dette nye betalingskort som en betalingsmetode for dine kunders abonnementer. 🙂

SCA

Fra september 2019 vil en ny regulering kaldet Strong Customer Authentication (SCA) kræve, at virksomheder i Europa anmoder om yderligere godkendelse for online betalinger.

For Fenerum betyder dette, at betalinger med kort udstedt af europæiske banker kan kræve yderligere godkendelse (i de fleste tilfælde vil dette være 3-D Secure mekanismen).

I sådanne tilfælde vil Fenerum sende en e-mail med link til manuel bekræftelse af transaktionen, og du er ikke forpligtet til at gøre noget på den del.

Denne regulering kræver også yderligere bekræftelse, når kortdetaljer gemmes til fremtidig brug. Hvis du bruger Fenerum link til at indhente kortdetaljer, er du ikke forpligtet til at gøre noget, da den opdaterede formular vil understøtte 3-D Secure på kortindtastningsformularen.

Krævede ændringer

Kun hvis du bruger Fenerum API til at tilføje kort ved hjælp af Stripe token, skal du opdatere din integration for at håndtere Stripe SetupIntent i stedet for Card Token.
For detaljer om, hvordan du migrerer, henvises til Stripe dokumentation.

Fra Fenerums synspunkt skal du ændre din brug af PaymentCard create API-opkaldet.

Du skal sende Stripe PaymentMethod.id på tokenfeltet og sætte gateway til "stripe_new".

Eksempel på gammel payload:

{  
"account": "2a79956a-21fa-429c-b3d5-8e38c5e34afb",  
"gateway": "stripe",  
"token": "card_1EidxPFXVCQFEes0L0YQxWJy"  
}

Eksempel på ny payload:

{  
"account": "2a79956a-21fa-429c-b3d5-8e38c5e34afb",  
"gateway": "stripe_new",  
"token": "pm_1F9rgdFXVCQFEes0oaYqf8HO"  
}

Note om bagudkompatibilitet

Den gamle token vil stadig være understøttet af Fenerum (med gateway-typen 'stripe'), men du skal forvente, at hver første betaling ved hjælp af kort registreret med den vil kræve 3-D secure godkendelse i stedet for at autorisere det under kortgemning.

Det samme gælder for gamle kort, du skal forvente, at hver første betaling efter den 14. september vil kræve 3-D secure udfordring. Fenerum vil sende e-mails til dine kunder, når betalingen mislykkes med link til at give 3-D secure detaljer.
Du vil måske informere din kunde om det.

Brug SEPA direkte debitering

For at bruge SEPA direkte debitering som en af faktureringsmetoderne skal du have Stripe-integration aktiveret og konfigureret SEPA som en af dine betalingsmetoder i Stripe dashboard. Husk ikke at slå SEPA-relaterede e-mails fra Stripe fra eller at håndtere dem selv - Fenerum sender ikke e-mails om SEPA-betalinger til kunder for ikke at fordoble Stripe eller din egen integration med Stripe. Derefter kan du aktivere brugen af SEPA ved at markere "Aktiver brug af SEPA-debit" på integrationens indstillinger side. Ved at markere denne afkrydsningsboks erklærer du, at al nødvendig konfiguration på siden af Stripe er fuldført.

Tilføjelse af SEPA direkte debitering som en faktureringsmetode er analog med at tilføje kort ved hjælp af Stripe.

Udbetaling

Når du modtager en udbetaling fra Stripe, vil den fremstå som en banktransaktionslinje i Fenerum sammen med en udbetalingskvittering.
Disse to skal matches, før de kan bogføres i dit regnskabssystem. Dette kan gøres enten automatisk eller manuelt.

Læs mere om dette i denne guide.