Gestisci i saldi prepagati degli account

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Per gestire il saldo di un account prepagato, puoi:

• Visualizza il saldo attuale dell'account prepagato. Consulta la sezione Visualizzazione dei saldi degli account prepagati tramite l'API.
• Ricarica (aggiungi denaro) il saldo del conto in base alle esigenze utilizzando un fornitore di servizi di pagamento di terze parti, come Worldpay. Consulta l'articolo Gestire i saldi prepagati utilizzando un fornitore di servizi di pagamento di terze parti.

  In alternativa, puoi gestire la ricarica 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 Gestire manualmente i saldi prepagati.

• Configura la ricarica automatica quando il saldo dell'account prepagato scende al di sotto di una determinata soglia utilizzando l'API monetization e un fornitore di servizi di pagamento di terze parti, ad esempio Worldpay. Questa opzione è utile per gestire i pagamenti ricorrenti per i piani tariffari. Per informazioni, consulta Configurazione della ricarica automatica dei saldi prepagati dell'account tramite l'API.

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

Quando visualizzi il saldo dell'account prepagato per uno sviluppatore o una società, come descritto nelle sezioni seguenti, devi ottenere i seguenti valori dalla risposta:

• amount: L'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: l'importo totale di denaro utilizzato durante il periodo di fatturazione corrente. Questo valore viene aggiornato a ogni transazione monetizzata idonea o tramite l'emissione di un credito (positivo o negativo).

Puoi calcolare il saldo prepagato rimanente dell'account per il periodo di fatturazione corrente 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 verrà calcolato nel seguente modo:

amount(335.50) - usage(34) = 229.50

Visualizzare i saldi dell'account prepagato utilizzando l'API

Le sezioni seguenti descrivono come visualizzare i saldi degli account prepagati per uno sviluppatore o un'azienda utilizzando l'API.

Visualizzare i saldi dell'account con pagamento anticipato per uno sviluppatore

Per visualizzare i saldi degli account prepagati 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 del conto prepagato e le informazioni sulla configurazione ricorrente per uno sviluppatore.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: restituisce informazioni sul saldo del conto prepagato, tra cui saldo attuale e totale, utilizzo, ricariche e imposta di utilizzo.

Puoi trasmettere 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 dell'account con pagamento anticipato per un'azienda

Per visualizzare i saldi degli account prepagati di 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 prepagato corrente dell'account. Se l'azienda è in postpagamento, la richiesta recupera il limite di credito attuale.

Puoi trasmettere 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 si visualizzano i saldi degli account prepagati per uno sviluppatore.

Gestire i saldi dell'account prepagato utilizzando un fornitore di servizi di pagamento

Gestisci i saldi dell'account prepagato configurando un account commerciante con un fornitore di pagamenti di terze parti, come Worldpay. La figura seguente mostra come vengono gestiti i saldi degli account prepagati 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:

• Configurazione di 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
• Attivazione e configurazione dei moduli richiesti nel portale per gli sviluppatori
• Avvio del pagamento a un account prepagato utilizzando un fornitore di servizi di pagamento
• Ricaricare il saldo dell'account prepagato utilizzando l'API
• Eliminazione di 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 saperne di più sugli account commerciante Worldpay, visita www.worldpay.com e wp-support.crm.worldpay.com (Centro assistenza Worldpay).

Dopo aver configurato il tuo account commerciante e 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 del messaggio (MAC):
   1. Fai clic su Profilo.
   2. Imposta la password da utilizzare durante la configurazione del fornitore di servizi di pagamento Worldpay in Edge nel campo Password XML.
   3. Inserisci una chiave segreta MAC di 20-30 caratteri nel campo Segreto MAC di reindirizzamento.
   4. Fai clic su Salva profilo.
4. Aggiungi il server di gestione Apigee Edge all'elenco degli IP del commerciante (lista consentita):
   1. Fai clic su Profilo > Ambiente 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 ospitate > Strumento di progettazione della pagina di pagamento.
   2. Nella sezione Modifica pagine di pagamento, seleziona l'ID installazione dall'elenco a discesa Seleziona canale.
   3. Nella scheda Proprietà, seleziona Modifica configurazione commerciante.
   4. Imposta il valore del parametro Invia parametri URL su True.
   5. Fai clic sulla scheda Pubblica.
   6. Promuovi le modifiche nel seguente modo:
      • Per gli ambienti di test, fai clic su Promuovi in Progettazione per promuovere da Progettazione a Sandbox.
      • Per gli ambienti di produzione, fai clic su Promuovi in Sandbox per promuovere da Sandbox a 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 una specifica organizzazione utilizzando la seguente API:

