Gestire i saldi prepagati dell'account

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

Per gestire il saldo di un account prepagato, puoi:

• Visualizzare il saldo prepagato corrente dell'account. Consulta la sezione Visualizzare i saldi prepagati degli account tramite l'API.
• Ricarica (aggiungi denaro) il saldo dell'account come richiesto utilizzando un fornitore di servizi di pagamento di terze parti, ad esempio Worldpay. Vedi 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 quindi chiamando l'API di monetizzazione per ricaricare l'account, come descritto in Gestire i saldi prepagati manualmente.

• 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 dei piani tariffari. Per informazioni, consulta Configurare il ricaricamento automatico dei saldi prepagati degli account utilizzando l'API.

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

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

• amount: importo totale 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 emettendo un credito (positivo o negativo).

Puoi calcolare il saldo prepagato rimanente dell'account per il periodo di fatturazione corrente sottraendo il valore di usage dal valore di 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

Visualizzare i saldi prepagati degli account utilizzando l'API

Le seguenti sezioni descrivono come visualizzare i saldi prepagati dei conti per uno sviluppatore o una società utilizzando l'API.

Visualizzare i saldi prepagati dell'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 prepagato dell'account e le informazioni di configurazione ricorrenti per uno sviluppatore.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: restituisce informazioni sul saldo prepagato dell'account, inclusi saldo corrente e totale, utilizzo, ricariche e imposte sull'utilizzo.

Per filtrare i risultati, puoi passare i seguenti parametri di query:

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 della 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 prepagati degli account di un'azienda

Per visualizzare i saldi prepagati dell'account di una società, invia una richiesta GET a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, dove {company_id} è l'ID dell'azienda. Se l'azienda ha scelto il pagamento anticipato, la richiesta recupera il saldo prepagato corrente dell'account. Se l'azienda prevede il pagamento posticipato, la richiesta recupera il massimale di credito attuale.

Per filtrare i risultati, puoi passare i seguenti parametri di query:

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 prepagati dell'account di uno sviluppatore.

Gestione dei saldi prepagati dell'account tramite un fornitore di servizi di pagamento

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

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

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

Le seguenti sezioni 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
• Configurazione del fornitore di servizi di pagamento in Edge
• Visualizzare i fornitori di servizi di pagamento configurati per la tua organizzazione
• Abilitazione e configurazione dei moduli richiesti nel portale per gli sviluppatori
• Avvio di un pagamento su un account prepagato utilizzando un fornitore di servizi di pagamento
• Ricaricare un saldo prepagato dell'account tramite l'API
• Eliminare un fornitore di servizi di pagamento di terze parti

Creazione 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 (Worldpay support center).

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 MAC (Message Authentication Code):
   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 secret MAC di lunghezza compresa tra 20 e 30 caratteri nel campo Secret MAC di reindirizzamento.
   4. Fai clic su Salva profilo.
4. Aggiungi il server di gestione Apigee Edge all'elenco di IP dei commercianti (lista consentita):
   1. Fai clic su Profilo > Ambiente commerciante.
   2. Fai clic su Nuovo IP di test.
   3. Inserisci l'IP per il server di gestione Apigee Edge.
   4. Fai clic su Salva.
5. Configura l'URL del commerciante per aggiungere i parametri di Worldpay, incluso il codice MAC (Method Authentication Code):
   1. Fai clic su Installazioni > Pagine pagamenti ospitate > Designer pagine pagamenti.
   2. In Modifica pagine di pagamento, seleziona il tuo ID di installazione dall'elenco a discesa Seleziona canale.
   3. Nella scheda Proprietà, seleziona Modifica configurazione commerciante.
   4. Imposta il valore dei parametri URL di invio su True.
   5. Fai clic sulla scheda Pubblica.
   6. Per promuovere le modifiche:
      • Per gli ambienti di test, fai clic su Promuovi in Design per passare dalla fase di progettazione alla 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 nella configurazione del 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 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, la procedura riportata di seguito consente di configurare 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 

Visualizzazione dei 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 sono riportati 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 della 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"
  } ]
}

Abilitazione e configurazione dei moduli Monetizzazione e Worldpay nel portale per gli sviluppatori

