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
return value
Returns a Promise with the following object as a result:
'subscriptionId': An id referencing to the subscription at the gateway.'_original': The original response from the gateway.
basegateway#createCustomerProfile(payment, billing, shipping, other)
Create a customer profile in the gateway, useful to charge a customer without having to provide his payment method information again.
parameters
payment: CreditCard | Object, payment info to associate with the customer
billing: Object, billing info to associate with the customer
shipping: Object, shipping info to associate with the customer
other: Object, optional info related to a specific gateway implementation
return value
Returns a Promise with the following object as a result:
'profileId': A reference id to the customer profile.'_original': The original response from the payment gateway.
basegateway#getCustomerProfile(profileId)
Get a previously saved customer profile.
parameters
profileId (string): The id referencing to the customer profile in the gateway.
return value
Returns a Promise with the following object as a result:
if resolved the promise will have the same field than a Prospect instance plus a field payment holding a CreditCard
basegateway#chargeCustomer(order, prospect[, other])
Submit a transaction (authorization and capture) using a customer profile.
parameters
order: Object, order information
prospect: Prospect, the prospect profile to charge, note that the prospect must have the field profileId set
other: Object, optional info related to a specific gateway implementation