moneywave
1.0.0
Pustaka PHP untuk menggunakan layanan API moneywave .
Anda dapat memeriksa dokumentasi untuk melihat semua yang tersedia: https://moneywave-doc.herokuapp.com/
Untuk memulai, Anda hanya perlu menginstalnya melalui composer :
$ composer require emmanix2002/ moneywave
Ini akan menambahkannya ke composer.json Anda dan menginstalnya sebagai ketergantungan proyek.
Semua Fitur dan Sumber Daya yang tersedia pada layanan moneywave diekspos sebagai Layanan . Oleh karena itu, untuk menggunakan layanan apa pun, layanan tersebut harus dibuat terlebih dahulu.
Semua Fitur dan Sumber Daya di API moneywave diekspos sebagai layanan di perpustakaan ini.
Titik masuk ke perpustakaan ini adalah kelas moneywave .
$ moneywave = new moneywave ();
Kita akan membahas lebih lanjut tentang ini nanti.
Untuk menggunakan perpustakaan, Anda perlu mendapatkan kredensial dari akun moneywave Anda. Mereka memberi Anda dua kunci:
Akun Anda dapat berada dalam salah satu dari dua status: Test atau Production . Untuk masing-masing negara bagian ini, Anda akan menggunakan kunci yang berbeda.
Kunci ini diperlukan oleh kelas moneywave (dan harus dilindungi -- kunci ini digunakan untuk mengautentikasi akun pedagang); untuk menggunakannya dengan perpustakaan ini, Anda dapat menggunakan salah satu dari dua metode yang mungkin.
Menggunakan metode ini menyimpan kunci dalam file tertentu di server Anda, artinya nilainya tidak di-hardcode ke dalam kode Anda. Perpustakaan mengharapkan untuk menemukan file bernama .env pada tingkat yang sama dengan direktori vendor komposer Anda.
.env
vendor/
composer.json
composer.lock
Seperti yang Anda lihat di atas, file pengaturan harus berada pada level yang dijelaskan. Konten file harus sama seperti yang Anda temukan di .env.example seperti:
# your account moneywave API key
moneywave _API_KEY="your API key goes here"
# your account moneywave Secret key
moneywave _SECRET_KEY="your secret key goes here"
# the environment - staging | production
moneywave _ENV="staging"
Nilai-nilai tersebut harus ditetapkan untuk menggunakan perpustakaan; setelah ini selesai, Anda cukup menelepon:
$ moneywave = new moneywave ();
Cara kedua untuk mengkonfigurasi klien moneywave adalah dengan meneruskan semua pengaturan ke konstruktor.
Berbeda dengan metode pertama , Anda harus menyimpan kunci di suatu tempat dan memberikannya kepada klien saat Anda membuat instance.
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
Saat klien dipakai ( lihat konfigurasi), klien secara otomatis memulai layanan VerifyMerchant . Layanan ini mendapatkan access token dari layanan moneywave yang akan digunakan untuk mengotorisasi setiap permintaan lain yang Anda buat terhadap API.
Setiap access token memiliki umur 2 hours . Dalam aplikasi Anda, Anda memiliki salah satu dari 2 opsi:
Session Anda untuk digunakan di beberapa permintaan Untuk opsi pertama, lihat file contoh di direktori examples . Anda akan melihat sesuatu seperti ini:
use Emmanix2002 moneywave ExceptionValidationException;
use Emmanix2002 moneywave moneywave ;
require(dirname(__DIR__).'/vendor/autoload.php');
session_start();
try {
$accessToken = !empty($_SESSION['accessToken']) ? $_SESSION['accessToken'] : null;
$mw = new moneywave ($accessToken);
$_SESSION['accessToken'] = $mw->getAccessToken();
$query = $mw->createWalletBalanceService();
$response = $query->send();
var_dump($response->getData());
var_dump($response->getMessage());
} catch (ValidationException $e) {
var_dump($e->getMessage());
}
Hal ini memungkinkan penggunaan access token yang sama untuk permintaan lain dari mesin yang sama.
Setelah membuat instance objek moneywave , ikuti langkah-langkah berikut untuk menggunakan layanan:
create*Service()send() pada objek layanan yang dibuat. Setiap fitur dan sumber daya dipetakan ke suatu layanan; pemetaan dapat dengan mudah disimpulkan dari nama kelas .
Tabel di bawah menjelaskan semua layanan:
| Nama Kelas | Panggilan Layanan |
|---|---|
| Validasi Nomor Akun | createAccountNumberValidationService |
| AkunKeAkun | buatAkunToAccountService |
| AkunKe Dompet | buatAccountToWalletService |
| Transfer Akun | buatAccountTransferService |
| Bank | buatLayanan Bank |
| Rekening KartuKeBank | buatCardToBankAccountService |
| Tokenisasi Kartu | buatCardTokenizationService |
| KartuKe Dompet | buatCardToWalletService |
| Transfer Kartu | buatCardTransferService |
| Mengeluarkan | buatDisburseService |
| Pencairan Massal | buatDisburseBulkService |
| InternetBankingToWallet | buatInternetBankingToWalletService |
| QueryCardToAccountTransfer | buatQueryCardToAccountTransfer |
| Pencairan Kueri | createQueryDisbursementService |
| Coba lagiTransfer yang Gagal | createRetryFailedTransferService |
| TotalChargeToCard | buatTotalChargeToCardService |
| ValidasiCardTransfer | createValidateCardTransferService |
| ValidasiTransfer | buatValidateTransferService |
| VerifikasiPedagang | buatVerifyMerchantService |
| Saldo Dompet | buatWalletBalanceService |
Setiap layanan memiliki daftar properti yang harus disetel sebelum dapat dikirim ke API; jika satu atau lebih properti ini tidak disetel, pemanggilan send() akan memunculkan ValidationException .
Mari kita gunakan sumber daya Account Number validation API sebagai contoh:
Dari dokumentasi, properti berikut diperlukan:
| Nama Bidang | Keterangan |
|---|---|
| nomor_akun | nomor rekening pengirim |
| kode_bank | kode bank dari rekening yang akan diselesaikan |
Untuk menggunakan perpustakaan, kami akan melakukan sesuatu seperti ini:
$ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();
Jika salah satu bidang tersebut tidak disetel pada objek layanan , pengecualian ValidationException akan dilempar.
Setiap bidang yang ditentukan dalam dokumentasi moneywave (untuk layanan) dapat ditetapkan sebagai properti pada objek layanan yang dibuat.
Ada bidang tertentu yang khusus, dan tidak perlu Anda atur (walaupun Anda dapat memilih untuk mengaturnya); mereka akan secara otomatis diberikan nilai yang dibutuhkan oleh perpustakaan. Temukan daftarnya di bawah ini:
| Bidang | Keterangan |
|---|---|
| apiKey | ini akan disetel ke kunci API yang digunakan untuk membuat instance objek moneywave |
| rahasia | ini akan disetel ke kunci rahasia yang digunakan untuk objek moneywave |
| biaya | diatur secara default ke 0 |
| penerima | untuk createCardToWalletService , ini disetel ke wallet secara default |
| mata uang | secara otomatis diatur ke Currency::NAIRA |
Sama seperti ada bidang khusus, ada juga beberapa objek layanan khusus, yang menyajikan lebih dari metode biasa: send() .
createCardToBankAccountService() , createCardToWalletService() )Layanan transfer ini istimewa karena sering kali berkaki dua . Ini melibatkan langkah-langkah berikut:
1 Bagian transfer 2 Bagian validasi
Langkah-langkah ini berjalan satu demi satu; dan kedua langkah harus diselesaikan untuk menyelesaikan transfer.
Ada 2 layanan yang menangani bagian validation ; mereka adalah:
createValidateCardTransferService() : memungkinkan Anda memvalidasi kartu ke dompet atau transfer kartu ke akun yang dilakukan dengan kartu debit VervecreateValidateTransferService() : memungkinkan Anda memvalidasi kartu ke dompet atau transfer kartu ke akun yang dilakukan dengan akun. Artinya, bidang charge_with disetel ke ChargeMethod::ACCOUNT .Jadi, ketika Anda menerima respons sukses dari API setelah leg pertama ; Anda memulai bagian validasi.
CATATAN : Untuk transfer kartu Mastercard dan Visa, Anda akan menerima kunci authurl dalam respons API yang berhasil; Anda harus mengalihkan ke URL ini agar pembayar dapat memvalidasi transfer. Setelah berhasil atau gagal, pembayar akan diarahkan kembali ke URL yang ditetapkan di bidang redirecturl permintaan transfer.
Layanan ini untuk mencairkan uang tunai dari dompet moneywave Anda ke beberapa rekening bank. Ini memiliki metode khusus untuk menambahkan akun beneficiary individu.
addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);
Metode ini memungkinkan Anda menambahkan setiap akun penerima secara bergantian:
$bulkDisbursement = $ moneywave ->createDisburseBulkService();
$bulkDisbursement->lock = 'wallet password';
$bulkDisbursement->ref = 'unique reference'; # suggestion: you could use a UUID; check out ramsey/uuid package
$bulkDisbursement->senderName = ' moneywave SDK';
$bulkDisbursement->addRecipient(Banks::ACCESS_BANK, '0690000004', 1)
->addRecipient(Banks::ACCESS_BANK, '0690000005', 2);
Lihat file examples/disburse_bulk.php untuk contoh lengkapnya.
Jika semua kolom yang diperlukan pada objek layanan (lihat layanan) telah disetel, panggilan ke send() akan mengembalikan objek respons yang merupakan turunan dari kelas moneywave Response .
Melanjutkan contoh Validasi Akun di atas:
$response = $accountValidation->send();
Respons JSON yang berhasil akan berbentuk seperti ini:
{
status: "success",
data: {
name: "MICHAEL JACKSON"
}
}
Sedangkan respon kegagalan JSON akan berbentuk:
{
status: "error",
message: "error message description",
code: "error code string; e.g. INVALID_ID",
data: "data string -- this is absent most of the time"
}
Variabel $response menyajikan beberapa fungsi yang dapat digunakan untuk bekerja dengan data ini:
# was a request successful?
if ($response->isSuccessful()) {
# do something with the returned data
$name = $response->getData()['name'];
} else {
# this was a failure
$message = $response->getMessage();
$code = $response->getCode();
$data = $response->getData();
}
CATATAN : Semua kunci dalam respons JSON juga dapat diakses dari objek respons sebagai properti:
if ($response->isSuccessful()) {
$name = $response->getData()['name'];
} else {
$message = $response->message;
$code = $response->code;
}
Contoh lainnya, respons dari layanan VerifyMerchant terlihat seperti ini:
{
status: "success",
token: "" // a valid merchant token
}
Dengan menggunakan responsnya, Anda harus melakukan ini:
$response = $verifyService->send();
if ($response->isSuccessful()) {
$token = $response->token;
} else {
# process the error response as you normally would
}
Tabel di bawah menjelaskan metode yang ditentukan pada objek moneywave Response :
| Metode | Jenis Pengembalian | Keterangan |
|---|---|---|
| dapatkanRespon Mentah() | rangkaian | respons JSON dari API |
| berhasil() | bodoh | memeriksa apakah kunci status === "success" |
| dapatkan Kode() | rangkaian | mengembalikan kunci code |
| dapatkan Pesan() | rangkaian | mengembalikan atribut message |
| dapatkanData() | susunan | mengembalikan kunci data |
CATATAN : Untuk respons yang data berupa string; ia mengembalikan array ini [data: string]
