Gestisci i saldi prepagati degli account

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Per gestire il saldo di un account con pagamento anticipato, puoi:

• Visualizza il saldo attuale dell'account prepagato. Consulta la sezione Visualizzare i saldi degli account prepagati utilizzando l'API.
• Ricarica (aggiungi denaro al) il saldo dell'account come richiesto utilizzando un fornitore di servizi di pagamento di terze parti, come Worldpay. Consulta Gestire i saldi prepagati utilizzando un fornitore di servizi di pagamento di terze parti.

  In alternativa, puoi gestire il ricaricamento monitorando i pagamenti manualmente o tramite un sistema di fatturazione integrato e chiamando l'API di monetizzazione per ricaricare l'account, come descritto in Gestire manualmente i saldi prepagati.

• Configura il ricaricamento automatico quando il saldo di un account prepagato scende al di sotto di una determinata soglia utilizzando l'API di monetizzazione e un fornitore di servizi di pagamento di terze parti, come Worldpay. Questa opzione è utile per gestire i pagamenti ricorrenti per i piani tariffari. Per informazioni, consulta Configurare il ricaricamento automatico dei saldi dell'account prepagato utilizzando l'API.

Come faccio a calcolare il saldo rimanente dell'account prepagato?

Quando visualizzi il saldo dell'account prepagato di uno sviluppatore o di un'azienda, come descritto nelle sezioni seguenti, devi recuperare i seguenti valori dalla risposta:

• amount: importo totale di denaro disponibile per il periodo di fatturazione corrente. Questo valore viene aggiornato quando ricarichi l'account prepagato utilizzando i metodi descritti in questa sezione.
• usage: importo totale utilizzato durante il periodo di fatturazione corrente. Questo valore viene aggiornato con ogni transazione monetizzata qualificata o tramite l'emissione di un credito (positivo o negativo).

Puoi calcolare il saldo rimanente dell'account prepagato per il periodo di fatturazione in corso sottraendo il valore usage dal valore amount. Ad esempio, se il valore di amount è 335,50 e il valore di usage è 34, il saldo rimanente viene calcolato come segue:

amount(335.50) - usage(34) = 229.50

Visualizzazione dei saldi dell'account con pagamento anticipato tramite l'API

Le sezioni seguenti descrivono come visualizzare i saldi degli account prepagati per uno sviluppatore o una società che utilizza l'API.

Visualizzare i saldi prepagati degli account di uno sviluppatore

Per visualizzare i saldi prepagati dell'account di uno sviluppatore, invia una richiesta GET a una delle seguenti API, dove {developer_id} è l'indirizzo email dello sviluppatore:

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: restituisce il saldo dell'account prepagato e le informazioni di configurazione ricorrenti per uno sviluppatore.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: restituisce informazioni sul saldo dell'account prepagato, tra cui saldo corrente e totale, utilizzo, ricariche e imposta sull'utilizzo.

Puoi passare i seguenti parametri di query per filtrare i risultati:

Ad esempio:

$ 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

Di seguito è riportato un esempio di risposta:

{
    "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
}

Visualizzare i saldi degli account con pagamento anticipato per un'azienda

Per visualizzare i saldi prepagati degli account per un'azienda, invia una richiesta GET a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, dove {company_id} è l'ID dell'azienda. Se l'azienda è prepagata, la richiesta recupera il saldo corrente dell'account prepagato. Se l'azienda è di tipo postpaid, la richiesta recupera il massimale di credito corrente.

Puoi passare i seguenti parametri di query per filtrare i risultati:

Ad esempio:

$ 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 risposta è simile a quella mostrata sopra, quando visualizzi i saldi degli account pagati in anticipo per un sviluppatore.

Gestione dei saldi dell'account con pagamento anticipato utilizzando un fornitore di servizi di pagamento

Gestisci i saldi dell'account con pagamento anticipato configurando un account commerciante con un fornitore di servizi di pagamento di terze parti, come Worldpay. La figura seguente mostra come viene gestito il saldo dell'account prepagato utilizzando il fornitore di servizi di pagamento Worldpay.

La tabella seguente descrive ogni passaggio del flusso di gestione del saldo dell'account prepagato, mostrato sopra.

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

Le sezioni seguenti descrivono i passaggi necessari per gestire i saldi prepagati utilizzando un fornitore di servizi di pagamento di terze parti:

• Configurare un account commerciante con il fornitore di servizi di pagamento Worldpay
• Configurare il fornitore di servizi di pagamento in Edge
• Visualizzare i fornitori di servizi di pagamento configurati per la tua organizzazione
• Attivare e configurare i moduli richiesti nel portale sviluppatori
• Avvio di un pagamento su un account prepagato tramite un fornitore di servizi di pagamento
• Ricaricare il saldo di un account con pagamento anticipato utilizzando l'API
• Eliminare un fornitore di servizi di pagamento di terze parti

Configurazione di un account commerciante con il fornitore di servizi di pagamento Worldpay

Prima di iniziare, devi contattare un fornitore di servizi di pagamento di terze parti (Worldpay) per configurare i tuoi account commerciante. Ti consigliamo di configurare due account, uno per i test e uno per la produzione. Per ulteriori informazioni sugli account commerciante Worldpay, visita le pagine www.worldpay.com e wp-support.crm.worldpay.com (centro assistenza Worldpay).

Dopo aver configurato il tuo account commerciante e aver ricevuto le credenziali dell'account, per configurare il tuo account commerciante con Worldpay:

1. Vai all'indirizzo https://secure.worldpay.com/sso/public/auth/login.html.
2. Accedi al tuo account Worldpay utilizzando le credenziali fornite da Worldpay.
3. Imposta la password XML e la chiave segreta del codice di autenticazione dei messaggi (MAC):
   1. Fai clic su Profilo.
   2. Imposta la password da utilizzare per configurare il fornitore di servizi di pagamento Worldpay in Edge nel campo Password XML.
   3. Inserisci una chiave segreta MAC di 20-30 caratteri nel campo Secret MAC per il reindirizzamento.
   4. Fai clic su Salva profilo.
4. Aggiungi il server di gestione Apigee Edge all'elenco degli IP dei commercianti (lista consentita):
   1. Fai clic su Profilo > Ambiente del commerciante.
   2. Fai clic su Nuovo IP di test.
   3. Inserisci l'IP del server di gestione Apigee Edge.
   4. Fai clic su Salva.
5. Configura l'URL del commerciante in modo da aggiungere i parametri Worldpay, incluso il codice di autenticazione del metodo (MAC):
   1. Fai clic su Installazioni > Pagine di pagamento in hosting > Progettazione pagine di pagamento.
   2. In Modifica pagine di pagamento, seleziona il tuo ID installazione dall'elenco a discesa Seleziona canale.
   3. Nella scheda Proprietà, seleziona Modifica configurazione commerciante.
   4. Imposta il valore dei parametri URL per l'invio su True.
   5. Fai clic sulla scheda Pubblica.
   6. Promuovi le modifiche come segue:
      • Per gli ambienti di test, fai clic su Esegui la promozione in Design per eseguire la promozione da Design a Sandbox.
      • Per gli ambienti di produzione, fai clic su Promuovi in Sandbox per passare dalla sandbox alla produzione.

Configurazione del fornitore di servizi di pagamento in Edge

Il passaggio successivo consiste nel configurare il fornitore di servizi di pagamento in Edge.

Puoi configurare il tuo fornitore di servizi di pagamento per un'organizzazione specifica utilizzando la seguente API:

/organizations/{org-name}/providers

Solo i clienti Apigee Edge Private Cloud con privilegi di amministratore di sistema possono optionally configurare un fornitore di servizi di pagamento globale utilizzando la seguente API:

/config/providers

Quando chiami ogni API, devi specificare le seguenti informazioni nel corpo della richiesta:

Ad esempio, il codice seguente configura un account commerciante con Worldpay denominato 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 

Visualizzare i fornitori di servizi di pagamento di terze parti

Visualizza e conferma i fornitori di servizi di pagamento di terze parti configurati per la tua organizzazione Edge inviando una richiesta GET alla seguente risorsa:

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

Ad esempio, di seguito vengono mostrati i fornitori di servizi di pagamento di terze parti attualmente configurati per myorg:

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

Di seguito è riportato un esempio di risposta che mostra due account commerciante, uno per i test e l'altro per la produzione.

{
  "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"
  } ]
}

Attivazione e configurazione dei moduli Monetizzazione e Worldpay nel portale per sviluppatori

Attiva i moduli Monetizzazione e Worldpay richiesti nel portale per gli sviluppatori. Per maggiori dettagli, vedi Configurare la monetizzazione nel Developer Portal.

Avvio del pagamento a un account prepagato utilizzando il fornitore di servizi di pagamento

Come mostrato nel passaggio 2 del flusso di gestione dell'account prepagato, il pagamento a un account prepagato tramite un fornitore di servizi di pagamento viene avviato dal portale per gli sviluppatori quando i consumatori dell'API:

• Accettare un piano tariffario, ma avere fondi insufficienti nell'account prepagato
• Richiedere l'aggiunta di denaro al proprio account prepagato.

Per avviare un pagamento da un fornitore di servizi di pagamento di terze parti utilizzando l'API, invia una richiesta POST alla seguente risorsa, dove {developer_id} è l'indirizzo email dello sviluppatore.

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

Quando emetti la richiesta, devi specificare i seguenti valori come parametri di query:

• Importo da aggiungere al saldo prepagato dell'account (amount={amount})
• ID fornitore di servizi di pagamento (provider={providerId})
• Valuta supportata (supportedCurrencyId={currency})

Inoltre, devi passare i dati di base dell'account, come l'indirizzo di fatturazione dell'azienda.

Ad esempio, il codice seguente ricarica il saldo di un account prepagato utilizzando il fornitore di servizi di pagamento Worldpay. Il trasferimento iniziale sul tuo account prepagato sarà di 10 dollari statunitensi (amount il parametro di query è impostato su 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

Di seguito viene fornito un esempio della risposta:

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

L'URL alla pagina di pagamento sicuro di Worldpay viene restituito in referenceUrl con la chiave ordine univoca aggiunta come parametro di query.

Ricaricare il saldo di un account prepagato utilizzando l'API

Come mostrato nel passaggio 15 del flusso di gestione degli account prepagato, dopo aver verificato l'avvenuta elaborazione da parte del fornitore di servizi di pagamento, il portale per gli sviluppatori invia a Edge una richiesta di ricaricamento dell'account prepagato.

Puoi ricaricare il saldo dell'account prepagato utilizzando l'API per uno sviluppatore o un'azienda, come descritto nelle sezioni seguenti.

Ricaricamento del saldo prepagato di un account per uno sviluppatore

Per ricaricare il saldo di un account prepagato per uno sviluppatore che utilizza l'API, invia una richiesta POST a /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, dove {developer_id} è l'indirizzo email dello sviluppatore. Quando emetti la richiesta, devi specificare nel corpo della richiesta l'importo da aggiungere al saldo e la valuta utilizzata.

Ad esempio, la seguente richiesta aggiunge 1000 $al saldo dell'account prepagato di uno sviluppatore:

$ 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

Per una descrizione delle proprietà della richiesta, consulta Riepilogo delle proprietà delle richieste per il ricaricamento di un account prepagato.

Ricaricare il saldo di un account prepagato per un'azienda

Per ricaricare il saldo di un account prepagato per un'azienda che utilizza l'API, invia una richiesta POST a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, dove {company_id} è l'ID dell'azienda. Quando emetti la richiesta, devi specificare nel corpo della richiesta l'importo da aggiungere al saldo e la valuta utilizzata.

Ad esempio, la seguente richiesta aggiunge 1000 $al saldo dell'account prepagato di un'azienda:

$ 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

Per una descrizione delle proprietà della richiesta, consulta Riepilogo delle proprietà delle richieste per il ricaricamento di un account prepagato.

Riepilogo delle proprietà della richiesta per il ricaricamento di un account prepagato

Le seguenti proprietà devono essere specificate quando ricarichi i saldi degli account prepagati utilizzando l'API:

Eliminare i fornitori di servizi di pagamento di terze parti

Puoi eliminare un fornitore di servizi di pagamento di terze parti configurato per la tua organizzazione Edge inviando una richiesta DELETE alla seguente risorsa:

Per eliminare un fornitore di servizi di pagamento per un'organizzazione specifica, utilizza la seguente API:

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

Solo i clienti Apigee Edge Private Cloud con privilegi di amministratore di sistema possono facoltativamente eliminare un fornitore di pagamenti globale utilizzando la seguente API:

/config/providers/id

Ad esempio, di seguito vengono eliminati i fornitori di servizi di pagamento di terze parti attualmente configurati per myorg:

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

Gestione manuale dei saldi dell'account con pagamento anticipato

In alternativa, puoi gestire il ricaricamento dei saldi prepagati monitorando i pagamenti manualmente o tramite un sistema di fatturazione integrato e poi chiamando l'API di monetizzazione per ricaricare l'account, come descritto in Ricaricare il saldo di un account prepagato utilizzando l'API.

Configurazione del ricaricamento automatico dei saldi degli account prepagati utilizzando l'API

Le sezioni seguenti descrivono come configurare il ricaricamento automatico dei saldi degli account prepagati per un sviluppatore o un'azienda che utilizza un fornitore di servizi di pagamento di terze parti. Questa opzione è utile per gestire i pagamenti ricorrenti per i piani tariffari.

Configurazione del ricaricamento automatico dei saldi dell'account con pagamento anticipato per uno sviluppatore

Per configurare il ricaricamento automatico del saldo di un account prepagato per uno sviluppatore quando il saldo scende al di sotto di una determinata soglia, invia una richiesta POST a /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup, dove {developer_id} è l'indirizzo email dello sviluppatore.

Quando emetti la richiesta, devi specificare quanto segue:

• ID del fornitore di servizi di pagamento da utilizzare per ricaricare l'account (providerID)
• Flag che attiva il ricaricamento automatico (isRecurring)
• Soglia alla quale il saldo prepagato dell'account deve scendere al di sotto per attivare il ricaricamento automatico (replenishAmount)
• Importo da aggiungere automaticamente all'account (recurringAmount)
• Il parametro di query supportedCurrencyID per specificare la valuta.

Nel seguente esempio, quando il saldo prepagato dello sviluppatore scende al di sotto di 5 dollari statunitensi, altri 10 dollari statunitensi verranno aggiunti automaticamente all'account.

$ 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

Per una descrizione delle proprietà della richiesta, consulta Riepilogo delle proprietà delle richieste per la configurazione del ricaricamento automatico di account prepagati.

Configurazione del ricaricamento automatico dei saldi dell'account con pagamento anticipato per un'azienda

Per configurare il ricaricamento automatico del saldo di un account prepagato per un'azienda quando il saldo scende al di sotto di un determinato importo, invia una richiesta POST a /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup, dove {company_id} è l'ID dell'azienda.

Quando emetti la richiesta, devi specificare quanto segue:

• ID del fornitore di servizi di pagamento da utilizzare per ricaricare l'account (providerID)
• Flag che attiva il ricaricamento automatico (isRecurring)
• Soglia al di sotto della quale deve scendere il saldo dell'account prepagato per attivare il ricaricamento automatico (replenishAmount)
• Importo da aggiungere automaticamente all'account (recurringAmount)
• Il parametro di query supportedCurrencyID per specificare la valuta.

Nel seguente esempio, quando il saldo dell'account prepagato dell'azienda scende al di sotto di 5 $, all'account verranno aggiunti automaticamente altri 10 $.

$ 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

Per una descrizione delle proprietà della richiesta, consulta Riepilogo delle proprietà della richiesta per la configurazione del ricaricamento automatico di un account prepagato.

Riepilogo delle proprietà della richiesta per la configurazione del ricaricamento automatico degli account prepagati

I seguenti attributi possono essere specificati quando si ricaricano automaticamente i saldi degli account prepagati utilizzando l'API.

Migrazione alle pagine dei pagamenti ospitati di WorldPay

WorldPay ha aggiornato il flusso di elaborazione dei pagamenti sicuri per utilizzare un nuovo insieme di pagine, chiamate Pagamenti ospitati.

Se hai configurato i tuoi fornitori di servizi di pagamento WorldPay utilizzando il flusso di elaborazione dei pagamenti sicuri ritirato (prima di agosto 2017), dovrai eseguire la migrazione alle nuove pagine di pagamento ospitate di WorldPay prima di gennaio 2018.

Per eseguire la migrazione alle pagine di pagamento ospitate di WorldPay:

1. Contatta WorldPay per eseguire la migrazione del tuo account attuale in modo da utilizzare le nuove pagine di pagamento ospitate e ottenere un nuovo ID installazione per il tuo account.
2. Configura i nuovi fornitori di servizi di pagamento WorldPay, come descritto in Configurare il fornitore di servizi di pagamento in Edge, passando l'ID installazione nel campo authType.
3. Configura i nuovi fornitori di servizi di pagamento nel tuo Developer Portal, come descritto in Configurare la monetizzazione nello Developer Portal.
4. Se hai configurato il ricaricamento automatico di un account prepagato utilizzando il provider di servizi di pagamento, devi riconfigurare il ricaricamento automatico per utilizzare il nuovo ID provider, come descritto in Configurare il ricaricamento automatico dei saldi degli account prepagati utilizzando l'API.

Passaggi successivi

Puoi impostare limiti di credito per singoli sviluppatori con abbonamento postpaid. Per ulteriori informazioni, consulta Gestire i saldi con pagamento posticipato.