Kelola saldo akun prabayar

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Untuk mengelola saldo di akun prabayar, Anda dapat:

• Lihat saldo akun prabayar saat ini. Lihat Melihat saldo rekening prabayar menggunakan API.
• Muat ulang (menambahkan uang ke) saldo rekening sesuai kebutuhan menggunakan penyedia jasa pembayaran pihak ketiga, seperti Worldpay. Lihat Mengelola saldo prabayar menggunakan penyedia pembayaran pihak ketiga.

  Selain itu, Anda dapat mengelola isi ulang dengan melacak pembayaran secara manual atau melalui sistem penagihan terintegrasi, lalu memanggil monetization API untuk memuat ulang akun, seperti yang dijelaskan dalam Mengelola saldo prabayar secara manual.

• Siapkan isi ulang otomatis saat saldo akun prabayar berkurang di bawah nilai minimum tertentu menggunakan monetization API dan penyedia pembayaran pihak ketiga, seperti Worldpay. Opsi ini berguna untuk mengelola pembayaran berulang untuk paket tarif. Untuk mengetahui informasinya, lihat Menyiapkan pengisian ulang otomatis saldo akun prabayar menggunakan API.

Bagaimana cara menghitung sisa saldo akun prabayar?

Saat melihat saldo akun prabayar untuk developer atau perusahaan, seperti yang dijelaskan di bagian berikut, Anda perlu mendapatkan nilai berikut dari respons:

• amount: Jumlah total uang yang tersedia untuk periode penagihan saat ini. Nilai ini diperbarui saat Anda memuat ulang akun prabayar menggunakan metode yang dijelaskan di bagian ini.
• usage: Jumlah total uang yang digunakan selama periode penagihan berjalan. Nilai ini diperbarui dengan setiap transaksi yang memenuhi syarat dan dimonetisasi atau dengan mengeluarkan kredit (positif atau negatif).

Anda dapat menghitung sisa saldo akun prabayar untuk periode penagihan saat ini dengan mengurangi nilai usage dari nilai amount. Misalnya, jika nilai amount adalah 335,50 dan nilai usage adalah 34, saldo yang tersisa akan dihitung sebagai berikut:

amount(335.50) - usage(34) = 229.50

Melihat saldo akun prabayar menggunakan API

Bagian berikut menjelaskan cara melihat saldo akun prabayar untuk developer atau perusahaan yang menggunakan API.

Melihat saldo akun prabayar untuk developer

Untuk melihat saldo akun prabayar bagi developer, ajukan permintaan GET ke salah satu API berikut, dengan {developer_id} sebagai alamat email developer:

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: Menampilkan saldo akun prabayar dan informasi penyiapan berulang untuk developer.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: Menampilkan informasi saldo akun prabayar termasuk saldo saat ini dan total, penggunaan, tambah saldo, dan pajak penggunaan.

Anda dapat meneruskan parameter kueri berikut untuk memfilter hasil:

Contoh:

$ 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

Berikut adalah contoh responsnya:

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

Melihat saldo akun prabayar untuk perusahaan

Untuk melihat saldo akun prabayar sebuah perusahaan, ajukan permintaan GET ke /mint/organizations/{org_name}/companies/{company_id}/developer-balances, dengan {company_id} sebagai ID perusahaan. Jika perusahaan menggunakan metode prabayar, permintaan akan mengambil saldo akun prabayar saat ini. Jika perusahaan tersebut melakukan pascabayar, permintaan akan mengambil batas kredit saat ini.

Anda dapat meneruskan parameter kueri berikut untuk memfilter hasil:

Contoh:

$ 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

Responsnya mirip dengan respons yang ditampilkan di atas, saat melihat saldo akun prabayar untuk developer.

Mengelola saldo akun prabayar menggunakan penyedia pembayaran

Kelola saldo akun prabayar dengan menyiapkan akun penjual dengan penyedia jasa pembayaran pihak ketiga, seperti Worldpay. Gambar berikut menunjukkan cara saldo akun prabayar dikelola menggunakan penyedia pembayaran Worldpay.

Tabel berikut menjelaskan setiap langkah dalam alur pengelolaan saldo akun prabayar, yang ditunjukkan di atas.

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

Bagian berikut menjelaskan langkah-langkah yang diperlukan untuk mengelola saldo prabayar menggunakan penyedia pembayaran pihak ketiga:

