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

return value

See basegateway#submitTransaction().