Zarządzanie saldami kont rozliczanych w systemie przedpłat

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Aby zarządzać saldem na koncie z przedpłatą, możesz:

• Wyświetlanie bieżącego salda konta przedpłaconego. Zobacz wyświetlanie sald kont przedpłaconych za pomocą interfejsu API.
• Doładuj saldo konta (dodawaj środki) w miarę potrzeby za pomocą zewnętrznego dostawcy płatności, takiego jak Worldpay. Zobacz artykuł Zarządzanie saldami przedpłaconymi za pomocą zewnętrznego dostawcy płatności.

  Możesz też zarządzać ponownym wczytaniem, śledząc płatności ręcznie lub za pomocą zintegrowanego systemu rozliczeniowego, a potem wywołać interfejs Monetyzacja API, aby ponownie załadować konto, zgodnie z opisem w artykule Ręczne zarządzanie saldami przedpłaconymi.

• Skonfiguruj automatyczne doładowanie, gdy saldo konta przedpłaconego spadnie poniżej określonego progu, korzystając z interfejsu API do zarabiania i zewnętrznego dostawcy usług płatniczych, takiego jak Worldpay. Ta opcja jest przydatna do zarządzania płatnościami cyklicznymi w przypadku planów cenowych. Więcej informacji znajdziesz w artykule Konfigurowanie automatycznego doładowywania salda konta prepaid za pomocą interfejsu API.

Jak obliczyć pozostałą wartość konta przedpłaconego?

Podczas wyświetlania salda konta z przedpłatą dewelopera lub firmy, jak opisano w następnych sekcjach, musisz uzyskać z odpowiedzi te wartości:

• amount: łączna kwota pieniędzy dostępna w bieżącym okresie rozliczeniowym. Ta wartość jest aktualizowana po ponownym załadowaniu konta przedpłaconego za pomocą metod opisanych w tej sekcji.
• usage: łączna kwota pieniędzy wykorzystana w bieżącym okresie rozliczeniowym. Ta wartość jest aktualizowana przy każdej kwalifikującej się transakcji zarabiania lub przez wydanie zwrotu środków (dodatniego lub ujemnego).

Pozostały stan środków na koncie z przedpłatą na bieżący okres rozliczeniowy możesz obliczyć, odejmując wartość usage od wartości amount. Jeśli na przykład amount ma wartość 335,50, a wartość usage to 34, pozostałe saldo zostanie obliczone w następujący sposób:

amount(335.50) - usage(34) = 229.50

Wyświetlanie sald kont przedpłaconych za pomocą interfejsu API

W następnych sekcjach opisujemy, jak wyświetlić salda na koncie pre-paid dewelopera lub firmy za pomocą interfejsu API.

Wyświetlanie salda kont przedpłaconych w przypadku dewelopera

Aby wyświetlić saldo konta z przedpłatą dewelopera, prześlij żądanie GET do jednego z tych interfejsów API, gdzie {developer_id} to adres e-mail dewelopera:

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: zwraca saldo konta z przedpłatą i informacje o powtarzających się płatnościach dla dewelopera.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: zwraca informacje o saldzie na koncie przedpłaconym, w tym saldo bieżące i łączne, wykorzystanie, doładowania i podatek od użytkowania.

Aby filtrować wyniki, możesz podać te parametry zapytania:

Na przykład:

$ 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

Poniżej przedstawiamy przykład odpowiedzi:

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

Wyświetlanie sald z przedpłatą na koncie firmy

Aby wyświetlić saldo konta z przedpłatą firmy, wyślij żądanie GET do adresu /mint/organizations/{org_name}/companies/{company_id}/developer-balances, gdzie {company_id} to identyfikator firmy. Jeśli firma korzysta z przedpłaty, żądanie pobiera aktualne saldo konta przedpłaconego. Jeśli firma korzysta z systemu postpaid, prośba pobiera aktualny limit kredytowy.

Aby filtrować wyniki, możesz podać te parametry zapytania:

Na przykład:

$ 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

Odpowiedź jest podobna do tej, która jest widoczna powyżej, gdy sprawdzasz salda na koncie pre-paid dewelopera.

Zarządzanie saldami na kontach przedpłaconych za pomocą dostawcy płatności

Zarządzaj saldami na koncie przedpłaconym, konfigurując konto sprzedawcy u zewnętrznego dostawcy płatności, takiego jak Worldpay. Rysunek poniżej pokazuje, jak zarządzać saldem konta przedpłaconego za pomocą dostawcy płatności Worldpay.

Poniższa tabela opisuje poszczególne kroki procesu zarządzania saldem na koncie z przedpłatą, który został przedstawiony powyżej.

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