• Menyiapkan akun penjual dengan penyedia pembayaran Worldpay
• Mengonfigurasi penyedia pembayaran di Edge
• Melihat penyedia pembayaran yang dikonfigurasi untuk organisasi Anda
• Mengaktifkan dan mengonfigurasi modul yang diperlukan di portal developer
• Memulai pembayaran ke akun prabayar menggunakan penyedia pembayaran
• Memuat ulang saldo akun prabayar menggunakan API
• Menghapus penyedia jasa pembayaran pihak ketiga

Menyiapkan akun penjual dengan penyedia pembayaran Worldpay

Sebelum memulai, Anda harus menghubungi penyedia jasa pembayaran pihak ketiga (Worldpay) untuk menyiapkan akun penjual. Sebaiknya siapkan dua akun, satu untuk pengujian dan satu untuk produksi. Untuk informasi selengkapnya tentang akun penjual Worldpay, lihat www.worldpay.com dan wp-support.crm.worldpay.com (pusat dukungan Worldpay).

Setelah menyiapkan akun penjual dan menerima kredensial akun, untuk mengonfigurasi akun penjual Anda dengan Worldpay:

1. Buka https://secure.worldpay.com/sso/public/auth/login.html.
2. Login ke akun Worldpay Anda menggunakan kredensial yang diberikan oleh Worldpay.
3. Tetapkan kunci rahasia sandi XML dan kode autentikasi pesan (MAC):
   1. Klik Profil.
   2. Tetapkan sandi yang akan digunakan saat mengonfigurasi penyedia pembayaran Worldpay di Edge di kolom Sandi XML.
   3. Masukkan kunci rahasia MAC yang terdiri atas 20 hingga 30 karakter di kolom Redirect MAC secret.
   4. Klik Simpan Profil
4. Tambahkan server pengelolaan Apigee Edge ke daftar IP penjual (daftar yang diizinkan):
   1. Klik Profil > Lingkungan Penjual.
   2. Klik New Test IP.
   3. Masukkan IP untuk server pengelolaan Apigee Edge.
   4. Klik Simpan.
5. Konfigurasikan URL penjual untuk menambahkan parameter Worldpay, termasuk kode autentikasi metode (MAC):
   1. Klik Penginstalan > Halaman Pembayaran yang Dihosting > Desainer Halaman Pembayaran.
   2. Di bagian Edit Halaman Pembayaran, pilih ID penginstalan dari menu drop-down Pilih saluran.
   3. Di tab Properti, pilih Edit konfigurasi penjual.
   4. Tetapkan nilai parameter Kirim URL ke Benar.
   5. Klik tab Publikasikan.
   6. Promosikan perubahan, sebagai berikut:
      • Untuk lingkungan pengujian, klik Promosikan di bagian Desain untuk mempromosikan dari Desain ke Sandbox.
      • Untuk lingkungan produksi, klik Promosikan di bagian Sandbox untuk mempromosikan dari Sandbox ke Produksi.

Mengonfigurasi penyedia pembayaran di Edge

Langkah berikutnya adalah mengonfigurasi penyedia jasa pembayaran di Edge.

Anda dapat mengonfigurasi penyedia pembayaran untuk organisasi tertentu menggunakan API berikut:

/organizations/{org-name}/providers

Hanya pelanggan Apigee Edge Private Cloud dengan hak istimewa admin sistem secara opsional dapat mengonfigurasi penyedia pembayaran global menggunakan API berikut:

/config/providers

Saat memanggil setiap API, Anda harus menentukan informasi berikut dalam isi permintaan:

Misalnya, kode berikut akan menyiapkan akun penjual dengan Worldpay yang bernama 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 

Melihat penyedia jasa pembayaran pihak ketiga

Lihat dan konfirmasi penyedia pembayaran pihak ketiga yang dikonfigurasi untuk organisasi Edge Anda dengan mengajukan permintaan GET ke resource berikut:

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

Misalnya, gambar berikut menampilkan penyedia pembayaran pihak ketiga yang saat ini dikonfigurasi untuk myorg:

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

Berikut contoh respons yang menampilkan dua akun penjual, satu untuk pengujian dan satu lagi untuk produksi.

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

Mengaktifkan dan mengonfigurasi modul Monetisasi dan Worldpay di portal developer

Aktifkan modul Monetisasi dan Worldpay yang diperlukan di portal developer. Untuk mengetahui detailnya, lihat Mengonfigurasi Monetisasi di Portal Developer.

Memulai pembayaran ke akun prabayar menggunakan penyedia jasa pembayaran

Seperti yang ditunjukkan di langkah 2 alur pengelolaan akun prabayar, pembayaran ke akun prabayar menggunakan penyedia pembayaran dimulai oleh portal developer ketika konsumen API:

• Menyetujui paket tarif, tetapi tidak memiliki dana yang cukup di akun prabayar
• Permintaan untuk menambahkan uang ke akun prabayar mereka.

Untuk memulai pembayaran dari penyedia jasa pembayaran pihak ketiga menggunakan API, kirimkan permintaan POST ke resource berikut, dengan {developer_id} sebagai alamat email developer.

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

Saat mengajukan permintaan, Anda harus menentukan nilai berikut sebagai parameter kueri:

• Jumlah yang akan ditambahkan ke saldo akun prabayar (amount={amount})
• ID penyedia pembayaran (provider={providerId})
• Mata uang yang didukung (supportedCurrencyId={currency})

Selain itu, Anda harus memberikan detail akun dasar, seperti alamat penagihan perusahaan.

Misalnya, kode berikut akan memuat ulang saldo akun prabayar menggunakan penyedia jasa pembayaran Worldpay. Transfer awal ke akun prabayar Anda adalah 10 dolar AS (parameter kueri amount ditetapkan ke 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

Berikut adalah contoh responsnya:

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

URL ke halaman Pembayaran Aman Worldpay ditampilkan di referenceUrl dengan penambahan kunci pesanan unik sebagai parameter kueri.

Memuat ulang saldo akun prabayar menggunakan API

Seperti yang ditunjukkan pada langkah 15 alur pengelolaan akun prabayar, setelah memverifikasi bahwa pemrosesan oleh penyedia pembayaran berhasil, portal developer mengirimkan permintaan ke Edge untuk memuat ulang akun prabayar.

Anda dapat mengisi ulang saldo akun prabayar menggunakan API untuk developer atau perusahaan, seperti yang dijelaskan di bagian berikut.

Memuat ulang saldo akun prabayar untuk developer

Untuk mengisi ulang saldo akun prabayar untuk developer yang menggunakan API, kirimkan permintaan POST ke /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, dengan {developer_id} sebagai alamat email developer. Saat mengajukan permintaan, Anda harus menyebutkan dalam isi permintaan jumlah yang akan ditambahkan ke saldo dan mata uang yang digunakan.

Misalnya, permintaan berikut menambahkan $1.000 ke saldo akun prabayar developer:

$ 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

Untuk deskripsi properti permintaan, lihat Ringkasan properti permintaan untuk memuat ulang akun prabayar.

Memuat ulang saldo akun prabayar untuk perusahaan

Untuk memuat ulang saldo akun prabayar untuk perusahaan yang menggunakan API, kirimkan permintaan POST ke /mint/organizations/{org_name}/companies/{company_id}/developer-balances, dengan {company_id} sebagai ID perusahaan. Saat mengajukan permintaan, Anda harus menyebutkan dalam isi permintaan jumlah yang akan ditambahkan ke saldo dan mata uang yang digunakan.

Misalnya, permintaan berikut menambahkan $1.000 ke saldo akun prabayar perusahaan:

$ 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

Untuk deskripsi properti permintaan, lihat Ringkasan properti permintaan untuk memuat ulang akun prabayar.

Ringkasan properti permintaan untuk memuat ulang akun prabayar

Properti berikut harus ditentukan saat memuat ulang saldo akun prabayar menggunakan API:

Menghapus penyedia jasa pembayaran pihak ketiga

Anda dapat menghapus penyedia pembayaran pihak ketiga yang dikonfigurasi untuk organisasi Edge Anda dengan mengajukan permintaan DELETE ke resource berikut:

Untuk menghapus penyedia pembayaran bagi organisasi tertentu, gunakan API berikut:

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

Hanya pelanggan Apigee Edge Private Cloud yang memiliki hak istimewa admin sistem secara opsional dapat menghapus penyedia pembayaran global menggunakan API berikut:

/config/providers/id

Misalnya, perintah berikut akan menghapus penyedia pembayaran pihak ketiga yang saat ini dikonfigurasi untuk myorg:

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

Mengelola saldo akun prabayar secara manual

Atau, Anda dapat mengelola pengisian ulang saldo prabayar dengan melacak pembayaran secara manual atau melalui sistem penagihan terintegrasi, lalu memanggil monetization API untuk memuat ulang akun, seperti yang dijelaskan dalam Memuat ulang saldo akun prabayar menggunakan API.

Menyiapkan isi ulang otomatis saldo akun prabayar menggunakan API

Bagian berikut menjelaskan cara menyiapkan isi ulang otomatis saldo akun prabayar untuk developer atau perusahaan yang menggunakan penyedia pembayaran pihak ketiga. Opsi ini berguna untuk mengelola pembayaran berulang untuk paket tarif.

Menyiapkan isi ulang otomatis saldo akun prabayar untuk developer

Untuk menyiapkan isi ulang otomatis saldo akun prabayar bagi developer saat saldo turun di bawah nilai minimum tertentu, ajukan permintaan POST ke /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup, dengan {developer_id} adalah alamat email developer.

Saat mengajukan permintaan, Anda harus menentukan hal-hal berikut:

• ID penyedia jasa pembayaran yang akan digunakan untuk memuat ulang akun (providerID)
• Tanda yang mengaktifkan pemuatan ulang otomatis (isRecurring)
• Nilai minimum saldo akun prabayar harus berkurang di bawah agar dapat memicu isi ulang otomatis (replenishAmount)
• Jumlah yang akan ditambahkan secara otomatis ke akun (recurringAmount)
• Parameter kueri supportedCurrencyID untuk menentukan mata uang.

Pada contoh berikut, saat saldo akun prabayar developer turun di bawah 5 dolar AS, tambahan 10 dolar AS akan otomatis ditambahkan ke akun.

$ 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

Untuk deskripsi properti permintaan, lihat Ringkasan properti permintaan untuk menyiapkan isi ulang otomatis akun prabayar.

Menyiapkan isi ulang otomatis saldo akun prabayar untuk perusahaan

Untuk menyiapkan isi ulang otomatis saldo akun prabayar untuk sebuah perusahaan saat saldo berkurang di bawah jumlah tertentu, ajukan permintaan POST ke /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup, dengan {company_id} adalah ID perusahaan.

Saat mengajukan permintaan, Anda harus menentukan hal-hal berikut:

• ID penyedia jasa pembayaran yang akan digunakan untuk memuat ulang akun (providerID)
• Tanda yang mengaktifkan pemuatan ulang otomatis (isRecurring)
• Nilai minimum saldo akun prabayar harus berkurang di bawah agar dapat memicu isi ulang otomatis (replenishAmount)
• Jumlah yang akan ditambahkan secara otomatis ke akun (recurringAmount)
• Parameter kueri supportedCurrencyID untuk menentukan mata uang.

Dalam contoh berikut, saat saldo akun prabayar perusahaan turun di bawah 5 dolar AS, tambahan 10 dolar AS akan otomatis ditambahkan ke akun.

$ 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

Untuk deskripsi properti permintaan, lihat Ringkasan properti permintaan untuk menyiapkan isi ulang otomatis akun prabayar.

Ringkasan properti permintaan untuk menyiapkan isi ulang otomatis akun prabayar

Atribut berikut dapat ditentukan saat memuat ulang saldo akun prabayar secara otomatis menggunakan API.

Bermigrasi ke Halaman Pembayaran yang Dihosting WorldPay

WorldPay telah memperbarui alur pemrosesan pembayaran yang aman untuk menggunakan serangkaian halaman baru, yang disebut sebagai Halaman Pembayaran yang Dihosting.

Jika Anda mengonfigurasi penyedia pembayaran WorldPay menggunakan alur pemrosesan pembayaran aman yang sudah tidak digunakan lagi (sebelum Agustus 2017), Anda harus bermigrasi ke Halaman Pembayaran yang Dihosting WorldPay yang baru sebelum Januari 2018.

Untuk bermigrasi ke Halaman Pembayaran yang Dihosting WorldPay:

1. Hubungi WorldPay untuk memigrasikan akun Anda saat ini agar dapat menggunakan Halaman Pembayaran yang Dihosting baru dan mendapatkan ID penginstalan baru untuk akun Anda.
2. Konfigurasi penyedia pembayaran WorldPay baru, seperti yang dijelaskan dalam Mengonfigurasi penyedia pembayaran di Edge, dengan meneruskan ID penginstalan di kolom authType.
3. Konfigurasikan penyedia pembayaran baru di portal developer Anda, seperti yang dijelaskan dalam Mengonfigurasi Monetisasi di Portal Developer.
4. Jika menyiapkan isi ulang otomatis akun prabayar menggunakan penyedia pembayaran, Anda harus mengonfigurasi ulang pemuatan ulang otomatis untuk menggunakan ID penyedia baru, seperti yang dijelaskan dalam Menyiapkan isi ulang otomatis saldo akun prabayar menggunakan API.

Langkah berikutnya

Anda dapat menetapkan batas kredit untuk setiap developer pascabayar. Pelajari caranya di Mengelola saldo pascabayar.