Gérer le solde des comptes prépayés

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Pour gérer le solde d'un compte prépayé, vous pouvez:

• Consultez le solde actuel de votre compte prépayé. Consultez Afficher le solde des comptes prépayés à l'aide de l'API.
• Recharger (ajouter de l'argent) le solde du compte si nécessaire à l'aide d'un fournisseur de services de paiement tiers, tel que Worldpay. Consultez Gérer les soldes prépayés à l'aide d'un fournisseur de paiement tiers.

  Vous pouvez également gérer le rechargement en suivant manuellement les paiements ou via un système de facturation intégré, puis en appelant l'API de monétisation pour recharger le compte, comme décrit dans la section Gérer manuellement les soldes prépayés.

• Configurez le rechargement automatique lorsque le solde d'un compte prépayé passe sous un certain seuil à l'aide de l'API de monétisation et d'un fournisseur de services de paiement tiers, tel que Worldpay. Cette option est utile pour gérer les paiements récurrents des forfaits. Pour en savoir plus, consultez Configurer le rechargement automatique des soldes de comptes prépayés à l'aide de l'API.

Comment calculer le solde restant du compte prépayé ?

Lorsque vous affichez le solde prépayé du compte d'un développeur ou d'une entreprise, comme décrit dans les sections suivantes, vous devez obtenir les valeurs suivantes à partir de la réponse:

• amount: somme totale disponible pour la période de facturation en cours. Cette valeur est mise à jour lorsque vous rechargez le compte prépayé à l'aide des méthodes décrites dans cette section.
• usage: montant total utilisé au cours de la période de facturation en cours. Cette valeur est mise à jour à chaque transaction monétisée qualifiée ou par émission d'un crédit (positif ou négatif).

Vous pouvez calculer le solde restant du compte prépayé pour la période de facturation en cours en soustrayant la valeur usage de la valeur amount. Par exemple, si la valeur amount est 335,50 et la valeur usage est 34, le solde restant est calculé comme suit:

amount(335.50) - usage(34) = 229.50

Afficher le solde de comptes prépayés à l'aide de l'API

Les sections suivantes expliquent comment afficher le solde prépayé des comptes d'un développeur ou d'une entreprise à l'aide de l'API.

Afficher le solde d'un compte prépayé pour un développeur

Pour afficher le solde d'un compte prépayé d'un développeur, envoyez une requête GET à l'une des API suivantes, où {developer_id} est l'adresse e-mail du développeur:

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: renvoie le solde du compte prépayé et les informations de configuration récurrente d'un développeur.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: renvoie des informations sur le solde prépayé du compte, y compris le solde actuel et total, l'utilisation, les recharges et les taxes d'utilisation.

Vous pouvez transmettre les paramètres de requête suivants pour filtrer les résultats:

Exemple :

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

Voici un exemple de réponse :

{
    "developerBalance": [
        {
            "amount": 2005,
            "chargePerUsage": false,
            "id": "your-provider-id",
            "isRecurring": false,
            "supportedCurrency": {
                "description": "United States Dollars",
                "displayName": "United States Dollars",
                "id": "usd",
                "name": "USD",
                "organization": {
                    "address": [
                        {
                            "address1": "10 Almaden Blvd.",
                            "city": "San Jose",
                            "country": "US",
                            "id": "32e808d8-3a3c-4d76-a0ae-17d70a982c61",
                            "isPrimary": true,
                            "state": "CA",
                            "zip": "95113"
                        }
                    ],
                    "approveTrusted": false,
                    "approveUntrusted": false,
                    "billingCycle": "CALENDAR_MONTH",
                    "country": "US",
                    "currency": "USD",
                    "description": "my-org",
                    "groupOrganization": false,
                    "hasBillingAdjustment": false,
                    "hasBroker": false,
                    "hasSelfBilling": false,
                    "hasSeparateInvoiceForProduct": false,
                    "id": "my-org",
                    "issueNettingStmt": false,
                    "name": "my-org",
                    "nettingStmtPerCurrency": false,
                    "selfBillingAsExchOrg": false,
                    "selfBillingForAllDev": false,
                    "separateInvoiceForFees": false,
                    "status": "ACTIVE",
                    "supportedBillingType": "BOTH",
                    "taxModel": "HYBRID",
                    "timezone": "UTC"
                },
                "status": "ACTIVE",
                "virtualCurrency": false
            },
            "usage": 2.1572
        }
    ],
    "totalRecords": 1
}

Afficher le solde des comptes prépayés d'une entreprise

Pour afficher les soldes des comptes prépayés d'une entreprise, envoyez une requête GET à /mint/organizations/{org_name}/companies/{company_id}/developer-balances, où {company_id} est l'ID de l'entreprise. Si l'entreprise a opté pour le pré-paiement, la requête récupère le solde prépayé actuel du compte. Si l'entreprise est postpayée, la demande récupère la limite de crédit actuelle.

Vous pouvez transmettre les paramètres de requête suivants pour filtrer les résultats:

Exemple :

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

La réponse est semblable à celle affichée ci-dessus lorsque vous consultez le solde d'un compte prépayé pour un développeur.

Gérer le solde de comptes prépayés à l'aide d'un fournisseur de services de paiement

Gérez le solde prépayé de votre compte en configurant un compte marchand auprès d'un fournisseur de services de paiement tiers, tel que Worldpay. La figure suivante montre comment le solde du compte prépayé est géré à l'aide du fournisseur de paiement Worldpay.

Le tableau suivant décrit chaque étape du flux de gestion du solde du compte prépayé, présenté ci-dessus.

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

Les sections suivantes décrivent les étapes requises pour gérer les soldes prépayés à l'aide d'un fournisseur de services de paiement tiers:

• Configurer un compte marchand auprès du fournisseur de services de paiement Worldpay
• Configuration du fournisseur de services de paiement dans Edge
• Afficher les fournisseurs de services de paiement configurés pour votre organisation
• Activer et configurer les modules requis dans le portail des développeurs
• Initiation d'un paiement sur un compte prépayé à l'aide d'un fournisseur de services de paiement
• Recharger le solde d'un compte prépayé à l'aide de l'API
• Supprimer un fournisseur de services de paiement tiers

Configurer un compte marchand auprès du fournisseur de services de paiement Worldpay

Avant de commencer, vous devez contacter un fournisseur de services de paiement tiers (Worldpay) pour configurer votre ou vos comptes marchand. Nous vous recommandons de configurer deux comptes, l'un pour les tests et l'autre pour la production. Pour en savoir plus sur les comptes marchands Worldpay, consultez les sites www.worldpay.com et wp-support.crm.worldpay.com (centre d'assistance Worldpay).

Une fois que vous avez configuré votre compte marchand et reçu vos identifiants, procédez comme suit pour le configurer avec Worldpay:

1. Accédez à https://secure.worldpay.com/sso/public/auth/login.html.
2. Connectez-vous à votre compte Worldpay à l'aide des identifiants fournis par Worldpay.
3. Définissez le mot de passe XML et la clé secrète du code d'authentification des messages (MAC) :
   1. Cliquez sur Profil.
   2. Définissez le mot de passe à utiliser lors de la configuration du fournisseur de paiement Worldpay dans Edge dans le champ Mot de passe XML.
   3. Saisissez une clé secrète MAC de 20 à 30 caractères dans le champ Secret MAC de redirection.
   4. Cliquez sur Enregistrer le profil.
4. Ajoutez le serveur de gestion Apigee Edge à la liste des adresses IP des marchands (liste d'autorisation) :
   1. Cliquez sur Profile > Merchant Environment (Profil > Environnement du marchand).
   2. Cliquez sur Nouvelle adresse IP de test.
   3. Saisissez l'adresse IP du serveur de gestion Apigee Edge.
   4. Cliquez sur Enregistrer.
5. Configurez l'URL du marchand pour ajouter les paramètres Worldpay, y compris le code d'authentification de la méthode (MAC) :
   1. Cliquez sur Installations > Pages de paiement hébergées > Outil de création de pages de paiement.
   2. Sous Modifier les pages de paiement, sélectionnez votre ID d'installation dans la liste déroulante Sélectionner un canal.
   3. Dans l'onglet "Propriétés", sélectionnez Modifier la configuration du marchand.
   4. Définissez la valeur des paramètres d'envoi d'URL sur True.
   5. Cliquez sur l'onglet Publier.
   6. Promouvoir les modifications comme suit :
      • Pour les environnements de test, cliquez sur Promouvoir sous Conception pour passer de la conception au bac à sable.
      • Pour les environnements de production, cliquez sur Promote (Promouvoir) sous Sandbox (Bac à sable) pour passer de l'environnement de bac à sable à l'environnement de production.

Configurer le fournisseur de paiement dans Edge

L'étape suivante consiste à configurer le fournisseur de services de paiement dans Edge.

Vous pouvez configurer votre fournisseur de paiement pour une organisation spécifique à l'aide de l'API suivante:

/organizations/{org-name}/providers

Seuls les clients Apigee Edge Private Cloud disposant d'autorisations d'administrateur système peuvent configurer un fournisseur de services de paiement mondial à l'aide de l'API suivante:

/config/providers

Lorsque vous appelez chaque API, vous devez spécifier les informations suivantes dans le corps de la requête:

Par exemple, la commande suivante configure un compte marchand Worldpay nommé Worldpay-myorg:

$ curl  -H "Content-Type:application/json" -X POST -d \
'{
    "name": "Worldpay-myorg",
    "description": "Worldpay payment provider",
    "endpoint": "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "authType": "123456",
    "credential": "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "merchantCode": "myMerchantCode"
  }' \
"https://api.enterprise.apigee.com/v1/organizations/myOrg/providers" \
-u email:password 

Afficher les fournisseurs de paiement tiers

Affichez et confirmez les fournisseurs de paiement tiers configurés pour votre organisation Edge en envoyant une demande GET à la ressource suivante:

/mint/organizations/{org-name}/providers

Par exemple, l'extrait suivant affiche les fournisseurs de paiement tiers actuellement configurés pour myorg:

$ curl  -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers" \
-u email:password

Voici un exemple de réponse affichant deux comptes marchands, l'un pour les tests et l'autre pour la production.

{
  "provider" : [ {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-myorg",
    "merchantCode" : "MERCH_CODE",
    "name" : "Worldpay-myorg"
  }, {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-test",
    "merchantCode" : "MERCH_CODE_FROM_PROVIDER",
    "name" : "Worldpay-test"
  } ]
}

Activer et configurer les modules de monétisation et Worldpay dans le portail des développeurs

Activez les modules Monetization et Worldpay requis dans le Developer Portal. Pour en savoir plus, consultez Configurer la monétisation dans le portail des développeurs.

Lancer un paiement sur un compte prépayé à l'aide du fournisseur de services de paiement

Comme indiqué à l'étape 2 du flux de gestion des comptes prépayés, le paiement d'un compte prépayé à l'aide d'un fournisseur de paiement est lancé par le portail des développeurs lorsque les consommateurs d'API:

• Accepter un forfait, mais ne pas disposer de fonds suffisants sur son compte prépayé
• Demander à ajouter de l'argent à son compte prépayé

Pour lancer un paiement à partir d'un fournisseur de paiement tiers à l'aide de l'API, envoyez une requête POST à la ressource suivante, où {developer_id} est l'adresse e-mail du développeur.

/mint/organizations/{org_name}/developers/{developer_id}/payment?amount={amount}&provider={providerId}&supportedCurrencyId={currency}

Lorsque vous envoyez la requête, vous devez spécifier les valeurs suivantes en tant que paramètres de requête:

• Montant à ajouter au solde du compte prépayé (amount={amount})
• ID du fournisseur de paiement (provider={providerId})
• Devise acceptée (supportedCurrencyId={currency})

De plus, vous devez transmettre des informations de base sur le compte, telles que l'adresse de facturation de l'entreprise.

Par exemple, l'exemple suivant recharge le solde d'un compte prépayé à l'aide du fournisseur de paiement Worldpay. Le transfert initial vers votre compte prépayé sera de 10 $ (le paramètre de requête amount est défini sur 10).

$ curl  -H "Content-Type:application/xml" -X POST -d \
'{
    "address1": "5115 Hopyard Ave.",
    "city": "Pleasanton",
    "country": "US",
    "state": "CA",
    "zip": "58158"
}'
' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/payment?amount=10&provider=worldpay-myorg&supportedCurrencyId=usd" \
-u email:password

Voici un exemple de réponse :

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

L'URL de la page de paiement sécurisé Worldpay est renvoyée dans referenceUrl, avec votre clé de commande unique ajoutée en tant que paramètre de requête.

Recharger le solde d'un compte prépayé à l'aide de l'API

Comme indiqué à l'étape 15 du flux de gestion du compte prépayé, après avoir vérifié que le fournisseur de paiement a bien traité la demande, le portail du développeur envoie une requête à Edge pour recharger le compte prépayé.

Vous pouvez recharger le solde d'un compte prépayé à l'aide de l'API pour un développeur ou une entreprise, comme décrit dans les sections suivantes.

Actualiser la réserve prépayée d'un compte pour un développeur

Pour recharger le solde d'un compte prépayé pour un développeur à l'aide de l'API, envoyez une requête POST à /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, où {developer_id} est l'adresse e-mail du développeur. Lorsque vous émettez la requête, vous devez spécifier dans le corps de la requête le montant à ajouter au solde et la devise utilisée.

Par exemple, la requête suivante ajoute 1 000 $au solde du compte prépayé d'un développeur:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

Pour en savoir plus sur les propriétés de la requête, consultez Récapitulatif des propriétés de requête pour recharger un compte prépayé.

Recharger le solde prépayé du compte d'une entreprise

Pour recharger le solde d'un compte prépayé pour une entreprise à l'aide de l'API, envoyez une requête POST à /mint/organizations/{org_name}/companies/{company_id}/developer-balances, où {company_id} est l'ID de l'entreprise. Lorsque vous envoyez la requête, vous devez spécifier dans le corps de la requête le montant à ajouter au solde et la devise utilisée.

Par exemple, la requête suivante ajoute 1 000 $au solde du compte prépayé d'une entreprise:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

Pour en savoir plus sur les propriétés de la requête, consultez Récapitulatif des propriétés de requête pour recharger un compte prépayé.

Résumé des propriétés de requête pour recharger un compte prépayé

Les propriétés suivantes doivent être spécifiées lorsque vous rechargez les soldes prépayés de vos comptes à l'aide de l'API:

Supprimer des fournisseurs de services de paiement tiers

Vous pouvez supprimer un fournisseur de paiement tiers configuré pour votre organisation Edge en envoyant une requête DELETE à la ressource suivante:

Pour supprimer un fournisseur de paiement pour une organisation spécifique, utilisez l'API suivante:

/mint/organizations/{org-name}/providers/id

Seuls les clients Apigee Edge Private Cloud disposant des droits d'administrateur système peuvent supprimer un fournisseur de services de paiement mondial à l'aide de l'API suivante:

/config/providers/id

Par exemple, la commande suivante supprime les fournisseurs de paiement tiers actuellement configurés pour myorg:

$ curl  -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers/worldpay-myorg" \
-u email:password

Gérer manuellement le solde de comptes prépayés

Vous pouvez également gérer le rechargement des soldes prépayés en suivant les paiements manuellement ou via un système de facturation intégré, puis en appelant l'API de monétisation pour recharger le compte, comme décrit dans la section Recharger le solde d'un compte prépayé à l'aide de l'API.

Configurer l'actualisation automatique du solde prépayé de vos comptes à l'aide de l'API

Les sections suivantes décrivent comment configurer le rechargement automatique des soldes de comptes prépayés pour un développeur ou une entreprise qui utilise un fournisseur de paiement tiers. Cette option est utile pour gérer les paiements récurrents des forfaits.

Configurer le rechargement automatique du solde d'un compte prépayé pour un développeur

Pour configurer le rechargement automatique du solde d'un compte prépayé pour un développeur lorsque le solde passe sous un certain seuil, envoyez une requête POST à /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup, où {developer_id} correspond à l'adresse e-mail du développeur.

Lorsque vous envoyez la requête, vous devez spécifier les éléments suivants:

• ID du fournisseur de services de paiement à utiliser pour actualiser le compte (providerID)
• Indicateur qui active le rechargement automatique (isRecurring)
• Seuil à partir duquel le solde prépayé du compte doit descendre en dessous du seuil pour déclencher l'actualisation automatique (replenishAmount)
• Montant à ajouter automatiquement au compte (recurringAmount)
• Paramètre de requête supportedCurrencyID pour spécifier la devise.

Dans l'exemple suivant, lorsque le solde du compte prépayé du développeur passe sous 5 USD, 10 USD supplémentaires sont automatiquement ajoutés au compte.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

Pour en savoir plus sur les propriétés de requête, consultez la section Récapitulatif des propriétés de requête pour configurer le rechargement automatique d'un compte prépayé.

Configurer l'actualisation automatique du solde prépayé du compte d'une entreprise

Pour configurer l'actualisation automatique du solde prépayé du compte d'une entreprise lorsque celui-ci passe en dessous d'un certain montant, envoyez une requête POST à /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup, où {company_id} est l'ID de l'entreprise.

Lorsque vous émettez la requête, vous devez spécifier les éléments suivants:

• ID du fournisseur de paiement à utiliser pour recharger le compte (providerID)
• Indicateur qui active l'actualisation automatique (isRecurring)
• Seuil à partir duquel le solde prépayé du compte doit descendre en dessous du seuil pour déclencher l'actualisation automatique (replenishAmount)
• Montant à ajouter automatiquement au compte (recurringAmount)
• Paramètre de requête supportedCurrencyID pour spécifier la devise.

Dans l'exemple suivant, lorsque le solde du compte prépayé de l'entreprise passe sous la barre des 5 USD, 10 USD supplémentaires sont automatiquement ajoutés au compte.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

Pour en savoir plus sur les propriétés de requête, consultez la section Récapitulatif des propriétés de requête pour configurer le rechargement automatique d'un compte prépayé.

Résumé des propriétés de requête pour la configuration de l'actualisation automatique des comptes prépayés

Les attributs suivants peuvent être spécifiés lorsque vous rechargez automatiquement les soldes prépayés de vos comptes à l'aide de l'API.

Migrer vers les pages de paiement hébergées de WorldPay

WorldPay a mis à jour son flux de traitement des paiements sécurisés pour utiliser un nouvel ensemble de pages, appelées pages de paiement hébergées.

Si vous avez configuré vos fournisseurs de paiement WorldPay à l'aide du flux de traitement des paiements sécurisés obsolète (avant août 2017), vous devrez migrer vers les nouvelles pages de paiement hébergées de WorldPay avant janvier 2018.

Pour migrer vers les pages de paiement hébergées de WorldPay:

1. Contactez WorldPay pour migrer votre compte actuel vers les nouvelles pages de paiement hébergées et obtenir un nouvel ID d'installation pour votre compte.
2. Configurez de nouveaux fournisseurs de paiement WorldPay, comme décrit dans la section Configurer le fournisseur de paiement dans Edge, en transmettant l'ID d'installation dans le champ authType.
3. Configurez le ou les nouveaux fournisseurs de paiement dans votre portail des développeurs, comme décrit dans Configurer la monétisation dans le portail des développeurs.
4. Si vous configurez le rechargement automatique d'un compte prépayé à l'aide du fournisseur de paiement, vous devez reconfigurer le rechargement automatique pour utiliser le nouvel ID de fournisseur, comme décrit dans la section Configurer le rechargement automatique des soldes de comptes prépayés à l'aide de l'API.

Étapes suivantes

Vous pouvez définir des limites de crédit pour des développeurs postpayés individuels. Pour en savoir plus, consultez l'article Gérer les soldes de post-paiement.