W następnych sekcjach znajdziesz instrukcje zarządzania saldami przedpłaconymi za pomocą zewnętrznego dostawcy płatności:

• Konfigurowanie konta sprzedawcy u dostawcy płatności Worldpay
• Konfigurowanie dostawcy płatności w Edge
• Wyświetlanie dostawców płatności skonfigurowanych w organizacji
• Włączanie i konfigurowanie wymaganych modułów w portalu dla programistów
• Inicjowanie płatności na konto przedpłacone za pomocą dostawcy płatności
• Doładowywanie salda na koncie prepaid za pomocą interfejsu API
• Usuwanie zewnętrznego dostawcy usług płatniczych

Konfigurowanie konta sprzedawcy u dostawcy płatności Worldpay

Zanim zaczniesz, musisz skontaktować się z zewnętrznym dostawcą płatności (Worldpay), aby skonfigurować swoje konto sprzedawcy. Zalecamy skonfigurowanie 2 kont – jednego do testowania i jednego do środowiska produkcyjnego. Więcej informacji o kontach sprzedawców w Worldpay znajdziesz na stronie www.worldpay.com i wp-support.crm.worldpay.com (centrum pomocy Worldpay).

Gdy skonfigurujesz konto sprzedawcy i otrzymasz dane logowania, aby skonfigurować konto sprzedawcy w Worldpay:

1. Otwórz stronę https://secure.worldpay.com/sso/public/auth/login.html.
2. Zaloguj się na konto Worldpay, używając danych logowania otrzymanych od Worldpay.
3. Ustaw hasło XML i klucz tajny kodu uwierzytelniania wiadomości (MAC):
   1. Kliknij Profil.
   2. W polu Hasło XML w Edge ustaw hasło, którego chcesz używać podczas konfigurowania dostawcy płatności Worldpay.
   3. W polu Przekieruj klucz tajny MAC wpisz klucz tajny MAC o długości od 20 do 30 znaków.
   4. Kliknij Zapisz profil.
4. Dodaj serwer zarządzania Apigee Edge do listy adresów IP sprzedawcy (lista dozwolonych):
   1. Kliknij Profil > Środowisko sprzedawcy.
   2. Kliknij Nowy testowy adres IP.
   3. Wpisz adres IP serwera zarządzania Apigee Edge.
   4. Kliknij Zapisz.
5. Skonfiguruj adres URL sprzedawcy, aby dodać parametry Worldpay, w tym kod uwierzytelniania metody (MAC):
   1. Kliknij Instalacje > Hostowane strony płatności > Designer strony płatności.
   2. W sekcji Edytuj strony płatności wybierz identyfikator instalacji z listy Wybierz kanał.
   3. Na karcie Właściwości kliknij Edytuj konfigurację sprzedawcy.
   4. Ustaw wartość parametrów wysyłania adresu URL na True.
   5. Kliknij kartę Publikowanie.
   6. Promowanie zmian w ten sposób:
      • W przypadku środowisk testowych kliknij Promuj w sekcji Projektowanie, aby zmienić wersję z projektu do piaskownicy.
      • W przypadku środowisk produkcyjnych kliknij Promote (Promouj) w sekcji Sandbox, aby przenieść piaskownicę do środowiska produkcyjnego.

Konfigurowanie dostawcy płatności w Edge

Następnie skonfiguruj dostawcę płatności w Edge.

Za pomocą tych interfejsów API możesz skonfigurować dostawcę płatności dla określonej organizacji:

/organizations/{org-name}/providers

Tylko klienci Apigee Edge Private Cloud z uprawnieniami administratora Sys mogą opcjonalnie skonfigurować globalnego dostawcę usług płatniczych przy użyciu tego interfejsu API:

/config/providers

Podczas wywoływania każdego interfejsu API musisz w treści żądania podać te informacje:

Na przykład poniższy kod skonfiguruje konto sprzedawcy w Worldpay o nazwie 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 

Wyświetlanie zewnętrznych dostawców usług płatniczych

Aby wyświetlić i potwierdzić zewnętrznych dostawców płatności skonfigurowanych dla organizacji w Edge, wyślij żądanie GET do tego zasobu:

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

Na przykład w następującym przykładzie wyświetlają się dostawcy płatności zewnętrznych skonfigurowani obecnie w przypadku myorg:

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

Poniżej przedstawiamy przykład odpowiedzi z 2 kontami sprzedawcy: jednym do testów, a drugim do celów produkcyjnych.

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

Włączanie i konfigurowanie modułów Monetization i Worldpay w portalu dla programistów

Włącz wymagane moduły Monetization i Worldpay w portalu dla deweloperów. Więcej informacji znajdziesz w artykule Konfigurowanie funkcji zarabiania w portalu deweloperskim.

