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świetl aktualne saldo konta przedpłaconego. Zobacz Wyświetlanie sald konta przedpłaconego za pomocą interfejsu API.
• W razie potrzeby doładuj saldo konta za pomocą zewnętrznego dostawcy usług płatniczych, np. Worldpay. Zobacz Zarządzanie saldem z przedpłaty za pomocą zewnętrznego dostawcy usług płatniczych.

  Możesz też zarządzać doładowaniem, śledząc płatności ręcznie lub za pomocą zintegrowanego systemu rozliczeniowego, a następnie wywołując interfejs API do zarabiania, aby doładować konto, zgodnie z opisem w sekcji 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 monetyzacji i zewnętrznego dostawcy płatności, np. Worldpay. Ta opcja jest przydatna do zarządzania płatnościami cyklicznymi za pakiety danych. Więcej informacji znajdziesz w artykule Konfigurowanie automatycznego doładowywania sald kont przedpłaconych za pomocą interfejsu API.

Jak obliczyć pozostałe saldo konta przedpłaconego?

Gdy sprawdzasz saldo konta przedpłaconego dewelopera lub firmy (zgodnie z opisem w kolejnych sekcjach), musisz uzyskać z odpowiedzi te wartości:

• amount: Łączna kwota 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 wykorzystanych w bieżącym okresie rozliczeniowym. Ta wartość jest aktualizowana przy każdej kwalifikującej się transakcji z monetyzacją lub przez przyznanie środków (dodatnich lub ujemnych).

Pozostałe saldo konta przedpłaconego w bieżącym okresie rozliczeniowym możesz obliczyć, odejmując wartość usage od wartości amount. Jeśli na przykład wartość amount wynosi 335,50, a wartość usage to 34, pozostałe saldo zostanie obliczone w ten sposób:

amount(335.50) - usage(34) = 229.50

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

W sekcjach poniżej opisujemy, jak za pomocą interfejsu API wyświetlić saldo konta przedpłaconego dewelopera lub firmy.

Wyświetlanie sald kont z przedpłatami dewelopera

Aby wyświetlić saldo konta przedpłaconego dewelopera, wyś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 przedpłaconego i informacje o konfiguracji płatności cyklicznych dewelopera.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: zwraca informacje o saldzie konta przedpłaconego, w tym bieżące i całkowite saldo, wykorzystanie, doładowania i podatek od wykorzystania.

Aby filtrować wyniki, możesz przekazywać 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

Oto 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 kont przedpłaconych firmy

Aby wyświetlić salda kont przedpłaconych 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 bieżące saldo konta przedpłaconego. Jeśli firma korzysta z płatności z dołu, żądanie pobiera aktualny limit kredytowy.

Aby filtrować wyniki, możesz przekazywać 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 odpowiedzi pokazanej powyżej, gdy deweloper wyświetla salda konta przedpłaconego.

Zarządzanie saldami kont przedpłaconych za pomocą dostawcy usług płatniczych

Zarządzaj saldami kont przedpłaconych, konfigurując konto sprzedawcy u zewnętrznego dostawcy usług płatniczych, np. Worldpay. Na ilustracji poniżej pokazano, jak zarządza się saldem konta przedpłaconego za pomocą dostawcy usług płatniczych Worldpay.

Tabela poniżej zawiera opis poszczególnych kroków procesu zarządzania saldem konta przedpłaconego, 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 sekcjach poniżej opisujemy czynności, które należy wykonać, aby zarządzać środkami przedpłaconymi za pomocą zewnętrznego dostawcy usług płatniczych:

• Konfigurowanie konta sprzedawcy u dostawcy płatności Worldpay
• Konfigurowanie dostawcy usług płatniczych 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 usług płatniczych
• Doładowywanie salda konta przedpłaconego za pomocą interfejsu API
• Usuwanie zewnętrznego dostawcy usług płatniczych

Konfigurowanie konta sprzedawcy u dostawcy usług płatniczych Worldpay

Zanim zaczniesz, musisz skontaktować się z zewnętrznym dostawcą usług płatniczych (Worldpay), aby skonfigurować konta sprzedawcy. Zalecamy skonfigurowanie 2 kont: jednego do testowania, a drugiego do środowiska produkcyjnego. Więcej informacji o kontach sprzedawcy Worldpay znajdziesz na stronach www.worldpay.com i wp-support.crm.worldpay.com (Centrum pomocy Worldpay).

