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

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

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

• Affichez le solde actuel du compte prépayé. Consultez Afficher les soldes des comptes prépayés à l'aide de l'API.
• Rechargez (ajoutez de l'argent) le solde du compte selon vos besoins à 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 services de paiement tiers.

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

• Configurez le rechargement automatique lorsqu'un solde de compte prépayé descend en dessous d'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 de mon compte prépayé ?

Lorsque vous consultez le solde du compte prépayé 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 : montant total 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 dépensé au cours de la période de facturation actuelle. Cette valeur est mise à jour à chaque transaction monétisée éligible ou en émettant 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 de 335,50 € et la valeur usage est de 34, le solde restant est calculé comme suit :

amount(335.50) - usage(34) = 229.50

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

Les sections suivantes décrivent comment afficher les soldes des comptes prépayés 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 les soldes des comptes prépayés d'un développeur, envoyez une requête GET à l'une des API suivantes, où {developer_id} correspond à 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 des paiements récurrents pour un développeur.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances : renvoie des informations sur le solde du compte prépayé, y compris le solde actuel et total, l'utilisation, les recharges et la taxe 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, émettez 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 est prépayée, la demande récupère le solde actuel du compte prépayé. Si l'entreprise est en post-paiement, 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 les soldes des comptes prépayés d'un développeur.

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

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

Le tableau suivant décrit chaque étape du flux de gestion du solde du compte prépayé, illustré 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 à suivre pour gérer les soldes prépayés à l'aide d'un fournisseur de services de paiement tiers :

• Configurer un compte marchand avec le fournisseur de paiement Worldpay
• Configurer le fournisseur de services de paiement dans Edge
• Afficher les fournisseurs de paiement configurés pour votre organisation
• Activer et configurer les modules requis dans le portail des développeurs
• Initiation d'un paiement vers un compte prépayé à l'aide d'un prestataire 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 avec le fournisseur de services de paiement Worldpay

Avant de commencer, vous devez contacter un fournisseur de services de paiement tiers (Worldpay) pour configurer vos comptes marchands. Nous vous recommandons de configurer deux comptes : un pour les tests et un pour la production. Pour en savoir plus sur les comptes marchands Worldpay, consultez 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 configurer votre compte marchand 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 services 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 Clé secrète MAC de redirection.
   4. Cliquez sur Enregistrer le profil.
4. Ajoutez le serveur de gestion Apigee Edge à la liste des adresses IP du marchand (liste d'autorisation) :
   1. Cliquez sur 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 conception 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 du paramètre "Envoyer les paramètres d'URL" sur True.
   5. Cliquez sur l'onglet Publier.
   6. Promouvez les modifications comme suit :
      • Pour les environnements de test, cliquez sur Promouvoir sous Conception pour promouvoir la conception vers le bac à sable.
      • Pour les environnements de production, cliquez sur Promote (Promouvoir) sous Sandbox (Bac à sable) pour promouvoir l'environnement de bac à sable vers 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 services de paiement pour une organisation spécifique à l'aide de l'API suivante :

/organizations/{org-name}/providers

Seuls les clients Apigee Edge pour le cloud privé disposant de droits d'administrateur système peuvent éventuellement 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 avec 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 services de paiement tiers

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

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

Par exemple, la commande suivante 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 de monétisation et Worldpay requis dans le portail des développeurs. Pour en savoir plus, consultez Configurer la monétisation dans le portail des développeurs.

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

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

• accepte un forfait, mais le solde de son compte prépayé est insuffisant.
• demander à ajouter de l'argent à son compte prépayé ;

Pour lancer un paiement à partir d'un fournisseur de services de paiement tiers à l'aide de l'API, envoyez une requête POST à la ressource suivante, où {developer_id} correspond à 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 services de paiement (provider={providerId})
• Devise acceptée (supportedCurrencyId={currency})

Vous devez également transmettre les informations de base du compte, comme l'adresse de facturation de l'entreprise.

Par exemple, la commande suivante 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 USD (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 des comptes prépayés, une fois le traitement réussi vérifié par le fournisseur de services de paiement, le portail des développeurs envoie une demande à Edge pour recharger le compte prépayé.

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

Recharger le solde d'un compte prépayé 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} correspond à l'adresse e-mail du développeur. 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'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 obtenir une description des propriétés de la requête, consultez Résumé des propriétés de la requête pour recharger un compte prépayé.

Recharger le solde d'un compte prépayé pour 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} correspond à 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 obtenir une description des propriétés de la requête, consultez Résumé des propriétés de la requête pour recharger un compte prépayé.

Récapitulatif des propriétés de la demande pour recharger un compte prépayé

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

Supprimer des fournisseurs de paiement tiers

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

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

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

Seuls les clients Apigee Edge pour le cloud privé disposant de droits d'administrateur système peuvent éventuellement 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 services 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 des comptes prépayés

Vous pouvez également gérer la recharge des soldes prépayés en effectuant un suivi manuel des 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 Recharger le solde d'un compte prépayé à l'aide de l'API.

Configurer le rechargement automatique des soldes de comptes prépayés à 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 utilisant un fournisseur de services de paiement tiers. Cette option est utile pour gérer les paiements récurrents des forfaits.

Configurer la recharge 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 descend en dessous d'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 recharger le compte (providerID)
• Indicateur qui permet le rechargement automatique (isRecurring)
• Seuil en dessous duquel le solde du compte prépayé doit descendre pour déclencher le rechargement 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 en dessous de 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 obtenir une description des propriétés de la requête, consultez Résumé des propriétés de la requête pour configurer la recharge automatique d'un compte prépayé.

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

Pour configurer le rechargement automatique du solde d'un compte prépayé pour une entreprise lorsque le solde descend 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} correspond à l'ID de l'entreprise.

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

• ID du fournisseur de services de paiement à utiliser pour recharger le compte (providerID)
• Indicateur qui permet le rechargement automatique (isRecurring)
• Seuil en dessous duquel le solde du compte prépayé doit descendre pour déclencher le rechargement 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 descend en dessous de 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 obtenir une description des propriétés de la requête, consultez Résumé des propriétés de la requête pour configurer la recharge automatique d'un compte prépayé.

Récapitulatif des propriétés de la demande pour configurer la recharge automatique des comptes prépayés

Les attributs suivants peuvent être spécifiés lors du rechargement automatique des soldes de comptes prépayés à l'aide de l'API.

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

WorldPay a mis à jour son flux de traitement sécurisé des paiements 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 de l'ancien flux de traitement des paiements sécurisés (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 afin d'utiliser les nouvelles pages de paiement hébergées et obtenir un nouvel ID d'installation pour votre compte.
2. Configurez de nouveaux fournisseurs de services de paiement WorldPay, comme décrit dans 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 services de paiement sur votre portail des développeurs, comme décrit dans Configurer la monétisation dans le portail des développeurs.
4. Si vous avez configuré le rechargement automatique d'un compte prépayé à l'aide du fournisseur de services de paiement, vous devez reconfigurer le rechargement automatique pour utiliser le nouvel ID de fournisseur, comme décrit dans 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 chaque développeur avec post-paiement. Pour en savoir plus, consultez Gérer les soldes postpayés.