42-cent-base NPM

42-cent-base

Node.js API abstraction for payment gateways.

Used by supported gateways listed in 42-cent.

Semantic Versioning

It is important to note that the BaseGateway API will follow the semantic versioning rules so that:

Any change on already defined property will define a new API and therefore will result on a different first digit of the BaseGateway version
New supported parameters/methods will define a new functionality and therefore will result in a different second digit of the BaseGateway version
Bug fixes/patches should not impact gateways implementation and will result in a different third digit of the BaseGateway version

BaseGateway API

basegateway()
basegateway#submitTransaction()
basegateway#authorizeTransaction()
basegateway#getSettledBatchList()
basegateway#refundTransaction()
basegateway#voidTransaction()
basegateway#createSubscription()
basegateway#createCustomerProfile()
basegateway#getCustomerProfile()
basegateway#chargeCustomer()

basegateway(options)

basegateway#submitTransaction(order, creditCard, prospect, other)

Authorize and capture a transaction.

`parameters`

order (object)

'amount' (string): The amount of the transaction.

'creditCard' (object)

'creditCardNumber' (string): The credit card (PAN) number.
'expirationMonth' (string): The month of credit card expiration date.
'expirationYear' (string): The year of credit card expiration date (2 or 4 digits).
'cvv' (string): The credit card security code (3 or 4 digits).

prospect (object)

'customerFirstName' (string): First name of the customer (also used for the billing).
'customerLastName' (string): Last name of the customer (also used for the billing).
'customerEmail' (string): Email of the customer.
'billingAddress' (string): Billing address.
'billingCity' (string): Billing City
'billingState' (string): Billing State
'billingZip' (string): Billing Zip
'billingCountry' (string): Billing Country
'shippingFirstName' (string):
'shippingLastName' (string):
'shippingAddress' (string):
'shippingCity' (string):
'shippingState' (string):
'shippingZip' (string):
'shippingCountry' (string):

other (object)

Other fields specific to a gateway SDK implementation.
Refer to specific SDK for more details.

`return value`

Returns a Promise with the following object as a result:

'transactionId' (string): A unique identifier of the transaction.
'authCode' (string): Authorization code from the banking institution.
'_original': The original response from the gateway.

If the promise gets rejected because of the gateway, the reason will be an object instance of GatewayError holding the following attributes:

'message' (string): The error message from the gateway.
'_original': The original response from the specific sdk implementation.

Otherwise it will be an instance of Error.

basegateway#authorizeTransaction(order, creditCard, prospect, other)

Auhtorize a transaction.

`parameters`

See basegateway#submitTransaction().

basegateway#getSettledBatchList(from, to)

get a batch list of settled transaction within the window of time

`parameters`

from (Date): Lower limit.

to (Date, default: Date.now()): Upper limit.

`return value`

Returns a Promise with the following object as a result:

'batchList' (Array): An array of batch where a batch will have the following fields.
- 'batchId': The id the batch is referenced by in the gateway internal system.
- 'settlementDate' (string): A string for the settlement date time (UTC).
- 'chargeAmount' (string): The total amount from the charged transactions during the window of time.
- 'chargeCount' (string): The total count of charged transactions during the window of time.
- 'refundAmount' (string): The total amount from the refunded transactions during the window of time.
- 'refundCount' (string): The total count of refund transactions during the window of time.
- 'voidCount' (string): The total count of voided transactions during the window of time.
- 'declineCount' (string): The total count of voided transactions during the window of time.
- 'errorCount' (string): The total count of voided transactions during the window of time.

basegateway#refundTransaction(transactionId, options)

Refund (or credit) a settled transaction.

`parameters`

transactionId (string): The id referencing the transaction to refund at the gateway.

options (object): Set of optional fields.

'amount': The amount to be refunded (useful for partial refund).

`return value`

Returns a Promise with the following object as a result:

'_original': The original response from the gateway.

If the promise gets rejected because of the gateway, the reason will be an object instance of GatewayError holding the following attributes:

'message' (string): The error message from the gateway.
'_original': The original response from the specific sdk implementation.

Otherwise it will be an instance of Error.

basegateway#voidTransaction(transactionId, options)

Void a non-settled transaction.

`parameters`

transactionId (string): The id referencing the transaction to void at the gateway.

options (object): Set of optional fields.

`return value`

Returns a Promise with the following object as a result:

'_original': The original response from the gateway.

If the promise gets rejected because of the gateway, the reason will be an object instance of GatewayError holding the following attributes:

'message' (string): The error message from the gateway.
'_original': The original response from the specific sdk implementation.

Otherwise it will be an instance of Error.

basegateway#createSubscription(creditCard, prospect, subscriptionPlan, other)

Create a recurring payment.

`parameters`

creditCard: CreditCard | Object, the credit card associated to the payment

prospect: Prospect | Object, the prospect/customer linked to the subscription

subscriptionPlan: SubscriptionPlan | Object, a subscription plan Note that the tuple periodUnit , periodLength must result in a period supported by the gateway implementation otherwise periodUnit should take priority

other: Object, a set of options to be used by specific implementations