rma-payment-gateway 1.0.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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +60 -0
- data/CODE_OF_CONDUCT.md +132 -0
- data/README.md +446 -0
- data/Rakefile +12 -0
- data/docs/API.md +339 -0
- data/docs/EXAMPLES.md +650 -0
- data/docs/FLOW_DIAGRAM.md +440 -0
- data/docs/QUICK_REFERENCE.md +323 -0
- data/docs/README.md +259 -0
- data/docs/SECURITY.md +506 -0
- data/docs/USAGE_GUIDE.md +522 -0
- data/lib/rma/payment/gateway/account_inquiry.rb +69 -0
- data/lib/rma/payment/gateway/authorization.rb +81 -0
- data/lib/rma/payment/gateway/client.rb +124 -0
- data/lib/rma/payment/gateway/configuration.rb +42 -0
- data/lib/rma/payment/gateway/debit_request.rb +65 -0
- data/lib/rma/payment/gateway/errors.rb +42 -0
- data/lib/rma/payment/gateway/utils.rb +130 -0
- data/lib/rma/payment/gateway/version.rb +9 -0
- data/lib/rma/payment/gateway.rb +24 -0
- data/sig/rma/payment/gateway.rbs +8 -0
- metadata +65 -0
|
@@ -0,0 +1,440 @@
|
|
|
1
|
+
# Payment Flow Diagrams
|
|
2
|
+
|
|
3
|
+
This document provides visual representations of the RMA Payment Gateway payment flow.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Complete Payment Flow](#complete-payment-flow)
|
|
8
|
+
- [Step-by-Step Flow](#step-by-step-flow)
|
|
9
|
+
- [Error Handling Flow](#error-handling-flow)
|
|
10
|
+
- [Sequence Diagrams](#sequence-diagrams)
|
|
11
|
+
|
|
12
|
+
## Complete Payment Flow
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
┌─────────────┐
|
|
16
|
+
│ Merchant │
|
|
17
|
+
│ Application │
|
|
18
|
+
└──────┬──────┘
|
|
19
|
+
│
|
|
20
|
+
│ 1. Initiate Payment
|
|
21
|
+
│ - Order Number
|
|
22
|
+
│ - Amount
|
|
23
|
+
│ - Customer Email
|
|
24
|
+
▼
|
|
25
|
+
┌─────────────────────────────────┐
|
|
26
|
+
│ RMA Payment Gateway Client │
|
|
27
|
+
│ .authorization.call() │
|
|
28
|
+
└──────────┬──────────────────────┘
|
|
29
|
+
│
|
|
30
|
+
│ POST /BFSSecure/nvpapi
|
|
31
|
+
│ bfs_msgType=AR
|
|
32
|
+
▼
|
|
33
|
+
┌─────────────────────────────────┐
|
|
34
|
+
│ RMA Payment Gateway API │
|
|
35
|
+
└──────────┬──────────────────────┘
|
|
36
|
+
│
|
|
37
|
+
│ Returns Transaction ID
|
|
38
|
+
▼
|
|
39
|
+
┌─────────────────────────────────┐
|
|
40
|
+
│ Merchant Application │
|
|
41
|
+
│ Store Transaction ID │
|
|
42
|
+
└──────────┬──────────────────────┘
|
|
43
|
+
│
|
|
44
|
+
│ 2. Customer Provides
|
|
45
|
+
│ - Bank ID
|
|
46
|
+
│ - Account Number
|
|
47
|
+
▼
|
|
48
|
+
┌─────────────────────────────────┐
|
|
49
|
+
│ RMA Payment Gateway Client │
|
|
50
|
+
│ .account_inquiry.call() │
|
|
51
|
+
└──────────┬──────────────────────┘
|
|
52
|
+
│
|
|
53
|
+
│ POST /BFSSecure/nvpapi
|
|
54
|
+
│ bfs_msgType=AE
|
|
55
|
+
▼
|
|
56
|
+
┌─────────────────────────────────┐
|
|
57
|
+
│ RMA Payment Gateway API │
|
|
58
|
+
│ - Verify Account │
|
|
59
|
+
│ - Send OTP to Customer │
|
|
60
|
+
└──────────┬──────────────────────┘
|
|
61
|
+
│
|
|
62
|
+
│ Returns Account Info
|
|
63
|
+
▼
|
|
64
|
+
┌─────────────────────────────────┐
|
|
65
|
+
│ Customer Receives OTP │
|
|
66
|
+
│ (via SMS to registered mobile) │
|
|
67
|
+
└──────────┬──────────────────────┘
|
|
68
|
+
│
|
|
69
|
+
│ 3. Customer Provides OTP
|
|
70
|
+
▼
|
|
71
|
+
┌─────────────────────────────────┐
|
|
72
|
+
│ RMA Payment Gateway Client │
|
|
73
|
+
│ .debit_request.call() │
|
|
74
|
+
└──────────┬──────────────────────┘
|
|
75
|
+
│
|
|
76
|
+
│ POST /BFSSecure/nvpapi
|
|
77
|
+
│ bfs_msgType=DR
|
|
78
|
+
▼
|
|
79
|
+
┌─────────────────────────────────┐
|
|
80
|
+
│ RMA Payment Gateway API │
|
|
81
|
+
│ - Verify OTP │
|
|
82
|
+
│ - Process Payment │
|
|
83
|
+
│ - Debit Customer Account │
|
|
84
|
+
└──────────┬──────────────────────┘
|
|
85
|
+
│
|
|
86
|
+
│ Returns Payment Confirmation
|
|
87
|
+
▼
|
|
88
|
+
┌─────────────────────────────────┐
|
|
89
|
+
│ Merchant Application │
|
|
90
|
+
│ - Mark Order as Paid │
|
|
91
|
+
│ - Send Confirmation to Customer│
|
|
92
|
+
└─────────────────────────────────┘
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Step-by-Step Flow
|
|
96
|
+
|
|
97
|
+
### Step 1: Payment Authorization
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
101
|
+
│ Merchant │ │ Gem │ │ RMA │
|
|
102
|
+
│ App │ │ Client │ │ API │
|
|
103
|
+
└────┬─────┘ └────┬─────┘ └────┬─────┘
|
|
104
|
+
│ │ │
|
|
105
|
+
│ authorization.call() │ │
|
|
106
|
+
│ - order_no: "ORDER123" │ │
|
|
107
|
+
│ - amount: 100.50 │ │
|
|
108
|
+
│ - email: "user@example.com" │ │
|
|
109
|
+
├──────────────────────────────>│ │
|
|
110
|
+
│ │ │
|
|
111
|
+
│ │ POST /BFSSecure/nvpapi │
|
|
112
|
+
│ │ bfs_msgType=AR │
|
|
113
|
+
│ │ bfs_orderNo=ORDER123 │
|
|
114
|
+
│ │ bfs_txnAmount=100.50 │
|
|
115
|
+
│ │ bfs_remitterEmail=user@... │
|
|
116
|
+
│ ├──────────────────────────────>│
|
|
117
|
+
│ │ │
|
|
118
|
+
│ │ │ Validate
|
|
119
|
+
│ │ │ Request
|
|
120
|
+
│ │ │
|
|
121
|
+
│ │ Response │
|
|
122
|
+
│ │ bfs_bfsTxnId=TXN123 │
|
|
123
|
+
│ │ bfs_responseCode=00 │
|
|
124
|
+
│ │<──────────────────────────────┤
|
|
125
|
+
│ │ │
|
|
126
|
+
│ Return Response │ │
|
|
127
|
+
│ transaction_id: "TXN123" │ │
|
|
128
|
+
│<──────────────────────────────┤ │
|
|
129
|
+
│ │ │
|
|
130
|
+
│ Store Transaction ID │ │
|
|
131
|
+
│ │ │
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Step 2: Account Inquiry
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
138
|
+
│ Merchant │ │ Gem │ │ RMA │
|
|
139
|
+
│ App │ │ Client │ │ API │
|
|
140
|
+
└────┬─────┘ └────┬─────┘ └────┬─────┘
|
|
141
|
+
│ │ │
|
|
142
|
+
│ account_inquiry.call() │ │
|
|
143
|
+
│ - transaction_id: "TXN123" │ │
|
|
144
|
+
│ - bank_id: "1010" │ │
|
|
145
|
+
│ - account_no: "12345678" │ │
|
|
146
|
+
├──────────────────────────────>│ │
|
|
147
|
+
│ │ │
|
|
148
|
+
│ │ POST /BFSSecure/nvpapi │
|
|
149
|
+
│ │ bfs_msgType=AE │
|
|
150
|
+
│ │ bfs_bfsTxnId=TXN123 │
|
|
151
|
+
│ │ bfs_remitterBankId=1010 │
|
|
152
|
+
│ │ bfs_remitterAccNo=12345678 │
|
|
153
|
+
│ ├──────────────────────────────>│
|
|
154
|
+
│ │ │
|
|
155
|
+
│ │ │ Verify
|
|
156
|
+
│ │ │ Account
|
|
157
|
+
│ │ │
|
|
158
|
+
│ │ │ Send OTP
|
|
159
|
+
│ │ │ to Customer
|
|
160
|
+
│ │ │
|
|
161
|
+
│ │ Response │
|
|
162
|
+
│ │ bfs_remitterName=John Doe │
|
|
163
|
+
│ │ bfs_responseCode=00 │
|
|
164
|
+
│ │<──────────────────────────────┤
|
|
165
|
+
│ │ │
|
|
166
|
+
│ Return Response │ │
|
|
167
|
+
│ account_name: "John Doe" │ │
|
|
168
|
+
│<──────────────────────────────┤ │
|
|
169
|
+
│ │ │
|
|
170
|
+
│ Display Account Info │ │
|
|
171
|
+
│ Request OTP from Customer │ │
|
|
172
|
+
│ │ │
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Step 3: Debit Request
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
179
|
+
│ Merchant │ │ Gem │ │ RMA │
|
|
180
|
+
│ App │ │ Client │ │ API │
|
|
181
|
+
└────┬─────┘ └────┬─────┘ └────┬─────┘
|
|
182
|
+
│ │ │
|
|
183
|
+
│ debit_request.call() │ │
|
|
184
|
+
│ - transaction_id: "TXN123" │ │
|
|
185
|
+
│ - otp: "123456" │ │
|
|
186
|
+
├──────────────────────────────>│ │
|
|
187
|
+
│ │ │
|
|
188
|
+
│ │ POST /BFSSecure/nvpapi │
|
|
189
|
+
│ │ bfs_msgType=DR │
|
|
190
|
+
│ │ bfs_bfsTxnId=TXN123 │
|
|
191
|
+
│ │ bfs_remitterOtp=123456 │
|
|
192
|
+
│ ├──────────────────────────────>│
|
|
193
|
+
│ │ │
|
|
194
|
+
│ │ │ Verify
|
|
195
|
+
│ │ │ OTP
|
|
196
|
+
│ │ │
|
|
197
|
+
│ │ │ Process
|
|
198
|
+
│ │ │ Payment
|
|
199
|
+
│ │ │
|
|
200
|
+
│ │ │ Debit
|
|
201
|
+
│ │ │ Account
|
|
202
|
+
│ │ │
|
|
203
|
+
│ │ Response │
|
|
204
|
+
│ │ bfs_responseCode=00 │
|
|
205
|
+
│ │ bfs_txnAmount=100.50 │
|
|
206
|
+
│ │<──────────────────────────────┤
|
|
207
|
+
│ │ │
|
|
208
|
+
│ Return Response │ │
|
|
209
|
+
│ payment_status: "completed" │ │
|
|
210
|
+
│<──────────────────────────────┤ │
|
|
211
|
+
│ │ │
|
|
212
|
+
│ Mark Order as Paid │ │
|
|
213
|
+
│ Send Confirmation │ │
|
|
214
|
+
│ │ │
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Error Handling Flow
|
|
218
|
+
|
|
219
|
+
```
|
|
220
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
221
|
+
│ Payment Request │
|
|
222
|
+
└────────────────────────┬─────────────────────────────────────┘
|
|
223
|
+
│
|
|
224
|
+
▼
|
|
225
|
+
┌──────────────┐
|
|
226
|
+
│ Validate │
|
|
227
|
+
│ Input │
|
|
228
|
+
└──────┬───────┘
|
|
229
|
+
│
|
|
230
|
+
┌────┴────┐
|
|
231
|
+
│ Valid? │
|
|
232
|
+
└────┬────┘
|
|
233
|
+
│
|
|
234
|
+
┌──────────┴──────────┐
|
|
235
|
+
│ │
|
|
236
|
+
Yes No
|
|
237
|
+
│ │
|
|
238
|
+
▼ ▼
|
|
239
|
+
┌──────────────┐ ┌─────────────────────┐
|
|
240
|
+
│ Send Request │ │ InvalidParameterError│
|
|
241
|
+
│ to RMA API │ │ Return Error to User │
|
|
242
|
+
└──────┬───────┘ └─────────────────────┘
|
|
243
|
+
│
|
|
244
|
+
▼
|
|
245
|
+
┌──────────────┐
|
|
246
|
+
│ API Response │
|
|
247
|
+
└──────┬───────┘
|
|
248
|
+
│
|
|
249
|
+
┌────┴────┐
|
|
250
|
+
│Response │
|
|
251
|
+
│ Code? │
|
|
252
|
+
└────┬────┘
|
|
253
|
+
│
|
|
254
|
+
┌────────┼────────┐
|
|
255
|
+
│ │ │
|
|
256
|
+
"00" Other Error
|
|
257
|
+
│ │ │
|
|
258
|
+
▼ ▼ ▼
|
|
259
|
+
┌────────┐ ┌──────┐ ┌──────────────┐
|
|
260
|
+
│Success │ │Retry?│ │ Raise Error │
|
|
261
|
+
│ │ │ │ │ - Network │
|
|
262
|
+
│ │ │ │ │ - Auth │
|
|
263
|
+
│ │ │ │ │ - API │
|
|
264
|
+
└────────┘ └──────┘ └──────────────┘
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## Sequence Diagrams
|
|
268
|
+
|
|
269
|
+
### Complete Payment Sequence
|
|
270
|
+
|
|
271
|
+
```
|
|
272
|
+
Customer Merchant Gem Client RMA API Bank
|
|
273
|
+
│ │ │ │ │
|
|
274
|
+
│ Browse │ │ │ │
|
|
275
|
+
│ & Order │ │ │ │
|
|
276
|
+
├──────────>│ │ │ │
|
|
277
|
+
│ │ │ │ │
|
|
278
|
+
│ │ Step 1: Authorization │ │
|
|
279
|
+
│ ├───────────>│ │ │
|
|
280
|
+
│ │ ├───────────>│ │
|
|
281
|
+
│ │ │<───────────┤ │
|
|
282
|
+
│ │<───────────┤ │ │
|
|
283
|
+
│ │ (TXN ID) │ │ │
|
|
284
|
+
│ │ │ │ │
|
|
285
|
+
│ Provide │ │ │ │
|
|
286
|
+
│ Bank │ │ │ │
|
|
287
|
+
│ Details │ │ │ │
|
|
288
|
+
├──────────>│ │ │ │
|
|
289
|
+
│ │ │ │ │
|
|
290
|
+
│ │ Step 2: Account Inquiry │ │
|
|
291
|
+
│ ├───────────>│ │ │
|
|
292
|
+
│ │ ├───────────>│ │
|
|
293
|
+
│ │ │ ├────────>│
|
|
294
|
+
│ │ │ │ Verify │
|
|
295
|
+
│ │ │ │<────────┤
|
|
296
|
+
│<──────────┼────────────┼────────────┤ │
|
|
297
|
+
│ OTP SMS │ │ │ │
|
|
298
|
+
│ │ │<───────────┤ │
|
|
299
|
+
│ │<───────────┤ │ │
|
|
300
|
+
│ │ (Account │ │ │
|
|
301
|
+
│ │ Info) │ │ │
|
|
302
|
+
│ │ │ │ │
|
|
303
|
+
│ Enter │ │ │ │
|
|
304
|
+
│ OTP │ │ │ │
|
|
305
|
+
├──────────>│ │ │ │
|
|
306
|
+
│ │ │ │ │
|
|
307
|
+
│ │ Step 3: Debit Request │ │
|
|
308
|
+
│ ├───────────>│ │ │
|
|
309
|
+
│ │ ├───────────>│ │
|
|
310
|
+
│ │ │ ├────────>│
|
|
311
|
+
│ │ │ │ Debit │
|
|
312
|
+
│ │ │ │<────────┤
|
|
313
|
+
│ │ │<───────────┤ │
|
|
314
|
+
│ │<───────────┤ │ │
|
|
315
|
+
│ │ (Success) │ │ │
|
|
316
|
+
│ │ │ │ │
|
|
317
|
+
│<──────────┤ │ │ │
|
|
318
|
+
│Confirmation │ │ │
|
|
319
|
+
│ │ │ │ │
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
## State Diagram
|
|
323
|
+
|
|
324
|
+
```
|
|
325
|
+
┌─────────────┐
|
|
326
|
+
│ Pending │ Initial state
|
|
327
|
+
└──────┬──────┘
|
|
328
|
+
│
|
|
329
|
+
│ authorization.call()
|
|
330
|
+
▼
|
|
331
|
+
┌─────────────┐
|
|
332
|
+
│ Authorized │ Transaction ID received
|
|
333
|
+
└──────┬──────┘
|
|
334
|
+
│
|
|
335
|
+
│ account_inquiry.call()
|
|
336
|
+
▼
|
|
337
|
+
┌─────────────┐
|
|
338
|
+
│ Account │ OTP sent to customer
|
|
339
|
+
│ Verified │
|
|
340
|
+
└──────┬──────┘
|
|
341
|
+
│
|
|
342
|
+
│ debit_request.call()
|
|
343
|
+
▼
|
|
344
|
+
┌─────────────┐
|
|
345
|
+
│ Completed │ Payment successful
|
|
346
|
+
└─────────────┘
|
|
347
|
+
|
|
348
|
+
│
|
|
349
|
+
│ (Any step can fail)
|
|
350
|
+
▼
|
|
351
|
+
┌─────────────┐
|
|
352
|
+
│ Failed │ Error occurred
|
|
353
|
+
└─────────────┘
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
## Integration Patterns
|
|
357
|
+
|
|
358
|
+
### Pattern 1: Synchronous Flow
|
|
359
|
+
|
|
360
|
+
```
|
|
361
|
+
User Action → Authorization → Account Inquiry → Debit Request → Completion
|
|
362
|
+
│ │ │ │ │
|
|
363
|
+
└──────────────┴───────────────┴────────────────┴──────────────┘
|
|
364
|
+
All steps in same session
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
### Pattern 2: Asynchronous Flow
|
|
368
|
+
|
|
369
|
+
```
|
|
370
|
+
User Action → Authorization → Store State
|
|
371
|
+
│
|
|
372
|
+
Customer Returns → Account Inquiry → Store State
|
|
373
|
+
│
|
|
374
|
+
Customer Enters OTP → Debit Request → Completion
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
### Pattern 3: Background Job Flow
|
|
378
|
+
|
|
379
|
+
```
|
|
380
|
+
User Action → Queue Job → Authorization
|
|
381
|
+
│
|
|
382
|
+
▼
|
|
383
|
+
Queue Job → Account Inquiry
|
|
384
|
+
│
|
|
385
|
+
▼
|
|
386
|
+
Queue Job → Debit Request
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
## Error Recovery Flow
|
|
390
|
+
|
|
391
|
+
```
|
|
392
|
+
┌─────────────┐
|
|
393
|
+
│ Attempt │
|
|
394
|
+
│ Payment │
|
|
395
|
+
└──────┬──────┘
|
|
396
|
+
│
|
|
397
|
+
▼
|
|
398
|
+
┌─────────────┐
|
|
399
|
+
│ Error? │
|
|
400
|
+
└──────┬──────┘
|
|
401
|
+
│
|
|
402
|
+
┌───┴───┐
|
|
403
|
+
│ │
|
|
404
|
+
Yes No
|
|
405
|
+
│ │
|
|
406
|
+
▼ ▼
|
|
407
|
+
┌──────┐ ┌────────┐
|
|
408
|
+
│Error │ │Success │
|
|
409
|
+
│Type? │ └────────┘
|
|
410
|
+
└──┬───┘
|
|
411
|
+
│
|
|
412
|
+
├─ Network Error ──> Retry with backoff
|
|
413
|
+
│
|
|
414
|
+
├─ Invalid Param ──> Show error to user
|
|
415
|
+
│
|
|
416
|
+
├─ Auth Error ────> Check config, retry
|
|
417
|
+
│
|
|
418
|
+
├─ OTP Error ─────> Allow re-entry
|
|
419
|
+
│
|
|
420
|
+
└─ Other Error ───> Log & notify admin
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
## Best Practices
|
|
424
|
+
|
|
425
|
+
1. **Always store transaction ID** after authorization
|
|
426
|
+
2. **Validate inputs** before each API call
|
|
427
|
+
3. **Handle all error types** appropriately
|
|
428
|
+
4. **Implement timeouts** for each step
|
|
429
|
+
5. **Log all transactions** (with masked sensitive data)
|
|
430
|
+
6. **Provide clear feedback** to users at each step
|
|
431
|
+
7. **Implement retry logic** for network errors only
|
|
432
|
+
8. **Never retry** validation or authentication errors
|
|
433
|
+
|
|
434
|
+
## Related Documentation
|
|
435
|
+
|
|
436
|
+
- [API Documentation](API.md) - Detailed API reference
|
|
437
|
+
- [Usage Guide](USAGE_GUIDE.md) - Integration examples
|
|
438
|
+
- [Code Examples](EXAMPLES.md) - Practical code samples
|
|
439
|
+
- [Security Guide](SECURITY.md) - Security best practices
|
|
440
|
+
|