Attiva i moduli Monetizzazione e Worldpay richiesti nel portale per gli sviluppatori. Per maggiori dettagli, consulta la sezione Configurare la monetizzazione nel Portale per gli sviluppatori.

Avvio di un pagamento a favore di 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 dell'API:

• Accettare un piano tariffario, ma disporre di fondi insufficienti nell'account prepagato
• Richiedere l'aggiunta di denaro all'account prepagato.

Per disporre 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 ricerca:

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

Inoltre, devi trasmettere i dettagli di base dell'account, come l'indirizzo di fatturazione dell'azienda.

Ad esempio, quanto riportato di seguito consente di ricaricare un saldo prepagato dell'account utilizzando il fornitore di servizi di pagamento Worldpay. Il trasferimento iniziale al 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 è riportato 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 della pagina dei pagamenti sicuri di Worldpay viene restituito nel formato referenceUrl con la tua chiave d'ordine univoca aggiunta come parametro di ricerca.

Ricaricare un saldo prepagato dell'account tramite l'API

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

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

Ricaricare il saldo di un account prepagato per uno sviluppatore

Per ricaricare il saldo prepagato dell'account di 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 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 il riepilogo delle proprietà della richiesta per il ricaricamento di un account prepagato.

Ricaricare il saldo prepagato di un account 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 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 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 il riepilogo delle proprietà della richiesta per il ricaricamento di un account prepagato.

Riepilogo delle proprietà della richiesta per ricaricare un account prepagato

Quando ricarichi i saldi prepagati dell'account tramite l'API, è necessario 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 facoltativamente eliminare un fornitore di servizi di pagamento globale utilizzando la seguente API:

/config/providers/id

Ad esempio, quanto segue consente di eliminare 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 prepagati dell'account

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

Configurare il ricaricamento automatico dei saldi prepagati degli account tramite l'API

Le seguenti sezioni descrivono come configurare il ricaricamento automatico dei saldi prepagati dei conti 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.

Configurare il ricaricamento automatico dei saldi prepagati dell'account per uno sviluppatore

Per configurare il ricaricamento automatico di un saldo prepagato dell'account 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 consente il ricaricamento automatico (isRecurring)
• Soglia a cui il saldo prepagato dell'account deve essere inferiore per attivare il ricaricamento automatico (replenishAmount)
• Importo da aggiungere automaticamente all'account (recurringAmount)
• supportedCurrencyID per specificare la valuta.

Nell'esempio seguente, 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 il riepilogo delle proprietà della richiesta per la configurazione del ricaricamento automatico di un account prepagato.

Impostazione del ricaricamento automatico dei saldi prepagati degli account per un'azienda

Per configurare il ricaricamento automatico di un saldo prepagato dell'account per una società 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 consente il ricaricamento automatico (isRecurring)
• Soglia a cui il saldo prepagato dell'account deve essere inferiore per attivare il ricaricamento automatico (replenishAmount)
• Importo da aggiungere automaticamente all'account (recurringAmount)
• supportedCurrencyID per specificare la valuta.

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

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

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

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

Migrazione alle pagine di pagamento ospitate di WorldPay

WorldPay ha aggiornato il flusso di elaborazione sicura dei pagamenti in modo da utilizzare un nuovo insieme di pagine, note come Pagine dei pagamenti in hosting.

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

Per eseguire la migrazione alle pagine dei pagamenti ospitati di WorldPay:

1. Contatta WorldPay per eseguire la migrazione del tuo account attuale al fine di utilizzare le nuove pagine di pagamento ospitate e ottenere un nuovo ID di 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 di installazione nel campo authType.
3. Configura i nuovi fornitori di servizi di pagamento sul portale per gli sviluppatori, come descritto in Configurare la monetizzazione nel Portale per gli sviluppatori.
4. Se configuri il ricaricamento automatico di un account prepagato utilizzando il fornitore di servizi di pagamento, devi riconfigurare il ricaricamento automatico in modo che utilizzi il nuovo ID fornitore, come descritto in Configurare il ricaricamento automatico dei saldi prepagati degli account tramite l'API.

Passaggi successivi

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