Po skonfigurowaniu konta sprzedawcy i otrzymaniu danych logowania do niego, 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 podanych przez Worldpay.
3. Ustaw hasło XML i tajny klucz kodu uwierzytelniania wiadomości (MAC):
   1. Kliknij Profil.
   2. W polu XML Password ustaw hasło, które będzie używane podczas konfigurowania dostawcy usług płatniczych Worldpay w Edge.
   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 dołączyć parametry Worldpay, w tym kod uwierzytelniania metody (MAC):
   1. Kliknij Instalacje > Strony płatności hostowane > Projektant 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ść parametru Wysyłaj parametry adresu URL na Prawda.
   5. Kliknij kartę Publikowanie.
   6. Promuj zmiany w ten sposób:
      • W przypadku środowisk testowych kliknij Promuj w sekcji Projekt, aby przenieść projekt z sekcji Projekt do sekcji Piaskownica.
      • W przypadku środowisk produkcyjnych kliknij Promuj w sekcji Piaskownica, aby przenieść środowisko z piaskownicy do środowiska produkcyjnego.

Konfigurowanie dostawcy usług płatniczych w Edge

Następnym krokiem jest skonfigurowanie dostawcy usług płatniczych w Edge.

Dostawcę usług płatniczych możesz skonfigurować dla konkretnej organizacji za pomocą tego interfejsu API:

/organizations/{org-name}/providers

Tylko klienci Apigee Edge Private Cloud z uprawnieniami administratora systemu mogą opcjonalnie skonfigurować globalnego dostawcę usług płatniczych za pomocą tego interfejsu API:

/config/providers

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

Na przykład poniższy kod konfiguruje 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

Wyświetl i potwierdź dostawców płatności zewnętrznych skonfigurowanych dla Twojej organizacji Edge, wysyłając żądanie GET do tego zasobu:

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

Na przykład poniżej wyświetlają się dostawcy zewnętrznych usług płatniczych skonfigurowani obecnie dla myorg:

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

Poniżej znajdziesz przykład odpowiedzi pokazującej 2 konta sprzedawcy: jedno do testowania, a drugie do produkcji.

{
  "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 Zarabianie i Worldpay w portalu dla programistów

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

Inicjowanie płatności na konto przedpłacone za pomocą dostawcy usług płatniczych

Zgodnie z krokiem 2 procesu zarządzania kontem przedpłaconym płatność na konto przedpłacone za pomocą dostawcy usług płatniczych jest inicjowana przez portal dla programistów, gdy konsumenci interfejsu API:

• zaakceptować abonament, ale nie mieć wystarczających środków na koncie przedpłaconym;
• prośbę o dodanie środków do konta przedpłaconego,

Aby zainicjować płatność od zewnętrznego dostawcy usług płatniczych 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}

W żądaniu musisz podać te wartości jako parametry zapytania:

• Kwota do dodania do salda konta przedpłaconego (amount={amount})
• Identyfikator dostawcy usług płatniczych (provider={providerId})
• Obsługiwana waluta (supportedCurrencyId={currency})

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

