├── .gitignore ├── .travis.yml ├── documentation ├── head.md ├── errors.md ├── foot.md └── BaseGateway.md ├── index.js ├── lib ├── errors.js └── BaseGateway.js ├── gulpFile.js ├── package.json ├── README.md └── readme.md /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | node_modules 3 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 3 | - '8' -------------------------------------------------------------------------------- /documentation/head.md: -------------------------------------------------------------------------------- 1 | # 42-cent-base 2 | 3 | Interface to implement by 42-cent adaptor. See [documentation](https://github.com/continuous-software/42-cent) for more information. -------------------------------------------------------------------------------- /documentation/errors.md: -------------------------------------------------------------------------------- 1 | # Global 2 | 3 | 4 | 5 | 6 | 7 | * * * 8 | 9 | ## Class: GatewayError 10 | thrown when a specific gateway return an error message 11 | 12 | 13 | 14 | * * * 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | //todo move mapKeys and flat to a 42-cent-utility module 2 | //todo move Prospect, CreditCard, Subscription plan to a 42-cent-model module 3 | module.exports = { 4 | BaseGateway: require('./lib/BaseGateway.js'), 5 | GatewayError: require('./lib/errors.js').GatewayError 6 | }; 7 | -------------------------------------------------------------------------------- /lib/errors.js: -------------------------------------------------------------------------------- 1 | var util = require('util'); 2 | 3 | /** 4 | * thrown when a specific gateway return an error message 5 | * @param {String} message - the error message 6 | * @param {Object} original - the original message specific to the gateway 7 | * @constructor 8 | */ 9 | function GatewayError(message, original) { 10 | Error.call(this, arguments); 11 | this.message = message; 12 | this._original = original; 13 | } 14 | 15 | util.inherits(GatewayError, Error); 16 | 17 | module.exports = { 18 | GatewayError:GatewayError 19 | }; -------------------------------------------------------------------------------- /gulpFile.js: -------------------------------------------------------------------------------- 1 | var gulp = require('gulp'); 2 | var jsdox = require('jsdox'); 3 | var concat = require('gulp-concat'); 4 | var version = require('./package.json').version; 5 | 6 | gulp.task('documentation', function (done) { 7 | jsdox.generateForDir('./lib/', 'documentation', './node_modules/jsdox/templates', done); 8 | }); 9 | 10 | gulp.task('readme', gulp.series('documentation', function (done) { 11 | 12 | gulp.src('./documentation/*.md') 13 | .pipe(concat('readme.md')) 14 | .pipe(gulp.dest('./')); 15 | done(); 16 | })); 17 | 18 | gulp.task('default', gulp.series('readme')); 19 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "42-cent-base", 3 | "version": "1.0.0", 4 | "description": "structural interface for 42-cent adaptors", 5 | "main": "index.js", 6 | "scripts": { 7 | "test": "exit 0" 8 | }, 9 | "keywords": [ 10 | "42-cent", 11 | "payment", 12 | "gateway" 13 | ], 14 | "author": "Laurent Renard", 15 | "license": "MIT", 16 | "dependencies": { 17 | "bluebird": "^3.5.1" 18 | }, 19 | "repository": { 20 | "type": "git", 21 | "url": "https://github.com/continuous-software/42-cent-base.git" 22 | }, 23 | "devDependencies": { 24 | "gulp": "^4.0.0", 25 | "gulp-concat": "^2.4.0", 26 | "jsdox": "^0.4.2" 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /documentation/foot.md: -------------------------------------------------------------------------------- 1 | ## license 2 | 3 | 42-cent-base module is under MIT license: 4 | 5 | > Copyright (C) 2014 Laurent Renard. 6 | > 7 | > Permission is hereby granted, free of charge, to any person 8 | > obtaining a copy of this software and associated documentation files 9 | > (the "Software"), to deal in the Software without restriction, 10 | > including without limitation the rights to use, copy, modify, merge, 11 | > publish, distribute, sublicense, and/or sell copies of the Software, 12 | > and to permit persons to whom the Software is furnished to do so, 13 | > subject to the following conditions: 14 | > 15 | > The above copyright notice and this permission notice shall be 16 | > included in all copies or substantial portions of the Software. 17 | > 18 | > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 19 | > EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 20 | > MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 21 | > NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 22 | > BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 23 | > ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 24 | > CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 25 | > SOFTWARE. -------------------------------------------------------------------------------- /documentation/BaseGateway.md: -------------------------------------------------------------------------------- 1 | # Global 2 | 3 | 4 | 5 | 6 | 7 | * * * 8 | 9 | ## Class: BaseGateway 10 | Structural interface, actual implementations must implement 11 | 12 | ### BaseGateway.submitTransaction(order, creditCard, prospect, other) 13 | 14 | authorize and capture a transaction. 15 | 16 | all values must be Strings 17 | 18 | **Parameters** 19 | 20 | **order**: `Object`, the fields related to the order 21 |
22 |
amount
23 |
the amount of the transaction
24 |
25 | 26 | **creditCard**: `CreditCard | Object`, object holding credit card information 27 |
28 |
creditCardNumber
29 |
the credit card number used for the transaction - a string with card number digit, no blank, no dash, etc
30 |
expirationMonth - two digit string : 01 -> 12
31 |
The month of credit card expiration date
32 |
expirationYear
33 |
The year of credit card expiration date - four or two digits string 2016 or 16
34 |
cvv
35 |
the credit card cvv number
36 |
37 | 38 | **prospect**: `Prospect | Object`, the fields related to the prospect 39 |
40 |
customerFirstName
41 |
first name of the customer (also used for the billing)
42 |
customerLastName(also used for the billing)
43 |
last name of the customer
44 |
customerEmail(also used for the billing)
45 |
email of the customer
46 |
billingAddress
47 |
the billing address
48 |
billingCity
49 |
the billing city
50 |
billingState
51 |
the billing state
52 |
billingZip
53 |
billing zip code
54 |
billingCountry
55 |
the billing country
56 |
shippingFirstName
57 |
the shipping first name
58 |
shippingLastName
59 |
the shipping last name
60 |
shippingAddress
61 |
the shipping address
62 |
shippingCity
63 |
the shipping city
64 |
shippingState
65 |
the shipping state
66 |
shippingZip
67 |
shipping zip code
68 |
shippingCountry
69 |
the shipping country
70 | 71 |
72 | 73 | **other**: `Object`, other field specific to a gateway sdk implementation. refer to specific sdk for more details 74 | 75 | **Returns**: `Promise`, - the promise will have these different fields 76 | 77 | if resolved 78 |
79 |
transactionId
80 |
A unique identifier of the transaction.
81 |
authCode
82 |
authorization code from the banking institution
83 |
_original
84 |
the original response from the specific sdk implementation
85 |
86 | 87 | if rejected 88 | 89 | if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 90 |
91 |
message
92 |
The error message from the gateway
93 |
_original
94 |
The original response from the specific sdk implementation
95 |
96 | 97 | otherwise it will be an instance of standard javascript Error 98 | 99 | ### BaseGateway.authorizeTransaction(order, creditCard, prospect, other) 100 | 101 | authorize only a transaction 102 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 103 | 104 | **Parameters** 105 | 106 | **order**: , authorize only a transaction 107 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 108 | 109 | **creditCard**: , authorize only a transaction 110 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 111 | 112 | **prospect**: , authorize only a transaction 113 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 114 | 115 | **other**: , authorize only a transaction 116 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 117 | 118 | 119 | ### BaseGateway.getSettledBatchList(from, to) 120 | 121 | get a batch list of settled transaction within the window of time 122 | 123 | **Parameters** 124 | 125 | **from**: `String | Date`, Lower limit. If String, it must be a valid date string: a string which will result in a valid Javascript Date object if passed as argument of the Date constructor 126 | 127 | **to**: `String | Date`, Upper limit (or today if not provided). If String, it must be a valid date string: a string which will result in a valid Javascript Date object if passed as argument of the Date constructor 128 | 129 | **Returns**: `Promise`, - The promise should resolve with the following fields 130 |
131 |
batchList
132 |
An array of batch where a batch will have the following fields 133 |
134 |
batchId
135 |
The id the batch is referenced by in the gateway internal system
136 |
settlementDate
137 |
A string for the settlement date time (UTC)
138 |
chargeAmount
139 |
the total amount from the charged transactions during the window of time
140 |
chargeCount
141 |
the total count of charged transactions during the window of time
142 |
refundAmount
143 |
the total amount from the refunded transactions during the window of time
144 |
refundCount
145 |
the total count of refund transactions during the window of time
146 |
voidCount
147 |
the total count of voided transactions during the window of time
148 |
declineCount
149 |
the total count of voided transactions during the window of time
150 |
errorCount
151 |
the total count of voided transactions during the window of time
152 |
153 |
154 |
155 | 156 | ### BaseGateway.refundTransaction(transactionId, options) 157 | 158 | Refund (or credit) an already settled transaction 159 | 160 | **Parameters** 161 | 162 | **transactionId**: `String`, the reference to the transaction to refund (used by the underlying payment gateway system) 163 | 164 | **options**: `Object`, a set of optional fields 165 |
166 |
amount
167 |
the amount to be refunded (partial refund)
168 |
169 | 170 | **Returns**: `Promise`, - the result promise will have the following fields 171 | 172 | if resolved 173 |
174 |
_original
175 |
the original response from the payment gateway
176 | 177 | 178 | if rejected 179 | 180 | if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 181 |
182 |
message
183 |
The error message from the gateway
184 |
_original
185 |
The original response from the specific sdk implementation
186 |
187 | 188 | otherwise it will be an instance of standard javascript Error 189 | 190 | ### BaseGateway.voidTransaction(transactionId, options) 191 | 192 | void a (non settled) transaction 193 | 194 | **Parameters** 195 | 196 | **transactionId**: `String`, the reference to the transaction to void (used by the underlying payment gateway system) 197 | 198 | **options**: `Object`, a set of optional fields 199 | 200 | **Returns**: `Promise`, - the result promise will have the following fields 201 | 202 | if resolved 203 |
204 |
_original
205 |
the original response from the payment gateway
206 | 207 | 208 | if rejected 209 | 210 | if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 211 |
212 |
message
213 |
The error message from the gateway
214 |
_original
215 |
The original response from the specific sdk implementation
216 |
217 | 218 | otherwise it will be an instance of standard javascript Error 219 | 220 | ### BaseGateway.createSubscription(creditCard, prospect, subscriptionPlan, other) 221 | 222 | create a recurring payment 223 | 224 | **Parameters** 225 | 226 | **creditCard**: `CreditCard | Object`, the credit card associated to the payment 227 | 228 | **prospect**: `Prospect | Object`, the prospect/customer linked to the subscription 229 | 230 | **subscriptionPlan**: `SubscriptionPlan | Object`, a subscription plan 231 | Note that the tuple [periodUnit , periodLength] must result in a period supported by the gateway implementation otherwise periodUnit should take priority 232 | 233 | **other**: `Object`, a set of options to be used by specific implementations 234 | 235 | **Returns**: `Promise`, - the result promise will have the following fields 236 | 237 | if resolved 238 |
239 |
subscriptionId
240 |
a reference id to the subscription
241 |
_original
242 |
the original response from the payment gateway
243 | 244 | 245 | ### BaseGateway.createCustomerProfile(payment, billing, shipping, other) 246 | 247 | create a customer profile in gateway system, useful to charge a customer without having to use his payment info 248 | 249 | **Parameters** 250 | 251 | **payment**: `CreditCard | Object`, payment info to associate with the customer 252 | 253 | **billing**: `Object`, billing info to associate with the customer 254 | 255 | **shipping**: `Object`, shipping info to associate with the customer 256 | 257 | **other**: `Object`, optional info related to a specific gateway implementation 258 | 259 | **Returns**: `Promise`, - the resolve promise will have the following fields 260 | 261 | if resolved 262 |
263 |
profileId
264 |
a reference id to the customer profile
265 |
_original
266 |
the original response from the payment gateway
267 | 268 | 269 | ### BaseGateway.getCustomerProfile(profileId) 270 | 271 | get a customer profile 272 | 273 | **Parameters** 274 | 275 | **profileId**: `String`, the id related to the customer profile in the gateway system 276 | 277 | **Returns**: `Promise`, - 278 | if resolved the promise will have the same field than a Prospect instance plus a field `payment` holding a CreditCard 279 | 280 | ### BaseGateway.chargeCustomer(order, prospect, other) 281 | 282 | submit a transaction (auth+capture) from a customer profile. 283 | 284 | **Parameters** 285 | 286 | **order**: `Object`, order information 287 | 288 | **prospect**: `Prospect`, the prospect profile to charge, note that the prospect must have the field profileId set 289 | 290 | **other**: `Object`, optional info related to a specific gateway implementation 291 | 292 | **Returns**: `Promise`, cf BaseGateway#submitTransaction 293 | 294 | 295 | 296 | * * * 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 42-cent-base 2 | 3 | [![Greenkeeper badge](https://badges.greenkeeper.io/continuous-software/42-cent-base.svg)](https://greenkeeper.io/) 4 | 5 | > Node.js API abstraction for payment gateways. 6 | 7 | Used by supported gateways listed in [42-cent](https://github.com/continuous-software/42-cent). 8 | 9 | ## [Semantic Versioning](http://semver.org/) 10 | 11 | It is important to note that the BaseGateway API will follow the semantic versioning rules so that: 12 | 13 | * Any change on already defined property will define a new API and therefore will result on a different first digit of the BaseGateway version 14 | * New supported parameters/methods will define a new functionality and therefore will result in a different second digit of the BaseGateway version 15 | * Bug fixes/patches should not impact gateways implementation and will result in a different third digit of the BaseGateway version 16 | 17 | ## BaseGateway API 18 | 19 | * basegateway() 20 | * basegateway#submitTransaction() 21 | * basegateway#authorizeTransaction() 22 | * basegateway#getSettledBatchList() 23 | * basegateway#refundTransaction() 24 | * basegateway#voidTransaction() 25 | * basegateway#createSubscription() 26 | * basegateway#createCustomerProfile() 27 | * basegateway#getCustomerProfile() 28 | * basegateway#chargeCustomer() 29 | 30 | -------------------------------------------------------- 31 | 32 | #### basegateway(options) 33 | 34 | -------------------------------------------------------- 35 | 36 | #### basegateway#submitTransaction(order, creditCard, prospect[, other]) 37 | 38 | Authorize and capture a transaction. 39 | 40 | #### `parameters` 41 | 42 | `order` *(object)* 43 | * `'amount'` *(string)*: The amount of the transaction. 44 | 45 | `'creditCard'` *(object)* 46 | * `'creditCardNumber'` *(string)*: The credit card (PAN) number. 47 | * `'expirationMonth'` *(string)*: The month of credit card expiration date. 48 | * `'expirationYear'` *(string)*: The year of credit card expiration date (2 or 4 digits). 49 | * `'cvv'` *(string)*: The credit card security code (3 or 4 digits). 50 | 51 | `prospect` *(object)* 52 | 53 | * `'customerFirstName'` *(string)*: First name of the customer (also used for the billing). 54 | * `'customerLastName'` *(string)*: Last name of the customer (also used for the billing). 55 | * `'customerEmail'` *(string)*: Email of the customer. 56 | * `'billingAddress'` *(string)*: Billing address. 57 | * `'billingCity'` *(string)*: Billing City 58 | * `'billingState'` *(string)*: Billing State 59 | * `'billingZip'` *(string)*: Billing Zip 60 | * `'billingCountry'` *(string)*: Billing Country 61 | * `'shippingFirstName'` *(string)*: 62 | * `'shippingLastName'` *(string)*: 63 | * `'shippingAddress'` *(string)*: 64 | * `'shippingCity'` *(string)*: 65 | * `'shippingState'` *(string)*: 66 | * `'shippingZip'` *(string)*: 67 | * `'shippingCountry'` *(string)*: 68 | 69 | `other` *(object)* 70 | 71 | Other fields specific to a gateway SDK implementation. 72 | Refer to specific SDK for more details. 73 | 74 | #### `return value` 75 | 76 | Returns a `Promise` with the following object as a result: 77 | 78 | * `'transactionId'` *(string)*: A unique identifier of the transaction. 79 | * `'authCode'` *(string)*: Authorization code from the banking institution. 80 | * `'_original'`: The original response from the gateway. 81 | 82 | If the promise gets rejected because of the gateway, the reason will be an `object` instance of GatewayError holding the following attributes: 83 | 84 | * `'message'` *(string)*: The error message from the gateway. 85 | * `'_original'`: The original response from the specific sdk implementation. 86 | 87 | Otherwise it will be an instance of `Error`. 88 | 89 | -------------------------------------------------------- 90 | 91 | #### basegateway#authorizeTransaction(order, creditCard, prospect[, other]) 92 | 93 | Auhtorize a transaction. 94 | 95 | #### `parameters` 96 | 97 | See basegateway#submitTransaction(). 98 | 99 | -------------------------------------------------------- 100 | 101 | #### basegateway#getSettledBatchList(from, to) 102 | get a batch list of settled transaction within the window of time 103 | 104 | #### `parameters` 105 | 106 | `from` *(Date)*: Lower limit. 107 | 108 | `to` *(Date, default: `Date.now()`)*: Upper limit. 109 | 110 | #### `return value` 111 | 112 | Returns a `Promise` with the following object as a result: 113 | 114 | * `'batchList'` *(Array)*: An array of batch where a batch will have the following fields. 115 | * `'batchId'`: The id the batch is referenced by in the gateway internal system. 116 | * `'settlementDate'` *(string)*: A string for the settlement date time (UTC). 117 | * `'chargeAmount'` *(string)*: The total amount from the charged transactions during the window of time. 118 | * `'chargeCount'` *(string)*: The total count of charged transactions during the window of time. 119 | * `'refundAmount'` *(string)*: The total amount from the refunded transactions during the window of time. 120 | * `'refundCount'` *(string)*: The total count of refund transactions during the window of time. 121 | * `'voidCount'` *(string)*: The total count of voided transactions during the window of time. 122 | * `'declineCount'` *(string)*: The total count of voided transactions during the window of time. 123 | * `'errorCount'` *(string)*: The total count of voided transactions during the window of time. 124 | 125 | -------------------------------------------------------- 126 | 127 | #### basegateway#refundTransaction(transactionId, options) 128 | 129 | Refund (or credit) a settled transaction. 130 | 131 | #### `parameters` 132 | 133 | `transactionId` *(string)*: The id referencing the transaction to refund at the gateway. 134 | 135 | `options` *(object)*: Set of optional fields. 136 | 137 | * `'amount'`: The amount to be refunded (useful for partial refund). 138 | 139 | #### `return value` 140 | 141 | Returns a `Promise` with the following object as a result: 142 | 143 | * `'_original'`: The original response from the gateway. 144 | 145 | If the promise gets rejected because of the gateway, the reason will be an `object` instance of GatewayError holding the following attributes: 146 | 147 | * `'message'` *(string)*: The error message from the gateway. 148 | * `'_original'`: The original response from the specific sdk implementation. 149 | 150 | Otherwise it will be an instance of `Error`. 151 | 152 | -------------------------------------------------------- 153 | 154 | ### basegateway#voidTransaction(transactionId[, options]) 155 | 156 | Void a non-settled transaction. 157 | 158 | #### `parameters` 159 | 160 | `transactionId` *(string)*: The id referencing the transaction to void at the gateway. 161 | 162 | `options` *(object)*: Set of optional fields. 163 | 164 | #### `return value` 165 | 166 | Returns a `Promise` with the following object as a result: 167 | 168 | * `'_original'`: The original response from the gateway. 169 | 170 | If the promise gets rejected because of the gateway, the reason will be an `object` instance of GatewayError holding the following attributes: 171 | 172 | * `'message'` *(string)*: The error message from the gateway. 173 | * `'_original'`: The original response from the specific sdk implementation. 174 | 175 | Otherwise it will be an instance of `Error`. 176 | 177 | -------------------------------------------------------- 178 | 179 | #### basegateway#createSubscription(creditCard, prospect, subscriptionPlan[, other]) 180 | 181 | Create a recurring payment. 182 | 183 | #### `parameters` 184 | 185 | **creditCard**: CreditCard | Object, the credit card associated to the payment 186 | 187 | **prospect**: Prospect | Object, the prospect/customer linked to the subscription 188 | 189 | **subscriptionPlan**: SubscriptionPlan | Object, a subscription plan 190 | Note that the tuple [periodUnit , periodLength] must result in a period supported by the gateway implementation otherwise periodUnit should take priority 191 | 192 | **other**: Object, a set of options to be used by specific implementations 193 | 194 | #### `return value` 195 | 196 | Returns a `Promise` with the following object as a result: 197 | 198 | * `'subscriptionId'`: An id referencing to the subscription at the gateway. 199 | * `'_original'`: The original response from the gateway. 200 | 201 | -------------------------------------------------------- 202 | 203 | #### basegateway#createCustomerProfile(payment, billing, shipping, other) 204 | 205 | Create a customer profile in the gateway, useful to charge a customer without having to provide his payment method information again. 206 | 207 | #### `parameters` 208 | 209 | **payment**: CreditCard | Object, payment info to associate with the customer 210 | 211 | **billing**: Object, billing info to associate with the customer 212 | 213 | **shipping**: Object, shipping info to associate with the customer 214 | 215 | **other**: Object, optional info related to a specific gateway implementation 216 | 217 | #### `return value` 218 | 219 | Returns a `Promise` with the following object as a result: 220 | 221 | * `'profileId'`: A reference id to the customer profile. 222 | * `'_original'`: The original response from the payment gateway. 223 | 224 | -------------------------------------------------------- 225 | 226 | #### basegateway#getCustomerProfile(profileId) 227 | 228 | Get a previously saved customer profile. 229 | 230 | #### `parameters` 231 | 232 | `profileId` *(string)*: The id referencing to the customer profile in the gateway. 233 | 234 | #### `return value` 235 | 236 | Returns a `Promise` with the following object as a result: 237 | 238 | if resolved the promise will have the same field than a Prospect instance plus a field `payment` holding a CreditCard 239 | 240 | -------------------------------------------------------- 241 | 242 | #### basegateway#chargeCustomer(order, prospect[, other]) 243 | 244 | Submit a transaction (authorization and capture) using a customer profile. 245 | 246 | #### `parameters` 247 | 248 | **order**: Object, order information 249 | 250 | **prospect**: Prospect, the prospect profile to charge, note that the prospect must have the field profileId set 251 | 252 | **other**: Object, optional info related to a specific gateway implementation 253 | 254 | #### `return value` 255 | 256 | See basegateway#submitTransaction(). 257 | 258 | -------------------------------------------------------------------------------- /lib/BaseGateway.js: -------------------------------------------------------------------------------- 1 | var Promise = require('bluebird'); 2 | 3 | function throwNotImplemented() { 4 | return new Error('method not implemented/supported by this gateway'); 5 | } 6 | 7 | /** 8 | * Structural interface, actual implementations must implement 9 | * @param {Object} [options] - the instance will be extended with the option object 10 | * @constructor 11 | */ 12 | function BaseGateway(options) { 13 | Object.assign(this, options); 14 | } 15 | 16 | /** 17 | * authorize and capture a transaction. 18 | * 19 | * all values must be Strings 20 | * @abstract 21 | * @param {Object} order - the fields related to the order 22 | *
23 | *
amount
24 | *
the amount of the transaction
25 | *
26 | * @param {CreditCard | Object} creditCard - object holding credit card information 27 | *
28 | *
creditCardNumber
29 | *
the credit card number used for the transaction - a string with card number digit, no blank, no dash, etc
30 | *
expirationMonth - two digit string : 01 -> 12
31 | *
The month of credit card expiration date
32 | *
expirationYear
33 | *
The year of credit card expiration date - four or two digits string 2016 or 16
34 | *
cvv
35 | *
the credit card cvv number
36 | *
37 | * @param {Prospect | Object} prospect - the fields related to the prospect 38 | *
39 | *
customerFirstName
40 | *
first name of the customer (also used for the billing)
41 | *
customerLastName(also used for the billing)
42 | *
last name of the customer
43 | *
customerEmail(also used for the billing)
44 | *
email of the customer
45 | *
billingAddress
46 | *
the billing address
47 | *
billingCity
48 | *
the billing city
49 | *
billingState
50 | *
the billing state
51 | *
billingZip
52 | *
billing zip code
53 | *
billingCountry
54 | *
the billing country
55 | *
shippingFirstName
56 | *
the shipping first name
57 | *
shippingLastName
58 | *
the shipping last name
59 | *
shippingAddress
60 | *
the shipping address
61 | *
shippingCity
62 | *
the shipping city
63 | *
shippingState
64 | *
the shipping state
65 | *
shippingZip
66 | *
shipping zip code
67 | *
shippingCountry
68 | *
the shipping country
69 | * 70 | *
71 | * @param {Object} [other] - other field specific to a gateway sdk implementation. refer to specific sdk for more details 72 | * @return {Promise} - the promise will have these different fields 73 | * 74 | * if resolved 75 | *
76 | *
transactionId
77 | *
A unique identifier of the transaction.
78 | *
authCode
79 | *
authorization code from the banking institution
80 | *
_original
81 | *
the original response from the specific sdk implementation
82 | *
83 | * 84 | * if rejected 85 | * 86 | * if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 87 | *
88 | *
message
89 | *
The error message from the gateway
90 | *
_original
91 | *
The original response from the specific sdk implementation
92 | *
93 | * 94 | * otherwise it will be an instance of standard javascript Error 95 | */ 96 | BaseGateway.prototype.submitTransaction = function submitTransaction(order, creditCard, prospect, other) { 97 | return Promise.reject(throwNotImplemented()); 98 | }; 99 | 100 | /** 101 | * authorize only a transaction 102 | * same parameters than {@link BaseGateway#submitTransaction} 103 | * @abstract 104 | * @param order 105 | * @param creditCard 106 | * @param prospect 107 | * @param other 108 | */ 109 | BaseGateway.prototype.authorizeTransaction = function authorizeTransaction(order, creditCard, prospect, other) { 110 | return Promise.reject(throwNotImplemented()); 111 | }; 112 | 113 | /** 114 | * get a batch list of settled transaction within the window of time 115 | * @abstract 116 | * @param {String | Date} from - Lower limit. If String, it must be a valid date string: a string which will result in a valid Javascript Date object if passed as argument of the Date constructor 117 | * @param {String | Date} [to] - Upper limit (or today if not provided). If String, it must be a valid date string: a string which will result in a valid Javascript Date object if passed as argument of the Date constructor 118 | * @returns {Promise} - The promise should resolve with the following fields 119 | *
120 | *
batchList
121 | *
An array of batch where a batch will have the following fields 122 | *
123 | *
batchId
124 | *
The id the batch is referenced by in the gateway internal system
125 | *
settlementDate
126 | *
A string for the settlement date time (UTC)
127 | *
chargeAmount
128 | *
the total amount from the charged transactions during the window of time
129 | *
chargeCount
130 | *
the total count of charged transactions during the window of time
131 | *
refundAmount
132 | *
the total amount from the refunded transactions during the window of time
133 | *
refundCount
134 | *
the total count of refund transactions during the window of time
135 | *
voidCount
136 | *
the total count of voided transactions during the window of time
137 | *
declineCount
138 | *
the total count of voided transactions during the window of time
139 | *
errorCount
140 | *
the total count of voided transactions during the window of time
141 | *
142 | *
143 | *
144 | */ 145 | BaseGateway.prototype.getSettledBatchList = function getTransactionsList(from, to) { 146 | return Promise.reject(throwNotImplemented()); 147 | }; 148 | 149 | /** 150 | * Refund (or credit) an already settled transaction 151 | * @abstract 152 | * @param {String} transactionId - the reference to the transaction to refund (used by the underlying payment gateway system) 153 | * @param {Object} [options] - a set of optional fields 154 | *
155 | *
amount
156 | *
the amount to be refunded (partial refund)
157 | *
158 | * @returns {Promise} - the result promise will have the following fields 159 | * 160 | * if resolved 161 | *
162 | *
_original
163 | *
the original response from the payment gateway
164 | * 165 | * 166 | * if rejected 167 | * 168 | * if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 169 | *
170 | *
message
171 | *
The error message from the gateway
172 | *
_original
173 | *
The original response from the specific sdk implementation
174 | *
175 | * 176 | * otherwise it will be an instance of standard javascript Error 177 | * 178 | */ 179 | BaseGateway.prototype.refundTransaction = function refundTransaction(transactionId, options) { 180 | return Promise.reject(throwNotImplemented()); 181 | }; 182 | 183 | /** 184 | * void a (non settled) transaction 185 | * @abstract 186 | * @param {String} transactionId - the reference to the transaction to void (used by the underlying payment gateway system) 187 | * @param {Object} [options] - a set of optional fields 188 | * @returns {Promise} - the result promise will have the following fields 189 | * 190 | * if resolved 191 | *
192 | *
_original
193 | *
the original response from the payment gateway
194 | * 195 | * 196 | * if rejected 197 | * 198 | * if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 199 | *
200 | *
message
201 | *
The error message from the gateway
202 | *
_original
203 | *
The original response from the specific sdk implementation
204 | *
205 | * 206 | * otherwise it will be an instance of standard javascript Error 207 | */ 208 | BaseGateway.prototype.voidTransaction = function voidTransaction(transactionId, options) { 209 | return Promise.reject(throwNotImplemented()); 210 | }; 211 | 212 | /** 213 | * create a recurring payment 214 | * @abstract 215 | * @param {CreditCard | Object} creditCard - the credit card associated to the payment 216 | * @param {Prospect | Object} prospect - the prospect/customer linked to the subscription 217 | * @param {SubscriptionPlan | Object} subscriptionPlan - a subscription plan 218 | * Note that the tuple [periodUnit , periodLength] must result in a period supported by the gateway implementation otherwise periodUnit should take priority 219 | * @param {Object} [other] - a set of options to be used by specific implementations 220 | * @returns {Promise} - the result promise will have the following fields 221 | * 222 | * if resolved 223 | *
224 | *
subscriptionId
225 | *
a reference id to the subscription
226 | *
_original
227 | *
the original response from the payment gateway
228 | * 229 | */ 230 | BaseGateway.prototype.createSubscription = function createSubscription(creditCard, prospect, subscriptionPlan, other) { 231 | return Promise.reject(throwNotImplemented()); 232 | }; 233 | 234 | /** 235 | * create a customer profile in gateway system, useful to charge a customer without having to use his payment info 236 | * @abstract 237 | * @param {CreditCard | Object} payment - payment info to associate with the customer 238 | * @param {Object} billing - billing info to associate with the customer 239 | * @param {Object} [shipping]- shipping info to associate with the customer 240 | * @param {Object} [other] - optional info related to a specific gateway implementation 241 | * @returns {Promise} - the resolve promise will have the following fields 242 | * 243 | * if resolved 244 | *
245 | *
profileId
246 | *
a reference id to the customer profile
247 | *
_original
248 | *
the original response from the payment gateway
249 | * 250 | * 251 | */ 252 | BaseGateway.prototype.createCustomerProfile = function createCustomerProfile(payment, billing, shipping, other) { 253 | return Promise.reject(throwNotImplemented()); 254 | }; 255 | 256 | /** 257 | * get a customer profile 258 | * @abstract 259 | * @param {String} profileId - the id related to the customer profile in the gateway system 260 | * @returns {Promise } - 261 | * if resolved the promise will have the same field than a Prospect instance plus a field `payment` holding a CreditCard 262 | */ 263 | BaseGateway.prototype.getCustomerProfile = function getCustomerProfile(profileId) { 264 | return Promise.reject(throwNotImplemented()); 265 | }; 266 | 267 | /** 268 | * submit a transaction (auth+capture) from a customer profile. 269 | * @param {Object} order - order information 270 | * @param {Prospect} prospect - the prospect profile to charge, note that the prospect must have the field profileId set 271 | * @param {Object} [other] - optional info related to a specific gateway implementation 272 | * @returns {Promise} cf BaseGateway#submitTransaction 273 | */ 274 | BaseGateway.prototype.chargeCustomer = function chargeCustomer(order, prospect, other) { 275 | return Promise.reject(throwNotImplemented()); 276 | }; 277 | 278 | module.exports = BaseGateway; 279 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # Global 2 | 3 | 4 | 5 | 6 | 7 | * * * 8 | 9 | ## Class: BaseGateway 10 | Structural interface, actual implementations must implement 11 | 12 | ### BaseGateway.submitTransaction(order, creditCard, prospect, other) 13 | 14 | authorize and capture a transaction. 15 | 16 | all values must be Strings 17 | 18 | **Parameters** 19 | 20 | **order**: `Object`, the fields related to the order 21 |
22 |
amount
23 |
the amount of the transaction
24 |
25 | 26 | **creditCard**: `CreditCard | Object`, object holding credit card information 27 |
28 |
creditCardNumber
29 |
the credit card number used for the transaction - a string with card number digit, no blank, no dash, etc
30 |
expirationMonth - two digit string : 01 -> 12
31 |
The month of credit card expiration date
32 |
expirationYear
33 |
The year of credit card expiration date - four or two digits string 2016 or 16
34 |
cvv
35 |
the credit card cvv number
36 |
37 | 38 | **prospect**: `Prospect | Object`, the fields related to the prospect 39 |
40 |
customerFirstName
41 |
first name of the customer (also used for the billing)
42 |
customerLastName(also used for the billing)
43 |
last name of the customer
44 |
customerEmail(also used for the billing)
45 |
email of the customer
46 |
billingAddress
47 |
the billing address
48 |
billingCity
49 |
the billing city
50 |
billingState
51 |
the billing state
52 |
billingZip
53 |
billing zip code
54 |
billingCountry
55 |
the billing country
56 |
shippingFirstName
57 |
the shipping first name
58 |
shippingLastName
59 |
the shipping last name
60 |
shippingAddress
61 |
the shipping address
62 |
shippingCity
63 |
the shipping city
64 |
shippingState
65 |
the shipping state
66 |
shippingZip
67 |
shipping zip code
68 |
shippingCountry
69 |
the shipping country
70 | 71 |
72 | 73 | **other**: `Object`, other field specific to a gateway sdk implementation. refer to specific sdk for more details 74 | 75 | **Returns**: `Promise`, - the promise will have these different fields 76 | 77 | if resolved 78 |
79 |
transactionId
80 |
A unique identifier of the transaction.
81 |
authCode
82 |
authorization code from the banking institution
83 |
_original
84 |
the original response from the specific sdk implementation
85 |
86 | 87 | if rejected 88 | 89 | if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 90 |
91 |
message
92 |
The error message from the gateway
93 |
_original
94 |
The original response from the specific sdk implementation
95 |
96 | 97 | otherwise it will be an instance of standard javascript Error 98 | 99 | ### BaseGateway.authorizeTransaction(order, creditCard, prospect, other) 100 | 101 | authorize only a transaction 102 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 103 | 104 | **Parameters** 105 | 106 | **order**: , authorize only a transaction 107 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 108 | 109 | **creditCard**: , authorize only a transaction 110 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 111 | 112 | **prospect**: , authorize only a transaction 113 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 114 | 115 | **other**: , authorize only a transaction 116 | same parameters than [BaseGateway#submitTransaction](#basegateway#submittransaction) 117 | 118 | 119 | ### BaseGateway.getSettledBatchList(from, to) 120 | 121 | get a batch list of settled transaction within the window of time 122 | 123 | **Parameters** 124 | 125 | **from**: `String | Date`, Lower limit. If String, it must be a valid date string: a string which will result in a valid Javascript Date object if passed as argument of the Date constructor 126 | 127 | **to**: `String | Date`, Upper limit (or today if not provided). If String, it must be a valid date string: a string which will result in a valid Javascript Date object if passed as argument of the Date constructor 128 | 129 | **Returns**: `Promise`, - The promise should resolve with the following fields 130 |
131 |
batchList
132 |
An array of batch where a batch will have the following fields 133 |
134 |
batchId
135 |
The id the batch is referenced by in the gateway internal system
136 |
settlementDate
137 |
A string for the settlement date time (UTC)
138 |
chargeAmount
139 |
the total amount from the charged transactions during the window of time
140 |
chargeCount
141 |
the total count of charged transactions during the window of time
142 |
refundAmount
143 |
the total amount from the refunded transactions during the window of time
144 |
refundCount
145 |
the total count of refund transactions during the window of time
146 |
voidCount
147 |
the total count of voided transactions during the window of time
148 |
declineCount
149 |
the total count of voided transactions during the window of time
150 |
errorCount
151 |
the total count of voided transactions during the window of time
152 |
153 |
154 |
155 | 156 | ### BaseGateway.refundTransaction(transactionId, options) 157 | 158 | Refund (or credit) an already settled transaction 159 | 160 | **Parameters** 161 | 162 | **transactionId**: `String`, the reference to the transaction to refund (used by the underlying payment gateway system) 163 | 164 | **options**: `Object`, a set of optional fields 165 |
166 |
amount
167 |
the amount to be refunded (partial refund)
168 |
169 | 170 | **Returns**: `Promise`, - the result promise will have the following fields 171 | 172 | if resolved 173 |
174 |
_original
175 |
the original response from the payment gateway
176 | 177 | 178 | if rejected 179 | 180 | if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 181 |
182 |
message
183 |
The error message from the gateway
184 |
_original
185 |
The original response from the specific sdk implementation
186 |
187 | 188 | otherwise it will be an instance of standard javascript Error 189 | 190 | ### BaseGateway.voidTransaction(transactionId, options) 191 | 192 | void a (non settled) transaction 193 | 194 | **Parameters** 195 | 196 | **transactionId**: `String`, the reference to the transaction to void (used by the underlying payment gateway system) 197 | 198 | **options**: `Object`, a set of optional fields 199 | 200 | **Returns**: `Promise`, - the result promise will have the following fields 201 | 202 | if resolved 203 |
204 |
_original
205 |
the original response from the payment gateway
206 | 207 | 208 | if rejected 209 | 210 | if the rejection occurs because of the gateway the reason will be an instance of {@link GatewayError} holding the following information 211 |
212 |
message
213 |
The error message from the gateway
214 |
_original
215 |
The original response from the specific sdk implementation
216 |
217 | 218 | otherwise it will be an instance of standard javascript Error 219 | 220 | ### BaseGateway.createSubscription(creditCard, prospect, subscriptionPlan, other) 221 | 222 | create a recurring payment 223 | 224 | **Parameters** 225 | 226 | **creditCard**: `CreditCard | Object`, the credit card associated to the payment 227 | 228 | **prospect**: `Prospect | Object`, the prospect/customer linked to the subscription 229 | 230 | **subscriptionPlan**: `SubscriptionPlan | Object`, a subscription plan 231 | Note that the tuple [periodUnit , periodLength] must result in a period supported by the gateway implementation otherwise periodUnit should take priority 232 | 233 | **other**: `Object`, a set of options to be used by specific implementations 234 | 235 | **Returns**: `Promise`, - the result promise will have the following fields 236 | 237 | if resolved 238 |
239 |
subscriptionId
240 |
a reference id to the subscription
241 |
_original
242 |
the original response from the payment gateway
243 | 244 | 245 | ### BaseGateway.createCustomerProfile(payment, billing, shipping, other) 246 | 247 | create a customer profile in gateway system, useful to charge a customer without having to use his payment info 248 | 249 | **Parameters** 250 | 251 | **payment**: `CreditCard | Object`, payment info to associate with the customer 252 | 253 | **billing**: `Object`, billing info to associate with the customer 254 | 255 | **shipping**: `Object`, shipping info to associate with the customer 256 | 257 | **other**: `Object`, optional info related to a specific gateway implementation 258 | 259 | **Returns**: `Promise`, - the resolve promise will have the following fields 260 | 261 | if resolved 262 |
263 |
profileId
264 |
a reference id to the customer profile
265 |
_original
266 |
the original response from the payment gateway
267 | 268 | 269 | ### BaseGateway.getCustomerProfile(profileId) 270 | 271 | get a customer profile 272 | 273 | **Parameters** 274 | 275 | **profileId**: `String`, the id related to the customer profile in the gateway system 276 | 277 | **Returns**: `Promise`, - 278 | if resolved the promise will have the same field than a Prospect instance plus a field `payment` holding a CreditCard 279 | 280 | ### BaseGateway.chargeCustomer(order, prospect, other) 281 | 282 | submit a transaction (auth+capture) from a customer profile. 283 | 284 | **Parameters** 285 | 286 | **order**: `Object`, order information 287 | 288 | **prospect**: `Prospect`, the prospect profile to charge, note that the prospect must have the field profileId set 289 | 290 | **other**: `Object`, optional info related to a specific gateway implementation 291 | 292 | **Returns**: `Promise`, cf BaseGateway#submitTransaction 293 | 294 | 295 | 296 | * * * 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | # Global 309 | 310 | 311 | 312 | 313 | 314 | * * * 315 | 316 | ## Class: GatewayError 317 | thrown when a specific gateway return an error message 318 | 319 | 320 | 321 | * * * 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | ## license 334 | 335 | 42-cent-base module is under MIT license: 336 | 337 | > Copyright (C) 2014 Laurent Renard. 338 | > 339 | > Permission is hereby granted, free of charge, to any person 340 | > obtaining a copy of this software and associated documentation files 341 | > (the "Software"), to deal in the Software without restriction, 342 | > including without limitation the rights to use, copy, modify, merge, 343 | > publish, distribute, sublicense, and/or sell copies of the Software, 344 | > and to permit persons to whom the Software is furnished to do so, 345 | > subject to the following conditions: 346 | > 347 | > The above copyright notice and this permission notice shall be 348 | > included in all copies or substantial portions of the Software. 349 | > 350 | > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 351 | > EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 352 | > MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 353 | > NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 354 | > BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 355 | > ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 356 | > CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 357 | > SOFTWARE. 358 | # 42-cent-base 359 | 360 | Interface to implement by 42-cent adaptor. See [documentation](https://github.com/continuous-software/42-cent) for more information. --------------------------------------------------------------------------------