/organizations/{org-name}/providers

Solo i clienti di Apigee Edge Private Cloud con privilegi di amministratore di sistema possono configurare facoltativamente 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 seguente comando 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 pagamenti 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 visualizzati i fornitori 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 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 sviluppatori quando i consumatori di API:

• Accettare un piano tariffario, ma non disporre di fondi sufficienti nel proprio account prepagato
• Richiesta di aggiungere denaro al suo 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 invii la richiesta, devi specificare i seguenti valori come parametri di query:

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

Inoltre, devi superare i controlli di base dei dettagli dell'account, ad esempio l'indirizzo di fatturazione dell'azienda.

Ad esempio, il seguente ricarica il saldo dell'account prepagato utilizzando il fornitore di servizi di pagamento Worldpay. Il trasferimento iniziale al tuo account prepagato sarà di 10 dollari statunitensi (il parametro di query amount è 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 è riportato un esempio di risposta:

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

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

Ricaricare il saldo dell'account prepagato utilizzando l'API

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

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

Ricarica del saldo dell'account prepagato per uno sviluppatore

Per ricaricare il saldo dell'account prepagato per uno sviluppatore utilizzando 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 invii 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 prepagato dell'account 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, vedi Riepilogo delle proprietà della richiesta per ricaricare un account prepagato.

Ricaricare il saldo dell'account prepagato per un'azienda

Per ricaricare il saldo dell'account prepagato per un'azienda utilizzando l'API, invia una richiesta POST a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, dove {company_id} è l'ID dell'azienda. Quando invii 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, vedi Riepilogo delle proprietà della richiesta per ricaricare un account prepagato.

Riepilogo delle proprietà della richiesta per ricaricare un account prepagato

Quando ricarichi i saldi degli account prepagati utilizzando l'API, devi specificare le seguenti proprietà:

Eliminazione dei 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 di Apigee Edge Private Cloud con privilegi di amministratore di sistema possono eliminare facoltativamente un fornitore di servizi di pagamento globale utilizzando la seguente API:

/config/providers/id

Ad esempio, il seguente comando elimina i fornitori 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

Gestire manualmente i 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 dell'account prepagato utilizzando l'API.

Configurazione della ricarica automatica dei saldi dell'account prepagato utilizzando l'API

Le sezioni seguenti descrivono come configurare la ricarica automatica dei saldi degli account prepagati per uno 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 della ricarica automatica dei saldi dell'account prepagato per uno sviluppatore

Per configurare la ricarica automatica 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 invii la richiesta, devi specificare quanto segue:

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

Nell'esempio seguente, quando il saldo dell'account prepagato dello sviluppatore 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}/developers/{developer_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

Per una descrizione delle proprietà della richiesta, vedi Riepilogo delle proprietà della richiesta per la configurazione della ricarica automatica di un account prepagato.

Configurazione della ricarica automatica dei saldi dell'account prepagato per un'azienda

Per configurare la ricarica automatica 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 invii la richiesta, devi specificare quanto segue:

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

Nell'esempio seguente, 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, vedi Riepilogo delle proprietà della richiesta per la configurazione della ricarica automatica di un account prepagato.

Riepilogo delle proprietà della richiesta per la configurazione della ricarica automatica degli account prepagati

Quando ricarichi automaticamente i saldi degli account prepagati utilizzando l'API, puoi specificare i seguenti attributi.

Migrazione alle pagine di pagamento ospitate di WorldPay

WorldPay ha aggiornato il flusso di elaborazione dei pagamenti sicuri per utilizzare un nuovo insieme di pagine, denominate pagine di pagamento ospitate.

Se hai configurato i tuoi fornitori di servizi di pagamento WorldPay utilizzando il flusso di elaborazione dei pagamenti sicuri deprecato (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 che utilizzi le nuove pagine di pagamento ospitate e ottieni un nuovo ID installazione per il tuo account.
2. Configura i nuovi fornitori di servizi di pagamento WorldPay, come descritto in Configurazione del 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 portale per sviluppatori, come descritto in Configura la monetizzazione nel portale per sviluppatori.
4. Se configuri la ricarica automatica di un account prepagato utilizzando il fornitore di servizi di pagamento, devi riconfigurare la ricarica automatica in modo da utilizzare il nuovo ID fornitore, come descritto in Configurazione della ricarica automatica dei saldi degli account prepagati utilizzando l'API.

Passaggi successivi

Puoi impostare limiti di credito per i singoli sviluppatori con pagamento posticipato. Scopri come fare in Gestire i saldi postpagati.