Na przykład poniższy kod ponownie doładowuje saldo konta przedpłaconego za pomocą dostawcy płatności Worldpay. Pierwszy przelew na konto przedpłacone wyniesie 10 USD (parametr zapytania amount ma wartość 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 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 dołączonym unikalnym kluczem zamówienia jako parametrem zapytania.

Doładowywanie salda konta przedpłaconego za pomocą interfejsu API

Jak pokazano w kroku 15 procesu zarządzania kontem przedpłaconym, po sprawdzeniu, czy dostawca usług płatniczych przetworzył płatność, portal dla programistów wysyła do Edge żądanie ponownego załadowania konta przedpłaconego.

Saldo konta przedpłaconego możesz doładować za pomocą interfejsu API dla dewelopera lub firmy, jak opisano w kolejnych sekcjach.

Doładowywanie salda konta przedpłaconego dewelopera

Aby doładować saldo konta przedpłaconego 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. W treści żądania musisz podać kwotę do dodania do salda i używaną walutę.

Na przykład ta prośba dodaje 1000 PLN do salda konta dewelopera z przedpłatą:

$ 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 sekcji Podsumowanie właściwości żądania doładowania konta przedpłaconego.

Doładowywanie salda konta z przedpłatą firmy

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

Na przykład to żądanie dodaje 1000 PLN do salda konta przedpłaconego firmy:

$ 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 sekcji Podsumowanie właściwości żądania doładowania konta przedpłaconego.

Podsumowanie właściwości żądania ponownego doładowania konta przedpłaconego

Podczas ponownego ładowania salda konta przedpłaconego za pomocą interfejsu API należy podać te właściwości:

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

Możesz usunąć zewnętrznego dostawcę usług płatniczych skonfigurowanego dla organizacji Edge, wysyłając żądanie DELETE do tego zasobu:

Aby usunąć dostawcę usług płatniczych dla konkretnej organizacji, użyj tego interfejsu API:

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

Tylko klienci Apigee Edge Private Cloud z uprawnieniami administratora systemu mogą opcjonalnie usunąć globalnego dostawcę usług płatniczych za pomocą tego interfejsu API:

/config/providers/id

Na przykład to polecenie usuwa dostawców zewnętrznych platform płatniczych skonfigurowanych obecnie dla organizacji myorg:

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

Ręczne zarządzanie saldem konta przedpłaconego

Możesz też zarządzać doładowywaniem salda przedpłaconego, śledząc płatności ręcznie lub za pomocą zintegrowanego systemu rozliczeniowego, a następnie wywołując interfejs API do zarabiania, aby doładować konto, zgodnie z opisem w artykule Doładowywanie salda konta przedpłaconego za pomocą interfejsu API.

Konfigurowanie automatycznego doładowywania salda konta przedpłaconego za pomocą interfejsu API

W sekcjach poniżej opisujemy, jak skonfigurować automatyczne doładowywanie salda konta przedpłaconego dla dewelopera lub firmy korzystającej z usług dostawcy usług płatniczych. Ta opcja jest przydatna do zarządzania płatnościami cyklicznymi w przypadku abonamentów.

Konfigurowanie automatycznego doładowania salda konta przedpłaconego dla dewelopera

Aby skonfigurować automatyczne doładowanie salda konta przedpłaconego dewelopera, gdy spadnie ono 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ć te informacje:

• Identyfikator dostawcy usług płatniczych, którego chcesz użyć do doładowania konta (providerID)
• Flaga, która włącza automatyczne doładowanie (isRecurring).
• Próg, poniżej którego musi spaść saldo konta przedpłaconego, aby uruchomić automatyczne doładowanie (replenishAmount).
• Kwota, która ma być automatycznie dodawana do konta (recurringAmount).
• parametru zapytania supportedCurrencyID, aby określić walutę.

W poniższym przykładzie, gdy saldo konta przedpłaconego dewelopera spadnie poniżej 5 USD, do konta zostanie automatycznie dodane 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 dotyczących konfigurowania automatycznego doładowywania kont przedpłaconych.

Konfigurowanie automatycznego doładowania salda konta przedpłaconego firmy

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

Podczas wysyłania żądania musisz podać te informacje:

• Identyfikator dostawcy usług płatniczych, którego chcesz użyć do doładowania konta (providerID)
• Flaga, która włącza automatyczne doładowanie (isRecurring).
• Próg, poniżej którego musi spaść saldo konta przedpłaconego, aby uruchomić automatyczne doładowanie (replenishAmount).
• Kwota, która ma być automatycznie dodawana do konta (recurringAmount).
• parametru zapytania supportedCurrencyID, aby określić walutę.

W poniższym przykładzie, gdy saldo konta przedpłaconego firmy spadnie poniżej 5 USD, do konta zostanie automatycznie dodane 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 dotyczących konfigurowania automatycznego doładowywania kont przedpłaconych.

Podsumowanie właściwości żądania dotyczących konfigurowania automatycznego doładowania kont przedpłaconych

Podczas automatycznego doładowywania salda konta przedpłaconego za pomocą interfejsu API można określić te atrybuty:

Migracja do hostowanych stron płatności WorldPay

Firma WorldPay zaktualizowała swój bezpieczny proces płatności, aby korzystać z nowego zestawu stron, zwanych hostowanymi stronami płatności.

Jeśli dostawców usług płatniczych WorldPay skonfigurowano za pomocą wycofanego bezpiecznego procesu przetwarzania płatności (przed sierpniem 2017 r.), przed styczniem 2018 r. musisz przejść na nowe strony płatności hostowane przez WorldPay.

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

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

Dalsze kroki

Możesz ustawić limity kredytowe dla poszczególnych deweloperów korzystających z płatności po wykonaniu usługi. Dowiedz się więcej w artykule Zarządzanie saldami płatności z dołu.