@giropay/node-sdk v0.1.7
Giro Node.js SDK
Giro SDK is a comprehensive Node.js SDK designed to simplify the integration with Giro’s powerful API. It provides developers with an easy-to-use interface for accessing core Giro services, such as initiating transactions, retrieving account balances, and more.
Installation
To install the Giro SDK, run:
npm install @giropay/node-sdk
# or
yarn add @giropay/node-sdkInitialization
The SDK must be initialized using your API secret key. This key is used for authorization.
import { initializeGiroPaySDK } from '@giropay/node-sdk';
// Replace 'your-secret-key' with an actual API secret key
const sdk = initializeGiroPaySDK('your-secret-key');Methods
1. findAccounts
Fetches all accounts associated with the API key.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | No | Filter accounts by name |
| isDefault | boolean | No | Filter accounts marked as default |
| live | boolean | No | Filter accounts that are live |
The parameters when provided, should be passed inside a configuration object. If no configuration is required, the object can be omitted entirely.
Returns: Promise<FindAccountsResponse>
2. updateAccount
Updates the details of a specific account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountId | string | Yes | The publicId of the account to update |
| payload | object | Yes | The account details to update |
| payload.live | boolean | No | Set to update account mode |
| payload.webhooks | array | No | Value should contain the webhook url(s). This should be an array of string(s) |
Returns: Promise<UpdateAccountResponse>
3. createWallet
Creates a new wallet.
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountName | string | Yes | The name of the new wallet |
| category | string | Yes | The wallet category (e.g., primary or secondary) |
| currency | string | Yes | The currency for the new wallet. Value should be NGN |
| emailAddress | string | No | This should be provided only when wallet category is secondary |
| mobile | object | No | This should be provided only when wallet category is secondary. |
| mobile.phoneNumber | string | Yes | The mobile number of the customer |
| mobile.isoCode | string | Yes | Value should be NG |
The parameters should be passed inside a configuration object.
Returns: Promise<CreateWalletResponse>
4. findWallets
Fetches wallets based on filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | No | The wallet category (e.g., primary) |
| live | boolean | No | Filter wallets that are live |
| isFavourite | boolean | No | Filter favourite wallets. By default, these are your primary wallets |
The parameters when provided, should be passed inside a configuration object. If no configuration is required, the object can be omitted entirely.
Returns: Promise<FindWalletsResponse>
5. getOneWallet
Fetches details of a specific wallet by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| walletId | string | Yes | The publicId of the wallet to retrieve |
Returns: Promise<GetWalletResponse>
6. getAllBalances
Fetches balances of all wallets associated with the API key.
Parameters: None
Returns: Promise<GetAllBalancesResponse>
7. getBalance
Fetches the balance of a specific wallet by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| walletId | string | Yes | The publicId of the wallet to retrieve |
Returns: Promise<GetBalanceResponse>
8. createDisposableCollectionWallet
Creates a disposable collection wallet.
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountName | string | Yes | The name of the collection wallet |
| destination | string | Yes | The value should be the publicId of the wallet where you want incoming transactions to be settled |
| amount | number | Yes | The amount for the collection. Value should be in kobo |
| expireIn | number | Yes | Range is 10 mins - 30mins. Value should be in seconds. |
| reference | string | No | When provided, this should be unique and minimum length should be 5. |
The parameters should be passed inside a configuration object.
Returns: Promise<DisposableCollectionWalletResponse>
9. createTransitCollectionWallet
Creates a new transit collection wallet.
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountName | string | Yes | The name of the collection wallet |
| settlementAccount | string | Yes | The value should be the publicId of the wallet where you want incoming transactions to be settled |
| currency | string | Yes | The currency for the new wallet. Value should be NGN |
| emailAddress | string | No | The value should be a valid email address |
| mobile | object | No | The value should be a valid mobile number |
| mobile.phoneNumber | string | Yes | |
| mobile.isoCode | string | Yes | Value should be NG |
The parameters should be passed inside a configuration object.
Returns: Promise<TransitCollectionWalletResponse>
10. closeWallet
Closes a wallet by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| walletId | string | Yes | The publicId of the wallet to close |
Returns: Promise<CloseWalletResponse>
11. findTransactions
Fetches transactions based on filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
| entry | string | No | Filter transactions by entry type (e.g., credit) |
| live | boolean | No | Filter transactions that are live |
| status | string | No | Filter transactions by status (e.g., success) |
| amount | number | No | Filter transactions by amount. Value should be in kobo |
| createdAt | object | No | Filter transactions by date-range. Value should be an object containing a date string in this format: {"startDate": "2024-01-01", "endDate": "2024-03-30"} |
The parameters when provided, should be passed inside a configuration object. If no configuration is required, the object can be omitted entirely.
Returns: Promise<FindTransactionsResponse>
12. getOneTransaction
Fetches details of a specific transaction by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| transactionId | string | Yes | The publicId of the transaction to retrieve |
Returns: Promise<GetOneTransactionResponse>
13. findBanks
Fetches a list of supported banks.
Parameters: None
Returns: Promise<FindBanksResponse>
14. initiateWalletTransfer
Initiates a transfer between own wallets.
| Parameter | Type | Required | Description |
|---|---|---|---|
| source | string | Yes | The source wallet publicId |
| sourceType | string | Yes | The type of source (e.g., VirtualAccount) |
| destination | string | Yes | The destination wallet publicId |
| destinationType | string | Yes | The type of destination (e.g., VirtualAccount) |
| currency | string | Yes | The currency for the transfer. Value should be NGN |
| amount | number | Yes | The amount to transfer. Value should be in kobo. Minimum transfer is 100 naira |
| narration | string | Yes | The narration for the transfer |
| reference | string | No | Optional reference for the transfer |
| nameEnquiryRef | string | No | Optional name enquiry reference |
The parameters should be passed inside a configuration object.
Returns: Promise<InitiateWalletTransferResponse>
15. initiateBankTransfer
Initiates a transfer to a bank account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| source | string | Yes | The source wallet publicId |
| accountNumber | string | Yes | The destination bank account number |
| bankCode | string | Yes | The bank code of the destination bank |
| currency | string | Yes | The currency for the transfer. Value should be NGN |
| amount | number | Yes | The amount to transfer. Value should be in kobo. Minimum transfer is 100 naira |
| narration | string | Yes | The narration for the transfer |
| reference | string | No | Optional reference for the transfer |
| saveBeneficiary | boolean | No | Whether to save the beneficiary details |
| metadata | object | No | Additional data to attach to the transaction |
The parameters should be passed inside a configuration object.
Returns: Promise<InitiateBankTransferResponse>
16. verifyTransaction
Verifies a transaction by its reference.
| Parameter | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | The reference of the transaction to verify |
Returns: Promise<VerifyTransactionResponse>
17. findBankAccounts
Fetches bank accounts based on filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
| beneficiaryType | string | No | The type of beneficiary (e.g., personal) |
| accountName | string | No | Filter by account name |
| live | boolean | No | Filter bank accounts that are live |
The parameters when provided, should be passed inside a configuration object. If no configuration is required, the object can be omitted entirely.
Returns: Promise<FindBankAccountsResponse>
18. getOneBankAccount
Fetches details of a specific bank account by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| bankAccountId | string | Yes | The publicId of the bank account to retrieve |
Returns: Promise<GetOneBankAccountResponse>
19. validateBankAccount
Validates a bank account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| bankCode | string | Yes | The bank code of the bank |
| accountNumber | string | Yes | The account number to validate |
The parameters should be passed inside a configuration object.
Returns: Promise<ValidateBankAccountResponse>
20. addBankAccount
Adds a new bank account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountName | string | Yes | The name of the bank account holder |
| accountNumber | string | Yes | The bank account number |
| bankCode | string | Yes | The bank code of the bank |
| bankName | string | Yes | The name of the bank |
| beneficiaryType | string | No | The beneficiary type. Value should be 'personal', 'vba', or'external'. Default is personal |
The parameters should be passed inside a configuration object.
Returns: Promise<AddBankAccountResponse>
Example
Here is an example of how to use the initiateWalletTransfer method:
await sdk.initiateWalletTransfer({
source: 'vba-cafdd935-9e82-4e2c-85fdd-d1ff1f43c5b53',
sourceType: 'VirtualAccount',
destination: 'vba-5d44d6d1-e2ed-4f83-9704-d956td50eb792',
destinationType: 'VirtualAccount',
currency: 'NGN',
amount: 55000,
narration: 'giro sdk wallet transfer',
});In this example, we initiated a transfer of NGN550 from one wallet to another.
For further reference, please refer to the Giro Documentation.