@vantagepay/vantagepay 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +515 -0
- package/dist/apiConfig.d.ts +10 -0
- package/dist/apiError.d.ts +5 -0
- package/dist/apiTokens.d.ts +7 -0
- package/dist/authentication/index.d.ts +22 -0
- package/dist/authentication/types.d.ts +67 -0
- package/dist/baseApi.d.ts +9 -0
- package/dist/common/types.d.ts +99 -0
- package/dist/consumers/index.d.ts +11 -0
- package/dist/consumers/types.d.ts +358 -0
- package/dist/content/index.d.ts +7 -0
- package/dist/devices/types.d.ts +20 -0
- package/dist/eventTypes.d.ts +10 -0
- package/dist/gmoney/index.d.ts +48 -0
- package/dist/gmoney/types.d.ts +136 -0
- package/dist/hubtel/index.d.ts +21 -0
- package/dist/hubtel/types.d.ts +35 -0
- package/dist/index.d.ts +36 -0
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -0
- package/dist/index.m.js +2 -0
- package/dist/index.m.js.map +1 -0
- package/dist/index.modern.mjs +2 -0
- package/dist/index.modern.mjs.map +1 -0
- package/dist/index.umd.js +2 -0
- package/dist/index.umd.js.map +1 -0
- package/dist/log/index.d.ts +19 -0
- package/dist/log/messageTemplate.d.ts +10 -0
- package/dist/log/types.d.ts +20 -0
- package/dist/lookups/index.d.ts +28 -0
- package/dist/lookups/types.d.ts +1840 -0
- package/dist/merchants/index.d.ts +36 -0
- package/dist/merchants/types.d.ts +479 -0
- package/dist/payments/index.d.ts +38 -0
- package/dist/payments/types.d.ts +2015 -0
- package/dist/qr/index.d.ts +6 -0
- package/dist/reports/index.d.ts +8 -0
- package/dist/reports/types.d.ts +67 -0
- package/dist/system/index.d.ts +4 -0
- package/dist/tokens/types.d.ts +38 -0
- package/dist/transflow/index.d.ts +11 -0
- package/dist/transflow/types.d.ts +11 -0
- package/package.json +47 -0
package/README.md
ADDED
|
@@ -0,0 +1,515 @@
|
|
|
1
|
+
# VantagePay API and Client SDK
|
|
2
|
+
|
|
3
|
+
The VantagePay client SDK is intended to be used by web or mobile applications to integrate into the VantagePay payments, consumer and merchant API's.
|
|
4
|
+
|
|
5
|
+
The library includes automatic retries for network failures and automatic token refresh on expiry. You can optionally subscribe to events published by the library to react appropriately from the client as well.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
# Installation
|
|
9
|
+
|
|
10
|
+
Install the latest package into your project from NPM.
|
|
11
|
+
|
|
12
|
+
```ps
|
|
13
|
+
npm install @vantagepay/vantagepay --save
|
|
14
|
+
```
|
|
15
|
+
---
|
|
16
|
+
# Basic Usage
|
|
17
|
+
The library can be imported just like any other NPM package.
|
|
18
|
+
```js
|
|
19
|
+
import { VantagePay, ApiTokens, ApiError } from '@vantagepay/vantagepay'
|
|
20
|
+
```
|
|
21
|
+
Once imported you can create an instance with options specific to your environment.
|
|
22
|
+
```js
|
|
23
|
+
const VantagePayClient = new VantagePay({ baseUrl: 'https://sandbox-api.vantagepay.dev/' })
|
|
24
|
+
```
|
|
25
|
+
When you are done using the client or when the application exits, you can close the client to flush logs, unsubscribe to events and cancel active web requests.
|
|
26
|
+
```js
|
|
27
|
+
await VantagePayClient.close()
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The following options are available when creating an instance.
|
|
31
|
+
```js
|
|
32
|
+
{
|
|
33
|
+
// The partner URL you are integrating with, this will point to the local development server by default.
|
|
34
|
+
baseUrl: 'https://sandbox-api.vantagepay.dev/'
|
|
35
|
+
|
|
36
|
+
// Optional extra headers (string key/value pairs) that you may want to send to th e server with each call.
|
|
37
|
+
headers: {
|
|
38
|
+
'X-EXAMPLE-HEADER': 'Test'
|
|
39
|
+
},
|
|
40
|
+
|
|
41
|
+
// Optional language if you need to have response messages translated.
|
|
42
|
+
language: 'en',
|
|
43
|
+
|
|
44
|
+
// The number of automatic retries required for network failures, the default is 3.
|
|
45
|
+
retries: 3,
|
|
46
|
+
|
|
47
|
+
// For additional request/response and signal logging which can be useful when debugging.
|
|
48
|
+
consoleLogging: false
|
|
49
|
+
|
|
50
|
+
// The batch size limit when logs should immediately be sent to the server, the default is 100, use 0 to disable.
|
|
51
|
+
logBatchSize: 100,
|
|
52
|
+
|
|
53
|
+
// The interval in milliseconds to send any queued logs the server, the default is 60000, use 0 to disable.
|
|
54
|
+
logBatchInterval: 60000,
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
To flush any logs to the server you can call the `log.flush()` method manually or `close()` on the client instance when closing your application.
|
|
59
|
+
```js
|
|
60
|
+
// Do this when the application close to push final logs to the server.
|
|
61
|
+
VantagePayClient.log.flush()
|
|
62
|
+
|
|
63
|
+
// You can also just close the client when you are done using it.
|
|
64
|
+
await VantagePayClient.close()
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The instance will contain all the methods available for making API calls. All methods return a [`Promise`](https://javascript.info/async) so you can either use modern async/await syntax or promise-based chaining. The rest of the examples that follow use the async/await syntax.
|
|
68
|
+
|
|
69
|
+
## Error Handling
|
|
70
|
+
The API will respond with typical REST HTTP error status codes (4xx and 5xx) for errors that will trigger an exception. You can use the following generic error handling code for the typical exceptions that you may experience.
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
try {
|
|
74
|
+
// ... Call a method on the client library.
|
|
75
|
+
} catch (error) {
|
|
76
|
+
// First check if it's an API error.
|
|
77
|
+
if (error instanceof ApiError) {
|
|
78
|
+
// You can always display the `message` property to handle things generically.
|
|
79
|
+
console.error('\n%s\n', error.message)
|
|
80
|
+
|
|
81
|
+
// Or you can decide to handle things in a custom way depending on the status code.
|
|
82
|
+
if (error.statusCode === 400 || error.statusCode === 422) { // 400/422 - Validation Errors
|
|
83
|
+
if (Array.isArray(error.result)) {
|
|
84
|
+
// Multiple errors.
|
|
85
|
+
error.result.forEach(validationError => console.error(validationError))
|
|
86
|
+
}
|
|
87
|
+
else {
|
|
88
|
+
// Single error message.
|
|
89
|
+
console.error(error.message || error.result)
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
else if (error.statusCode === 401 || error.statusCode === 403) { // 401/403 - Auth Errors
|
|
93
|
+
// Login calls will contain extra information on failure (401).
|
|
94
|
+
// No access will not have any specific details on why (403).
|
|
95
|
+
}
|
|
96
|
+
else if (error.statusCode === 429) { // 429 - Too Many Requests
|
|
97
|
+
// Contains the limit.
|
|
98
|
+
console.error(error.message)
|
|
99
|
+
// This will also contain a standard 'Retry-After' header if you need to know how long to wait.
|
|
100
|
+
}
|
|
101
|
+
else if (error.statusCode === 500) { // 500 - Server Error
|
|
102
|
+
// General error message.
|
|
103
|
+
console.error(error.message)
|
|
104
|
+
}
|
|
105
|
+
else {
|
|
106
|
+
console.error('Unknown status code from VantagePay client library: ' + error.statusCode)
|
|
107
|
+
throw error
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
else {
|
|
111
|
+
// Not a client library error...
|
|
112
|
+
throw error
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
# Authentication
|
|
119
|
+
|
|
120
|
+
## Login
|
|
121
|
+
Use credentials to login and retrieve access and refresh tokens.
|
|
122
|
+
```js
|
|
123
|
+
try {
|
|
124
|
+
|
|
125
|
+
const testLogin = await VantagePayClient.auth.login('test', 'test@#$123abCD')
|
|
126
|
+
|
|
127
|
+
// Store tokens in secure storage if you want to use biometrics etc.
|
|
128
|
+
my_secure_storage.set('accessToken', testLogin.accessToken)
|
|
129
|
+
my_secure_storage.set('refreshToken', testLogin.refreshToken)
|
|
130
|
+
|
|
131
|
+
// An alternative is to just use the static ApiTokens object where the tokens are stored after a login/refresh.
|
|
132
|
+
my_secure_storage.set('accessToken', ApiTokens.accessToken)
|
|
133
|
+
my_secure_storage.set('refreshToken', ApiTokens.refreshToken)
|
|
134
|
+
|
|
135
|
+
} catch (error) {
|
|
136
|
+
if (error.statusCode === 401) {
|
|
137
|
+
// Authentication error
|
|
138
|
+
// {
|
|
139
|
+
// invalidUsernameOrPassword: true,
|
|
140
|
+
// mustChangePassword: false,
|
|
141
|
+
// mustValidatePhoneNumber: false,
|
|
142
|
+
// mustValidateEmailAddress: false,
|
|
143
|
+
// registrationRequired: false,
|
|
144
|
+
// lockedOut: false
|
|
145
|
+
// }
|
|
146
|
+
|
|
147
|
+
const authError = error.result
|
|
148
|
+
|
|
149
|
+
if (authError.mustChangePassword) {
|
|
150
|
+
console.log('Navigate to a change password page, the token is internally set to allow calls to auth.changePassword()')
|
|
151
|
+
|
|
152
|
+
// A successfull change will automatically log you in.
|
|
153
|
+
await VantagePayClient.auth.changePassword('NewComplexP@55word!')
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
if (authError.mustValidatePhoneNumber) {
|
|
157
|
+
console.log('Navigate to the OTP page password page, the token is internally set to allow calls to auth.resendOtp() and auth.validateOtp()')
|
|
158
|
+
|
|
159
|
+
// A successfull OTP verification will automatically log you in.
|
|
160
|
+
await VantagePayClient.auth.validateOtp('1234')
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
if (authError.deactivated) {
|
|
164
|
+
console.log('User account has been deactivated')
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
if (authError.lockedOut) {
|
|
168
|
+
console.log('User is currently locked out')
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
if (authError.invalidUsernameOrPassword) {
|
|
172
|
+
console.log('User credentials supplied are invalid')
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
if (error.statusCode === 429) {
|
|
177
|
+
// Rate limited
|
|
178
|
+
// Maximum number of requests exceeded. The maximum number of requests allowed is 3 per 30s. Please try again in 13 second(s).
|
|
179
|
+
console.log(error.message)
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Using Existing Tokens
|
|
185
|
+
Tokens are kept in memory for the lifetime of the client instance and are used automatically to make authenticated calls and refresh when necessary.
|
|
186
|
+
To avoid having to login each time your application starts, you can store access and refresh tokens (securely using biometrics for example) and re-use them when starting the application to "auto-login". You simply assign any tokens you have to the static instance of `ApiTokens`.
|
|
187
|
+
|
|
188
|
+
```js
|
|
189
|
+
ApiTokens.accessToken = my_secure_storage.get('accessToken') || null
|
|
190
|
+
ApiTokens.refreshToken = my_secure_storage.get('refreshToken') || null
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
It is usually not necessary to set the `accessToken`, if there is no access token then an automatic refresh will be triggered to retrieve one.
|
|
194
|
+
You can also use this to clear out tokens manually which is also used internally when `logout` is called.
|
|
195
|
+
|
|
196
|
+
## Logout
|
|
197
|
+
Logout of the system which revokes the refresh token as well. Use this when you need to forcibly log a user out due to multiple device unlock failures for example.
|
|
198
|
+
```js
|
|
199
|
+
await VantagePayClient.auth.logout()
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Refresh
|
|
203
|
+
This is used internally to automatically refresh if the access token is no longer valid. If you need to refresh manually for any reason to start a new access session then you can call this as well to avoid expiry. This will use the current refresh token that has been set (`ApiKeys.refreshToken`).
|
|
204
|
+
```js
|
|
205
|
+
await VantagePayClient.auth.refresh()
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
# Lookups
|
|
210
|
+
There are a number of lookup values that can be retrieved from the server. This is preferred over static client data because it allows for dynamic configuration and disabling of things from the server without redeploying the client.
|
|
211
|
+
|
|
212
|
+
## Currencies
|
|
213
|
+
Get a list of configured currencies for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. Other properties can be useful for displaying currency values.
|
|
214
|
+
```js
|
|
215
|
+
var currencies = await VantagePayClient.lookups.getCurrencies()
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Example Output
|
|
219
|
+
```js
|
|
220
|
+
[
|
|
221
|
+
{
|
|
222
|
+
isAvailable: true,
|
|
223
|
+
currency: 'GHS',
|
|
224
|
+
currencyName: 'Ghana Cedi',
|
|
225
|
+
currencyCode: 'GHS',
|
|
226
|
+
symbol: '¢',
|
|
227
|
+
numericIsoCode: 936
|
|
228
|
+
},
|
|
229
|
+
{
|
|
230
|
+
isAvailable: true,
|
|
231
|
+
currency: 'NGN',
|
|
232
|
+
currencyName: 'Nigeria Naira',
|
|
233
|
+
currencyCode: 'NGN',
|
|
234
|
+
symbol: '₦',
|
|
235
|
+
numericIsoCode: 566
|
|
236
|
+
},
|
|
237
|
+
{
|
|
238
|
+
isAvailable: true,
|
|
239
|
+
currency: 'ZAR',
|
|
240
|
+
currencyName: 'South Africa Rand',
|
|
241
|
+
currencyCode: 'ZAR',
|
|
242
|
+
symbol: 'R',
|
|
243
|
+
numericIsoCode: 710
|
|
244
|
+
}
|
|
245
|
+
]
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
## Countries
|
|
249
|
+
Get a list of configured countries for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. Other values are useful for adding drop-downs to mobile numbers for example.
|
|
250
|
+
```js
|
|
251
|
+
var countries = await VantagePayClient.lookups.getCountries()
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Example Output
|
|
255
|
+
```js
|
|
256
|
+
[
|
|
257
|
+
{
|
|
258
|
+
isAvailable: true,
|
|
259
|
+
country: 'GHA',
|
|
260
|
+
countryName: 'Ghana',
|
|
261
|
+
longIsoCode: 'GHA',
|
|
262
|
+
shortIsoCode: 'GH',
|
|
263
|
+
numericIsoCode: 288,
|
|
264
|
+
diallingCode: '233'
|
|
265
|
+
},
|
|
266
|
+
{
|
|
267
|
+
isAvailable: true,
|
|
268
|
+
country: 'NGA',
|
|
269
|
+
countryName: 'Nigeria',
|
|
270
|
+
longIsoCode: 'NGA',
|
|
271
|
+
shortIsoCode: 'NG',
|
|
272
|
+
numericIsoCode: 566,
|
|
273
|
+
diallingCode: '234'
|
|
274
|
+
},
|
|
275
|
+
{
|
|
276
|
+
isAvailable: false,
|
|
277
|
+
country: 'ZAF',
|
|
278
|
+
countryName: 'South Africa (Currently Unavailable)',
|
|
279
|
+
longIsoCode: 'ZAF',
|
|
280
|
+
shortIsoCode: 'ZA',
|
|
281
|
+
numericIsoCode: 710,
|
|
282
|
+
diallingCode: '27'
|
|
283
|
+
}
|
|
284
|
+
]
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
## Languages
|
|
288
|
+
Get a list of configured languages for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. This can be useful for apps that are translated to change the language header.
|
|
289
|
+
```js
|
|
290
|
+
var languages = await VantagePayClient.lookups.getLanguages()
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
Example Output
|
|
294
|
+
```js
|
|
295
|
+
[ { isAvailable: true, languageCode: 'ENG', languageName: 'English' } ]
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## Mobile Wallet Operators
|
|
299
|
+
Get a list of configured mobile wallet operators for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. This can be used when setting up mobile wallets for example by limiting the types to only what the partner supports. The `operatorCode` is what can be passed into payment request packets for mobile wallet sources or destinations.
|
|
300
|
+
```js
|
|
301
|
+
var mobileWalletOperators = await VantagePayClient.lookups.getMobileWalletOperators()
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
Example Output
|
|
305
|
+
```js
|
|
306
|
+
[
|
|
307
|
+
{
|
|
308
|
+
isAvailable: false,
|
|
309
|
+
operatorCode: 'ATG',
|
|
310
|
+
operatorName: 'AirtelTigo (Currently Unavailable)'
|
|
311
|
+
},
|
|
312
|
+
{ isAvailable: true, operatorCode: 'MTN', operatorName: 'MTN' },
|
|
313
|
+
{ isAvailable: true, operatorCode: 'VDF', operatorName: 'Vodafone' }
|
|
314
|
+
]
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
## Banks
|
|
318
|
+
Get a list of configured banks for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. This can be used when setting up bank accounts for example by limiting the types to only what the partner supports. The `bankCode` is what can be passed into payment request packets for bank account sources or destinations.
|
|
319
|
+
```js
|
|
320
|
+
var banks = await VantagePayClient.lookups.getBanks()
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
You can also optionally filter the banks returned for a specific country.
|
|
324
|
+
```js
|
|
325
|
+
// Only return banks in Ghana.
|
|
326
|
+
var banks = await VantagePayClient.lookups.getBanks('GHA')
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Example Output
|
|
330
|
+
```js
|
|
331
|
+
[
|
|
332
|
+
{
|
|
333
|
+
isAvailable: true,
|
|
334
|
+
bank: 'ABG',
|
|
335
|
+
bankCode: 'ABG',
|
|
336
|
+
bankName: 'ABSA Bank Ghana',
|
|
337
|
+
country: 'GHA'
|
|
338
|
+
},
|
|
339
|
+
{
|
|
340
|
+
isAvailable: true,
|
|
341
|
+
bank: 'ABL',
|
|
342
|
+
bankCode: 'ABL',
|
|
343
|
+
bankName: 'Access Bank Ghana',
|
|
344
|
+
country: 'GHA'
|
|
345
|
+
},
|
|
346
|
+
{
|
|
347
|
+
isAvailable: false,
|
|
348
|
+
bank: 'FNB',
|
|
349
|
+
bankCode: 'FNB',
|
|
350
|
+
bankName: 'First National Bank Ghana (Currently Unavailable)',
|
|
351
|
+
country: 'GHA'
|
|
352
|
+
}
|
|
353
|
+
]
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## Card Issuer Country
|
|
357
|
+
It is sometimes necessary to determine which country a card was issued in, you can use the card issuer country lookup with a card number to lookup the country.
|
|
358
|
+
```js
|
|
359
|
+
var country = await VantagePayClient.lookups.getCardIssuerCountry('5200000000000114')
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Partial numbers are also supported, 6 digits is usually sufficient, 8 digits is better.
|
|
363
|
+
```js
|
|
364
|
+
var country = await VantagePayClient.lookups.getCardIssuerCountry('520001')
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
Example Output
|
|
368
|
+
```js
|
|
369
|
+
{
|
|
370
|
+
isAvailable: true,
|
|
371
|
+
country: 'MYS',
|
|
372
|
+
countryName: 'Malaysia',
|
|
373
|
+
longIsoCode: 'MYS',
|
|
374
|
+
shortIsoCode: 'MY',
|
|
375
|
+
numericIsoCode: 458,
|
|
376
|
+
diallingCode: '60'
|
|
377
|
+
}
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
---
|
|
381
|
+
# Subscribing to Events
|
|
382
|
+
The library uses [pubsub-js](https://www.npmjs.com/package/pubsub-js) to publish messages for subscribers. To subscribe to events you can use the `events` property on the client instance, which is a wrapper around PubSub so all the functions for the base library are available.
|
|
383
|
+
|
|
384
|
+
These events can be useful if your application needs to react to certain things happening behind the scenes. It is especially useful when used to automatically receive payment status updates during payment processing.
|
|
385
|
+
```js
|
|
386
|
+
import { VantagePay, OnApiRetry, OnAutomaticRefresh, OnSessionExpired } from '@vantagepay/vantagepay'
|
|
387
|
+
...
|
|
388
|
+
const onApiRetrySub = VantagePayClient.events.subscribe(OnApiRetry, (_, retryInfo) => console.log('API performed an automatic retry', retryInfo))
|
|
389
|
+
const onAutoRefreshSub = VantagePayClient.events.subscribe(OnAutomaticRefresh, (_, tokenResponse) => console.log('Automatic refresh was triggered', tokenResponse))
|
|
390
|
+
const onSessionExpiredSub = VantagePayClient.events.subscribe(OnSessionExpired, () => console.log('Session expired'))
|
|
391
|
+
...
|
|
392
|
+
// Unsubscribe if you no longer want to receive events.
|
|
393
|
+
VantagePayClient.events.unsubscribe(onApiRetrySub)
|
|
394
|
+
VantagePayClient.events.unsubscribe(onAutoRefreshSub)
|
|
395
|
+
VantagePayClient.events.unsubscribe(onSessionExpiredSub)
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
## OnSessionExpired ('login.session.expired')
|
|
399
|
+
This will be fired when an automatic refresh fails or a refresh token is no longer available when making a call and you are now logged out. No data will be included with this event.
|
|
400
|
+
|
|
401
|
+
## OnAutomaticRefresh ('login.session.refreshed')
|
|
402
|
+
This will be fired when an automatic token refresh occurs. This is useful to know when new tokens are available that you may want to save in secure storage. The token response is included with the event, you can also use `ApiTokens.accessToken` and `ApiTokens.refreshToken` to read the new values.
|
|
403
|
+
|
|
404
|
+
## OnApiRetry ('api.retry')
|
|
405
|
+
This will be fired whenever there is an automatic API request retry. This is useful to indicate to application users that the network may be slow or they lack connectivity.
|
|
406
|
+
The data included in the event indicates how many times the call has been retried.
|
|
407
|
+
```js
|
|
408
|
+
{ retryCount: 2 }
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
## OnPaymentStatusUpdate ('payment.status')
|
|
412
|
+
During payment processing (call to `payments.pay()`) this will be fired for any status change to the payment. This is mainly due to transaction status changes that the client can display or react to. Certain status changes will also change the transaction amounts (adjustments, fees, failures and others). The recommendation here is to create a single view that renders the transaction status and on each event render the new state.
|
|
413
|
+
|
|
414
|
+
Transaction status data will be based on the request made. The source and destination data will be based on the source ans destinations provided in the request. All the possibilities will be documented separately.
|
|
415
|
+
|
|
416
|
+
## OnPaymentComplete ('payment.complete')
|
|
417
|
+
This will be fired when the payment processing is complete. In the most basic payment processing client you can ignore `OnPaymentStatusUpdate` if you do not want to show progress and simply go to the completion screen when this fires. The event will include full payment status data the same as `OnPaymentStatusUpdate` so the transaction statuses and final amounts can be displayed. Success or failure will be based on the various transaction statues in the final results.
|
|
418
|
+
|
|
419
|
+
## OnRequires3DSecure ('payment.wait.requires3dSecure')
|
|
420
|
+
If card payment requires 3D Secure the client will need to launch a browser ot open an iFrame with the supplied URL and wait for `OnComplete3DSecure` to be fired before closing the browser or iFrame.
|
|
421
|
+
The data will include the URL to launch.
|
|
422
|
+
```js
|
|
423
|
+
{ url: 'https://some_url_that_will_start-3ds' }
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
### Pseudo Code
|
|
427
|
+
```js
|
|
428
|
+
async function handleRequires3DS(signalData) {
|
|
429
|
+
// You are given a URL that you simply need to launch or set at the `src` on an iFrame.
|
|
430
|
+
webBrowser = await open(signalData.url)
|
|
431
|
+
}
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
## OnComplete3DSecure ('payment.complete3dSecure')
|
|
435
|
+
This will fire once 3DS has completed as an indication that you can close the browser or iFrame that was launched when `OnRequires3DSecure` was fired. There is no additional data included in this event.
|
|
436
|
+
|
|
437
|
+
## OnRequiresPin ('payment.wait.requiresPin')
|
|
438
|
+
This will be fired if a transaction requires a PIN/OTP. The event data will include the message to display to the user so they are aware of what to provide. The text field can generally be numbers only.
|
|
439
|
+
```js
|
|
440
|
+
{
|
|
441
|
+
message: 'Please enter you Vodafone PIN to complete this transaction.',
|
|
442
|
+
transactionReference: '84125510-B042-417D-A532-47A7EBD47488',
|
|
443
|
+
pinLength: 6
|
|
444
|
+
}
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
Once the PIN has been captured you can make a call to `payments.submitPinCode()` with the `transactionReference` that was sent in the event to continue payment processing.
|
|
448
|
+
|
|
449
|
+
### Pseudo Code
|
|
450
|
+
```js
|
|
451
|
+
function handleRequiresPin(signalData) {
|
|
452
|
+
// You need to capture a PIN code and call `submitPinCode`.
|
|
453
|
+
const pin = prompt(signalData.message)
|
|
454
|
+
VantagePayClient.payments.submitPinCode(signalData.transactionReference, pin)
|
|
455
|
+
}
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
## OnRequiresConfirmation ('payment.wait.requiresConfirmation')
|
|
459
|
+
This will be fired if a transaction requires confirmation such as additional fees or even to verify account information. The event data will include the message to display to the user so they are aware of what they are confirming. The dialog to display can just have Yes/No buttons.
|
|
460
|
+
```js
|
|
461
|
+
{
|
|
462
|
+
message: 'The transaction requires an additional e-levy fee of GHS 3.00. Do you want to continue?',
|
|
463
|
+
transactionReference: '6FD502DE-20FF-4110-ABBE-8FE6D7733AAE',
|
|
464
|
+
confirmationData: {
|
|
465
|
+
amountInCents: 1025,
|
|
466
|
+
sourceAccountHolder: 'Steve Rogers',
|
|
467
|
+
destinationAccountHolder: 'Tony Stark',
|
|
468
|
+
fees: []
|
|
469
|
+
}
|
|
470
|
+
}
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
Once the response has been captured you can make a call to `payments.submitConfirmation()` with the `transactionReference` that was sent in the event to continue payment processing.
|
|
474
|
+
|
|
475
|
+
### Pseudo Code
|
|
476
|
+
```js
|
|
477
|
+
function handleRequiresConfirmation(signalData) {
|
|
478
|
+
// You need to ask the user for a Yes/No answer.
|
|
479
|
+
const confirmation = prompt(signalData.message + ' -Y/N - ')
|
|
480
|
+
VantagePayClient.payments.submitConfirmation(signalData.transactionReference, confirmation === 'Y' || confirmation === 'y')
|
|
481
|
+
}
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
## OnRequiresAddress ('payment.wait.requiresAddress')
|
|
485
|
+
This will be fired if address validation failed or an address is required but was not provided in the initial payment request. The event data will include the message to display to the user. The client should launch an address capture screen with the information provided (so it can corrected) a blank if no address information was provided.
|
|
486
|
+
```js
|
|
487
|
+
{
|
|
488
|
+
message: 'The address information provided does not appear to be valid. Please provide billing address information for this transaction.',
|
|
489
|
+
transactionReference: '6F4F250E-BF64-4BC2-936C-02E5A2982969'
|
|
490
|
+
}
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
Once the address details have been captured you can make a call to `payments.submitAddress()` with the `transactionReference` that was sent in the event to continue payment processing.
|
|
494
|
+
|
|
495
|
+
### Pseudo Code
|
|
496
|
+
```js
|
|
497
|
+
function handleRequiresAddress(signalData) {
|
|
498
|
+
// Let the user know what is required.
|
|
499
|
+
alert(signalData.message)
|
|
500
|
+
|
|
501
|
+
// You need to capture a PIN code and call `submitPinCode`.
|
|
502
|
+
const address = {
|
|
503
|
+
addressType: prompt('Type: ') || 'BILL',
|
|
504
|
+
addressLine1: prompt('Line 1: ') || '10 Whitley Road',
|
|
505
|
+
addressLine2: prompt('Line 2: ') || null,
|
|
506
|
+
addressLine3: prompt('Line 3: ') || null,
|
|
507
|
+
countryIsoCode: prompt('Country: ') || 'ZAF',
|
|
508
|
+
city: prompt('City: ') || 'Johannesburg',
|
|
509
|
+
state: prompt('State: ') || null,
|
|
510
|
+
postalCode: prompt('Postal Code: ') || '2196',
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
VantagePayClient.payments.submitAddress(signalData.transactionReference, address)
|
|
514
|
+
}
|
|
515
|
+
```
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { BaseApi } from '../baseApi';
|
|
2
|
+
import { TokenResponse } from './types';
|
|
3
|
+
export declare class Authentication extends BaseApi {
|
|
4
|
+
isLoggedIn(): boolean;
|
|
5
|
+
login(username: string, password: string): Promise<TokenResponse>;
|
|
6
|
+
logout(): Promise<void>;
|
|
7
|
+
refresh(token?: string): Promise<TokenResponse>;
|
|
8
|
+
changePassword(oldPassword: string, newPassword: string): Promise<TokenResponse>;
|
|
9
|
+
forgotPassword(username: string): Promise<void>;
|
|
10
|
+
validateOtp(otpValue: string): Promise<void>;
|
|
11
|
+
resendOtp(): Promise<void>;
|
|
12
|
+
resendEmailAddressVerification(): Promise<void>;
|
|
13
|
+
getCurrentConsumerReference(token?: string): string;
|
|
14
|
+
getCurrentMerchantReference(token?: string): string;
|
|
15
|
+
getCurrentBusinessReference(token?: string): string;
|
|
16
|
+
getCurrentTerminalReference(token?: string): string;
|
|
17
|
+
getCurrentUserReference(token?: string): string;
|
|
18
|
+
getCurrentUserName(token?: string): string;
|
|
19
|
+
getRedirectAction(token?: string): string;
|
|
20
|
+
getMobileNumber(token?: string): string;
|
|
21
|
+
getEmailAddress(token?: string): string;
|
|
22
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** Model to hold information to change a user's password. */
|
|
2
|
+
export declare class ChangePasswordRequest {
|
|
3
|
+
/** Gets or sets the old password. */
|
|
4
|
+
oldPassword?: string;
|
|
5
|
+
/** Gets or sets the new password (required). */
|
|
6
|
+
newPassword: string;
|
|
7
|
+
/** Gets or sets the reset code that need to be supplied if you are not authenticated. */
|
|
8
|
+
resetCode?: string;
|
|
9
|
+
/** Gets or sets the reference of the user that is linked to this login information. */
|
|
10
|
+
userReference?: string;
|
|
11
|
+
}
|
|
12
|
+
export declare class ForgotPasswordRequest {
|
|
13
|
+
username: string;
|
|
14
|
+
}
|
|
15
|
+
/** Model to hold login information that can be used to access the system and generate tokens. */
|
|
16
|
+
export declare class LoginCredentials {
|
|
17
|
+
/** Gets or sets the username (required). */
|
|
18
|
+
username: string;
|
|
19
|
+
/** Gets or sets the password (required). */
|
|
20
|
+
password: string;
|
|
21
|
+
}
|
|
22
|
+
/** Provides details for the reason why a login attempt failed (401 errors). */
|
|
23
|
+
export declare class LoginErrorResponse {
|
|
24
|
+
/** Gets or sets a value indicating whether either the username or password credentials provided to login are invalid. */
|
|
25
|
+
invalidUsernameOrPassword?: boolean;
|
|
26
|
+
/** Gets or sets a value indicating whether the user is required to change their password first before attempting to login. */
|
|
27
|
+
mustChangePassword?: boolean;
|
|
28
|
+
/** Gets or sets a value indicating whether the user is required to validate their phone number first (OTP or phone call) before attempting to login. */
|
|
29
|
+
mustValidatePhoneNumber?: boolean;
|
|
30
|
+
/** Gets or sets a value indicating whether the user is required to validate their email address first before attempting to login. */
|
|
31
|
+
mustValidateEmailAddress?: boolean;
|
|
32
|
+
/** Gets or sets a value indicating whether the user has been deactivated. */
|
|
33
|
+
deactivated?: boolean;
|
|
34
|
+
/** Gets or sets a value indicating whether further information about the user is required and the registration process needs to be complete before attempting to login. */
|
|
35
|
+
registrationRequired?: boolean;
|
|
36
|
+
/** Gets or sets a value indicating whether the user is currently locked out. */
|
|
37
|
+
lockedOut?: boolean;
|
|
38
|
+
/** Gets or sets an access token that can be used to call the change password end-point. */
|
|
39
|
+
changePasswordAccessToken?: string;
|
|
40
|
+
/** Gets or sets an access token that can be used to call the change password end-point. */
|
|
41
|
+
validatePhoneNumberAccessToken?: string;
|
|
42
|
+
/** Gets or sets an access token that can be used to call the resend email verification end-point, and view current merchant / consumer details. */
|
|
43
|
+
resendEmailVerificationToken?: string;
|
|
44
|
+
}
|
|
45
|
+
/** Model to hold the credentials for a login attempt. */
|
|
46
|
+
export declare class LoginRequest {
|
|
47
|
+
/** Gets or sets the username (required). */
|
|
48
|
+
username: string;
|
|
49
|
+
/** Gets or sets the password (required). */
|
|
50
|
+
password: string;
|
|
51
|
+
}
|
|
52
|
+
export declare class OtpVerificationRequest {
|
|
53
|
+
otpValue: string;
|
|
54
|
+
}
|
|
55
|
+
export declare class OtpVerificationResponse {
|
|
56
|
+
userAccountExists: boolean;
|
|
57
|
+
accessToken: string;
|
|
58
|
+
}
|
|
59
|
+
/** Provides token information for successful login and refresh operations. */
|
|
60
|
+
export declare class TokenResponse {
|
|
61
|
+
/** Gets or sets a JWT Refresh token that can be used to request a new Access tokens. */
|
|
62
|
+
refreshToken?: string;
|
|
63
|
+
/** Gets or sets a JWT Access token that can be used to make API calls. */
|
|
64
|
+
accessToken?: string;
|
|
65
|
+
/** Gets or sets the amount of time (in seconds) for which the Access token will be valid. */
|
|
66
|
+
accessTokenValidForSeconds: number;
|
|
67
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { AxiosInstance } from 'axios';
|
|
2
|
+
export { default as ApiTokens } from './apiTokens';
|
|
3
|
+
export declare abstract class BaseApi {
|
|
4
|
+
private readonly axiosInstance;
|
|
5
|
+
protected readonly consoleLogging: boolean;
|
|
6
|
+
protected readonly events: PubSubJS.Base<any, PubSubJS.Message>;
|
|
7
|
+
constructor(axiosInstance: AxiosInstance, consoleLogging?: boolean);
|
|
8
|
+
protected request<T>(endpoint: string, method: string, body?: any, token?: string | null): Promise<T>;
|
|
9
|
+
}
|