Inicjowanie płatności na konto przedpłacone u dostawcy usług płatniczych

Jak pokazano w kroku 2 procesu zarządzania kontem przedpłaconym, płatność na konto przedpłacone za pomocą dostawcy płatności jest inicjowana przez portal deweloperski, gdy: użytkownicy interfejsu API:

• akceptują plan taryfowy, ale mają niewystarczające środki na koncie przedpłaconym;
• poprosić o dodanie środków na konto przedpłacone.

Aby zainicjować płatność od zewnętrznego dostawcy płatności za pomocą interfejsu API, wyślij żądanie POST do tego zasobu, gdzie {developer_id} to adres e-mail dewelopera.

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

Po wysłaniu żądania musisz określić te wartości jako parametry zapytania:

• Kwota do dodania do salda konta z przedpłatą (amount={amount})
• Identyfikator dostawcy płatności (provider={providerId})
• Obsługiwana waluta (supportedCurrencyId={currency})

Musisz też podać podstawowe informacje o koncie, takie jak adres rozliczeniowy firmy.

Poniższy przykład pokazuje ponowne wczytanie salda konta przedpłaconego za pomocą dostawcy usług płatniczych Worldpay. Początkowy przelew na konto przedpłacone wynosi 10 USD (amountparametr zapytania jest ustawiony na 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

Oto przykład takiej odpowiedzi:

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

Adres URL strony bezpiecznych płatności Worldpay jest zwracany w referenceUrl z Twoim unikalnym kluczem zamówienia dołączonym jako parametr zapytania.

Doładowywanie salda na koncie przedpłaconym za pomocą interfejsu API

Jak pokazano w kroku 15 procesu zarządzania przedpłaconym kontem, po sprawdzeniu poprawności przetwarzania przez dostawcę usług portal dla programistów wysyła do Edge żądanie ponownego załadowania konta przedpłaconego.

Możesz doładować saldo konta prepaid za pomocą interfejsu API dla dewelopera lub firmy, jak opisano w następnych sekcjach.

Doładowywanie salda na koncie z przedpłatą należącym do dewelopera

Aby ponownie załadować przedpłacone saldo konta dewelopera za pomocą interfejsu API, wyślij żądanie POST na adres /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, gdzie {developer_id} to adres e-mail dewelopera. Podczas wysyłania żądania musisz w jego treści podać kwotę do dodania do salda i używaną walutę.

Na przykład ta prośba zwiększa saldo konta pre-paid dewelopera o 1000 USD:

$ 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

Opis właściwości żądania znajdziesz w artykule Podsumowanie właściwości żądania służących do doładowania konta prepaid.

Ponowne ładowanie salda konta przedpłaconego dla firmy

Aby doładować saldo konta przedpłaconego firmy za pomocą interfejsu API, wyślij żądanie POST do adresu /mint/organizations/{org_name}/companies/{company_id}/developer-balances, gdzie {company_id} to identyfikator firmy. Podczas wysyłania żądania musisz w jego treści podać kwotę do dodania do salda i używaną walutę.

Na przykład następująca prośba zwiększa saldo konta przedpłaconego firmy o 1000 USD:

$ 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

Opis właściwości żądania znajdziesz w artykule Podsumowanie właściwości żądania służących do doładowania konta prepaid.

Podsumowanie właściwości żądania dotyczącego ponownego załadowania konta przedpłaconego

Podczas doładowywania salda na koncie przedpłaconym za pomocą interfejsu API należy podać te właściwości:

Usuwanie zewnętrznych dostawców usług płatniczych

Aby usunąć zewnętrznego dostawcę płatności skonfigurowanego w organizacji Edge, wyślij żądanie DELETE do tego zasobu:

Aby usunąć dostawcę płatności dla konkretnej organizacji, użyj tych interfejsów API:

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

Tylko klienci Apigee Edge Private Cloud z uprawnieniami administratora systemu mogą opcjonalnie usunąć globalnego dostawcę płatności za pomocą tych interfejsów API:

/config/providers/id

Przykład poniżej spowoduje usunięcie zewnętrznych dostawców płatności, którzy są obecnie skonfigurowani dla mojej organizacji:

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

Ręczne zarządzanie saldami na kontach z przedpłatą

Możesz też zarządzać doładowaniem sald przedpłaconych, śledząc płatności ręcznie lub przez zintegrowany system rozliczeniowy, a następnie wywołując interfejs API monetyzacji w celu ponownego załadowania konta zgodnie z opisem w sekcji Ponowne ładowanie salda konta przedpłaconego za pomocą interfejsu API.

Konfigurowanie automatycznego doładowywania salda na koncie przedpłaconym za pomocą interfejsu API

W następnych sekcjach opisujemy, jak skonfigurować automatyczne doładowywanie salda na koncie z użyciem przedpłaconej karty płatniczej przez dewelopera lub firmę korzystającą z usług zewnętrznego dostawcy płatności. Ta opcja jest przydatna do zarządzania płatnościami cyklicznymi w przypadku abonamentów.

Konfigurowanie automatycznego doładowywania salda na koncie przedpłaconym dewelopera

Aby skonfigurować automatyczne doładowywanie salda konta przedpłaconego dewelopera, gdy saldo spadnie poniżej określonego progu, wyślij żądanie POST na adres /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup, gdzie {developer_id} to adres e-mail dewelopera.

Podczas wysyłania żądania musisz podać:

• Identyfikator dostawcy usług płatniczych, którego chcesz użyć do ponownego załadowania konta (providerID)
• Flaga, która włącza automatyczne odświeżanie (isRecurring)
• Próg, poniżej którego musi spaść saldo konta przedpłaconego, aby włączyć automatyczne doładowanie (replenishAmount)
• Kwota do automatycznego dodania na konto (recurringAmount)
• parametru zapytania supportedCurrencyID, aby określić walutę.

W tym przykładzie, gdy saldo konta pre-paid dewelopera spadnie poniżej 5 USD, na konto zostanie automatycznie dodana kwota 10 USD.

$ 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

Opis właściwości żądania znajdziesz w artykule Podsumowanie właściwości żądania do automatycznego doładowywania kont przedpłaconych.

Konfigurowanie automatycznego doładowywania salda na koncie przedpłaconym firmy

Aby skonfigurować automatyczne doładowywanie salda na koncie przedpłaconym firmy, gdy saldo spadnie poniżej określonej kwoty, wyślij żądanie POST do adresu /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup, gdzie {company_id} to identyfikator firmy.

Podczas wysyłania żądania musisz podać:

• Identyfikator dostawcy płatności, którego chcesz użyć do ponownego załadowania konta (providerID)
• Flaga, która umożliwia automatyczne odświeżanie (isRecurring)
• Próg, poniżej którego musi spaść saldo konta przedpłaconego, aby włączyć automatyczne doładowanie (replenishAmount)
• Kwota do automatycznego dodania na konto (recurringAmount)
• parametru zapytania supportedCurrencyID, aby określić walutę.

W poniższym przykładzie, gdy saldo konta firmy z przedpłaty spadnie poniżej 5 USD, do konta automatycznie zostanie dodanych 10 USD.

$ 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

Opis właściwości żądania znajdziesz w artykule Podsumowanie właściwości żądania do automatycznego doładowywania kont przedpłaconych.

Podsumowanie właściwości żądania służących do konfigurowania automatycznego przeładowywania kont przedpłaconych

Podczas automatycznego doładowywania salda na koncie prepaid za pomocą interfejsu API możesz podać te atrybuty:

Migracja na hostowane strony płatności WorldPay

Firma WorldPay zaktualizowała proces bezpiecznego przetwarzania płatności, aby używać nowego zestawu stron, zwanych stronami płatności hostowanych.

Jeśli dostawca płatności WorldPay został skonfigurowany z użyciem przestarzałego procesu przetwarzania bezpiecznych płatności (przed sierpniem 2017 r.), przed styczniem 2018 r. musisz przejść na nowe strony płatności hostowanych WorldPay.

Aby przejść na hostowane strony płatności WorldPay:

1. Skontaktuj się z WorldPay, aby przenieść swoje obecne konto na nowe hostowane strony płatności i uzyskać nowy identyfikator instalacji dla swojego konta.
2. Skonfiguruj nowych dostawców płatności WorldPay zgodnie z opisem w artykule Konfigurowanie dostawcy płatności w Edge, przekazując identyfikator instalacji w polu authType.
3. Skonfiguruj nowych dostawców płatności na portalu dewelopera zgodnie z instrukcjami podanymi w artykule Konfigurowanie zarabiania na portalu dewelopera.
4. Jeśli skonfigurujesz automatyczne doładowywanie salda na koncie przedpłaconym za pomocą dostawcy płatności, musisz ponownie skonfigurować automatyczne doładowywanie, aby używać nowego identyfikatora dostawcy zgodnie z opisem w artykule Konfigurowanie automatycznego doładowywania salda na koncie przedpłaconym za pomocą interfejsu API.

Dalsze kroki

Możesz ustawić limity środków dla poszczególnych deweloperów korzystających z płatności odroczonej. Dowiedz się więcej na ten temat w artykule Zarządzanie saldami abonamentowymi.