Delen via

API's voor aankoopbescherming integreren

Belangrijk

Vanaf 3 februari 2025 is Dynamics 365 Fraud Protection niet meer beschikbaar voor aankoop. Ondersteuning voor fraudebescherming eindigt op 3 februari 2026. Raadpleeg het artikel Einde van ondersteuning voor Dynamics 365 Fraud Protection voor meer informatie.

In dit artikel wordt uitgelegd hoe u realtime API's (Application Programming Interfaces) integreert in Microsoft Dynamics 365 Fraud Protection.

Als u wilt profiteren van de volledige suite met functies voor fraudebeveiliging, moet u uw transactiegegevens verzenden naar de realtime-API's voor fraudebeveiliging. In de evaluatie-ervaring kunt u met het verzenden van uw transactiegegevens de resultaten van het gebruik van Fraudebeveiliging analyseren. In de beveiligingservaring kunt u ook beslissingen respecteren op basis van de regels die u hebt geconfigureerd.

Afhankelijk van hoe u Fraudebeveiliging gebruikt, kunt u verschillende sets van de volgende aankoopbeveiligings-API's gebruiken:

  • Inkoop
  • Aankoopstatus
  • BankEvenement
  • Terugboeking
  • Terugbetaling
  • UpdateAccount
  • Etiket

API-integratie fasen

De integratie van API's voor aankoopbeveiliging vindt plaats in drie fasen:

  1. Maak Microsoft Entra-toepassingen via fraudebescherming.
  2. Een toegangstoken genereren.
  3. Roep de API's aan.

Aanmelden

Belangrijk

U moet een globale beheerder in uw Azure-tenant zijn om de initiële aanmelding te voltooien.

Ga naar de volgende portals voor elke omgeving die u wilt gebruiken. Meld u aan en accepteer de voorwaarden als u hierom wordt gevraagd.

Microsoft Entra-toepassingen maken

Belangrijk

U moet een toepassingsbeheerder, cloudtoepassingsbeheerder of globale beheerder in uw Azure-tenant zijn om deze stap te voltooien.

Als u de tokens wilt verkrijgen die nodig zijn om de API's aan te roepen, moet u Microsoft Entra-toepassingen configureren en gebruiken, zoals beschreven in deze sectie.

Microsoft Entra-toepassingen configureren

Volg deze stappen om Microsoft Entra-toepassingen te configureren.

  1. Selecteer in de portal Fraudebeveiliging in het navigatiedeelvenster links de optie Integratie > Microsoft Entra Applicatie > Nu instellen.

  2. Voltooi de pagina om uw app te maken. U wordt aangeraden één Microsoft Entra-toepassing te maken voor elke omgeving die u wilt integreren met Fraud Protection.

  3. Voer waarden in of selecteer deze voor de volgende vereiste velden:

    • Weergavenaam van de applicatie – Geef uw applicatie een beschrijvende naam. De tekst mag maximaal 93 tekens lang zijn.
    • Verificatiemethode : selecteer of u wilt verifiëren via een certificaat of een geheim (wachtwoord).

  4. Als u de verificatiemethode voor certificaten hebt geselecteerd, voert u de volgende stappen uit:

    1. Selecteer Bestand kiezen om de openbare sleutel te uploaden. (De overeenkomende persoonlijke sleutel is vereist wanneer u tokens verkrijgt.)
    2. Selecteer Geheim om automatisch een wachtwoord te genereren nadat de toepassing is gemaakt.

  5. Wanneer u klaar bent met het instellen van de vereiste velden, selecteert u Toepassing maken. De bevestigingspagina bevat een overzicht van de naam, id en certificaatvingerafdruk of het geheim van uw app, afhankelijk van de verificatiemethode die u hebt geselecteerd.

Belangrijk

Sla uw geheime of certificaatvingerafdrukgegevens op voor toekomstige naslaginformatie. Het geheim wordt slechts eenmaal weergegeven.

Een andere toepassing maken

Als u een andere toepassing wilt maken, selecteert u Een andere toepassing maken. U kunt zoveel apps maken als u nodig hebt om API-aanroepen uit te voeren in elk van uw omgevingen.

Bestaande Microsoft Entra-toepassingen beheren

Nadat u uw Microsoft Entra-apps hebt gemaakt, kunt u deze beheren via [Azure Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Zie Hoe en waarom toepassingen worden toegevoegd aan Microsoft Entra ID voor meer informatie.

Een toegangstoken genereren

Als u uw systemen veilig wilt integreren met Fraud Protection, haalt u een Microsoft Entra-token op en geeft u dit op in de header van elke API-aanroep.

Opmerking

Toegangstokens hebben een beperkte levensduur van 60 minuten. Het wordt aanbevolen om een token op te slaan en opnieuw te gebruiken totdat het bijna verloopt. Vervolgens kunt u een nieuw toegangstoken ophalen.

De volgende informatie is nodig om een token te verkrijgen.

Vereiste id's en gegevens

  • Omgevings-URI : de URI's voor uw sandbox of productieomgeving worden weergegeven op het tabblad Configuratie van de pagina API Management in de portal Fraudebeveiliging.
  • Directory (tenant) ID – deze ID is de GUID (Globally Unique Identifier) van het domein van een tenant in Azure. Deze wordt weergegeven in Azure Portal en op het tabblad Configuratie van de pagina API Management in de portal Fraudebeveiliging.
  • Toepassings-id (client): deze id identificeert de Microsoft Entra-app die u hebt gemaakt om API's aan te roepen. Haal de id op via de bevestigingspagina van realtime API's of zoek deze later onder App-registraties in Azure Portal. Er is één id voor elke app die u hebt gemaakt.
  • Vingerafdruk of geheim van certificaat : haal de vingerafdruk of het geheim op van de bevestigingspagina van realtime API's.
  • Instantie-ID – deze id is de GUID van uw omgeving in Fraudepreventie. Deze wordt weergegeven op de tegel Integratie van het Fraud Protection-dashboard.

Voorbeelden: Codevoorbeelden die laten zien hoe u een token verkrijgt met behulp van uw certificaat of geheim

De volgende C#-codevoorbeelden bevatten voorbeelden van het verkrijgen van een token met uw certificaat of geheim. Vervang de tijdelijke aanduidingen door uw specifieke informatie. Voor beide C#-voorbeelden moet u het NuGet-pakket Microsoft.Identity.Client importeren.

Zie voor voorbeelden in andere talen https://aka.ms/aaddev.

Een toegangstoken ophalen met behulp van een app-id en een persoonlijke certificaatsleutel

/// <summary>
/// Gets an access token using an app ID and private certificate key.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="certPath">File path to the certificate file (pfx) used to authenticate your application to Microsoft Entra ID</param>
/// <param name="certPassword">Password to access to the certificate file's private key</param>
public async Task<string> AcquireTokenWithCertificate(string tenantId, string clientId, string certPath, string certPassword)
{
    var certificate = new X509Certificate2(certPath, certPassword);

    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithCertificate(certificate)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

Een toegangstoken ophalen met behulp van een app-id en geheim

/// <summary>
/// Gets an access token using an app ID and secret.
/// </summary>
/// <param name="tenantId">Directory (tenant) ID, in GUID format</param>
/// <param name="clientId">Application (client) ID</param>
/// <param name="clientSecret">The secret (password) used to authenticate the client (application) ID</param>
public async Task<string> AcquireTokenWithSecret(string tenantId, string clientId, string clientSecret)

{
    var app = ConfidentialClientApplicationBuilder.Create(clientId)
            .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
            .WithClientSecret(clientSecret)
            .Build();

    var scopes = new string[] { "<API endpoint for INT or PROD>; should be https://api.dfp.microsoft-int.com/.default or https://api.dfp.microsoft.com/.default" };

    try
    {
        var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
        return result.AccessToken;
    }
    catch (MsalServiceException ex)
    {
        //Handle authentication exceptions
        throw ex;
    }
}

Het AuthenticationResult-object bevat in elk geval de AccessToken-waarde en een eigenschap ExpiresOn die aangeeft wanneer het token ongeldig wordt.

  • POST-verzoek naar:

    • https://login.microsoftonline.com/<Microsoft Entra tenant ID>/oauth2/token

  • Kopteksten:

    • Inhoudstype: application/x-www-form-urlencoded

  • Hoofdtekst (sleutelwaarde):

    • grant_type: client_credentials
    • client_id: {Uw client-id uit de vorige stap}
    • client_secret: {Uw geheim uit de vorige stap}
    • resource: https://api.dfp.microsoft.com (voor int, https://api.dfp.microsoft-int.com)

  • Respons:

    • Gebruik de waarde van access_token uit het antwoord voor de volgende stap.

Zie de volgende Azure-documentatie voor meer informatie:

De API's aanroepen

Volg deze stappen om de API's aan te roepen.

  1. Geef bij elk verzoek de volgende vereiste HTTP-headers door.

    Koptekstnaam Headerwaarde
    Autorisatie

    Gebruik de volgende indeling voor deze header. (Vervang het toegangstoken door de werkelijke tokenwaarde die wordt geretourneerd door Microsoft Entra-id.)

    Bearer-toegangstoken
    x-ms-correlation-id Verzend een nieuwe GUID-waarde voor elke set API-aanroepen die samen worden ingediend.
    x-ms-dfpenvid Stuur de GUID-waarde van uw instance-ID.

  2. Genereer een op gebeurtenissen gebaseerde payload. Vul voor de gebeurtenisgegevens de relevante informatie van uw systeem in. Zie de Dynamics 365 Fraud Protection-API voor documentatie over alle ondersteunde gebeurtenissen.

  3. Combineer de header (inclusief de toegangstoken) en de payload en stuur deze vervolgens naar uw Fraud Protection-eindpunt.

    • POST-verzoek naar:

      • <Base URL>/v1.0/merchantservices/events/purchase

    • Kopteksten:

      • x-ms-correlation-id: {Een GUID, die uniek moet zijn per aanvraag}
      • inhoudstype: toepassing/json
      • Autorisatie: {Het token uit de vorige stap}
      • x-ms-dfpenvid: {De omgevings-id van de doelomgeving}

    • Lichaam:

      • Haal de hoofdtekst van de voorbeeldaccountbeveiligingsaanvraag op van de gedeelde Swagger-pagina.

Opmerking

Als u een nieuwe omgeving maakt, neemt u de omgevings-id op in de API-header tijdens de integratie, zodat de transacties correct kunnen worden gerouteerd.

De volgende opties zijn acceptabel voor x-ms-dfpenvid in de API-aanroep en het gedrag is identiek.

  • Gebruik de omgevings-id voor de omgeving die u aanroept. De ID wordt weergegeven op de Integratiepagina in het veld omgeving-ID.
  • Gebruik het volledige pad van de API-ID van de klant van de hoofdomgeving naar de onderliggende omgeving die u aanroept, waarbij u de slash (/) als scheidingsteken gebruikt. Bijvoorbeeld /primary/XYZ.
  • Gebruik het volledige pad van de Omgevings-ID of de Klant-API-ID vanaf de root naar de onderliggende omgeving die u aanroept, met behulp van de slash (/) als scheidingsteken. Bijvoorbeeld 7b925ca8-d372-4245-bc5a-94b5fdb6c067/XYZ.

Als u de API-id van de klant wilt opgeven wanneer u een omgeving creat, raadpleegt u het artikel Omgevingen beheren.

Beste praktijken

  • Elk Microsoft Entra-token blijft 60 minuten geldig. U wordt aangeraden deze gedurende een kortere periode in de cache op te plaatsen en opnieuw te gebruiken.
  • Zorg ervoor dat uw HttpClient keep-alive-verbindingen heeft.
  • Geef altijd de x-ms-dfpenvid-header door en zorg ervoor dat deze verwijst naar de omgeving van de handelaar namens wie u transacties wilt verzenden.
  • Sla het geheim op in een geheime winkel.
  • Geef altijd de header x-ms-correlation-id door voor toekomstige foutopsporingssessies met Fraudebeveiliging.
  • Zorg ervoor dat de header x-ms-correlation-id uniek is voor elke transactie die naar Fraudebeveiliging wordt verzonden. 

De voorbeeld-app weergeven

Voor aanvullende informatie kunt u de voorbeeld-merchant-app en de bijbehorende documentatie voor ontwikkelaars bekijken. De voorbeeld-app biedt een voorbeeld van het aanroepen van fraudebeveiligings-API's, waaronder API-gebeurtenissen zoals het verzenden van updates van klantenaccounts, restituties en terugstortingen in realtime. De documentatie voor de voorbeeld-app is gekoppeld aan de werkelijke voorbeeldcode wanneer dergelijke koppelingen mogelijk zijn. Anders bestaan codevoorbeelden rechtstreeks in de documentatie.

Zie De voorbeeldsite configureren voor hulp bij het configureren van de voorbeeldsite voor uw gebruik.