Action (Before)

This action occurs before a certain interaction is performed on a payment. It runs before both the embedded.commerce.payments.performPaymentInteraction and the embedded.commerce.payments.action.after actions. The main difference between these three actions is the methods each has access to and whether they occur before or after the payment interaction. The relevant payment interactions that this action responds to are: 

  • AuthAndCapture
  • Authorize
  • Capture
  • Create
  • Credit
  • Decline
  • RequestCheck
  • Rollback
  • Void
Action TypeEmbedded
Full Action IDembedded.commerce.payments.action.before
Runs multiple custom functions?Yes

JavaScript File Structure

Action files share the following basic structure:

module.exports = function(context, callback) {
   // Your custom code here
   callback();
};

When you code the custom function for an action, you have access to two arguments:

callback—This argument follows the established JavaScript callback pattern: it takes an error as the first argument (or null if there is no error) and a result as the second argument (if required).

context—This argument provides the function access to relevant objects and methods that interface with Kibo.

Context: Payment

The following methods and objects are available to this action through the use of the context argument.

Microservice Operation
This action corresponds to the microservice that performs payment actions.

Get Methods

Exec Methods

Context Objects Available to All Actions

Get

get.payment

Returns the payment transaction.

ParametersTypeDescription
N/AN/AN/A

Example:

context.get.payment();

Response:

{
   "amountCollected": "decimal",
   "amountCredited": "decimal",
   "amountRequested": "decimal",
   "auditInfo": {
      "createBy": "string",
      "createDate": "DateTime",
      "updateBy": "string",
      "updateDate": "DateTime"
   },
   "availableActions": "string",
   "billingInfo": {
      "auditInfo": {
         "createBy": "string",
         "createDate": "DateTime",
         "updateBy": "string",
         "updateDate": "DateTime"
      },
      "billingContact": {
         "address": {
            "address1": "string",
            "address2": "string",
            "address3": "string",
            "address4": "string",
            "addressType": "string",
            "cityOrTown": "string",
            "countryCode": "string",
            "isValidated": "bool",
            "postalOrZipCode": "string",
            "stateOrProvince": "string"
         },
         "companyOrOrganization": "string",
         "email": "string",
         "firstName": "string",
         "id": "int",
         "lastNameOrSurname": "string",
         "middleNameOrInitial": "string",
         "phoneNumbers": {
            "home": "string",
            "mobile": "string",
            "work": "string"
         }
      },
      "card": {
         "cardNumberPartOrMask": "string",
         "expireMonth": "short",
         "expireYear": "short",
         "isCardInfoSaved": "bool",
         "isUsedRecurring": "bool",
         "nameOnCard": "string",
         "paymentOrCardType": "string",
         "paymentServiceCardId": "string"
      },
      "isSameBillingShippingAddress": "bool",
      "paymentType": "string",
      "storeCreditCode": "string"
   },
   "changeMessages": [
      {
         "amount": "decimal",
         "appId": "string",
         "appKey": "string",
         "appName": "string",
         "correlationId": "string",
         "createDate": "DateTime",
         "id": "string",
         "identifier": "string",
         "message": "string",
         "metadata": "object",
         "newValue": "string",
         "oldValue": "string",
         "subject": "string",
         "subjectType": "string",
         "success": "bool",
         "userFirstName": "string",
         "userId": "string",
         "userLastName": "string",
         "userScopeType": "string",
         "verb": "string"
      }
   ],
   "id": "string",
   "interactions": [
      {
         "amount": "decimal",
         "auditInfo": {
            "createBy": "string",
            "createDate": "DateTime",
            "updateBy": "string",
            "updateDate": "DateTime"
         },
         "checkNumber": "string",
         "currencyCode": "string",
         "gatewayAuthCode": "string",
         "gatewayAVSCodes": "string",
         "gatewayCVV2Codes": "string",
         "gatewayInteractionId": "int",
         "gatewayResponseCode": "string",
         "gatewayResponseText": "string",
         "gatewayTransactionId": "string",
         "id": "string",
         "interactionDate": "DateTime",
         "interactionType": "string",
         "isManual": "bool",
         "isRecurring": "bool",
         "note": "string",
         "orderId": "string",
         "paymentEntryStatus": "string",
         "paymentId": "string",
         "paymentTransactionInteractionIdReference": "int",
         "status": "string"
      }
   ],
   "isRecurring": "bool",
   "orderId": "string",
   "paymentServiceTransactionId": "string",
   "paymentType": "string",
   "status": "string"
}

For information about the properties in the response, refer to the REST API Help.

get.paymentAction

Returns a primitive list of strings naming the available payment actions.

ParametersTypeDescription
N/AN/AN/A

Example:

context.get.paymentAction();

Response:

[
   {}
]

Exec

exec.setActionAmount

Set a requested payment amount for the transaction.

ParametersTypeDescription
amountnumberThe requested amount you want to set for the payment.

Example:

context.exec.setActionAmount(37.00);

Response:

[
   {}
]

Returns a payment action. For information about the properties in the response, refer to the REST API Help.

exec.setPaymentData

Set custom payment data (usually billing information associated with a billing service that might only send an auth token).

ParametersTypeDescription
keystringKey used to identify the payment data.
valueobjectCustom data originated by the billing service.

Example:

context.exec.setPaymentData("paypal",existingPayment.billingInfo.data.paypal);

Response:

{
   "amountCollected": "decimal",
   "amountCredited": "decimal",
   "amountRequested": "decimal",
   "auditInfo": {
      "createBy": "string",
      "createDate": "DateTime",
      "updateBy": "string",
      "updateDate": "DateTime"
   },
   "availableActions": "string",
   "billingInfo": {
      "auditInfo": {
         "createBy": "string",
         "createDate": "DateTime",
         "updateBy": "string",
         "updateDate": "DateTime"
      },
      "billingContact": {
         "address": {
            "address1": "string",
            "address2": "string",
            "address3": "string",
            "address4": "string",
            "addressType": "string",
            "cityOrTown": "string",
            "countryCode": "string",
            "isValidated": "bool",
            "postalOrZipCode": "string",
            "stateOrProvince": "string"
         },
         "companyOrOrganization": "string",
         "email": "string",
         "firstName": "string",
         "id": "int",
         "lastNameOrSurname": "string",
         "middleNameOrInitial": "string",
         "phoneNumbers": {
            "home": "string",
            "mobile": "string",
            "work": "string"
         }
      },
      "card": {
         "cardNumberPartOrMask": "string",
         "expireMonth": "short",
         "expireYear": "short",
         "isCardInfoSaved": "bool",
         "isUsedRecurring": "bool",
         "nameOnCard": "string",
         "paymentOrCardType": "string",
         "paymentServiceCardId": "string"
      },
      "isSameBillingShippingAddress": "bool",
      "paymentType": "string",
      "storeCreditCode": "string"
   },
   "changeMessages": [
      {
         "amount": "decimal",
         "appId": "string",
         "appKey": "string",
         "appName": "string",
         "correlationId": "string",
         "createDate": "DateTime",
         "id": "string",
         "identifier": "string",
         "message": "string",
         "metadata": "object",
         "newValue": "string",
         "oldValue": "string",
         "subject": "string",
         "subjectType": "string",
         "success": "bool",
         "userFirstName": "string",
         "userId": "string",
         "userLastName": "string",
         "userScopeType": "string",
         "verb": "string"
      }
   ],
   "id": "string",
   "interactions": [
      {
         "amount": "decimal",
         "auditInfo": {
            "createBy": "string",
            "createDate": "DateTime",
            "updateBy": "string",
            "updateDate": "DateTime"
         },
         "checkNumber": "string",
         "currencyCode": "string",
         "gatewayAuthCode": "string",
         "gatewayAVSCodes": "string",
         "gatewayCVV2Codes": "string",
         "gatewayInteractionId": "int",
         "gatewayResponseCode": "string",
         "gatewayResponseText": "string",
         "gatewayTransactionId": "string",
         "id": "string",
         "interactionDate": "DateTime",
         "interactionType": "string",
         "isManual": "bool",
         "isRecurring": "bool",
         "note": "string",
         "orderId": "string",
         "paymentEntryStatus": "string",
         "paymentId": "string",
         "paymentTransactionInteractionIdReference": "int",
         "status": "string"
      }
   ],
   "isRecurring": "bool",
   "orderId": "string",
   "paymentServiceTransactionId": "string",
   "paymentType": "string",
   "status": "string"
}

For information about the properties in the response, refer to the REST API Help.

exec.removePaymentData

Remove custom payment data from a payment.

ParametersTypeDescription
keystringKey used to identify the payment data.

Example:

context.exec.removePaymentData("paypal");

Response:

{
   "amountCollected": "decimal",
   "amountCredited": "decimal",
   "amountRequested": "decimal",
   "auditInfo": {
      "createBy": "string",
      "createDate": "DateTime",
      "updateBy": "string",
      "updateDate": "DateTime"
   },
   "availableActions": "string",
   "billingInfo": {
      "auditInfo": {
         "createBy": "string",
         "createDate": "DateTime",
         "updateBy": "string",
         "updateDate": "DateTime"
      },
      "billingContact": {
         "address": {
            "address1": "string",
            "address2": "string",
            "address3": "string",
            "address4": "string",
            "addressType": "string",
            "cityOrTown": "string",
            "countryCode": "string",
            "isValidated": "bool",
            "postalOrZipCode": "string",
            "stateOrProvince": "string"
         },
         "companyOrOrganization": "string",
         "email": "string",
         "firstName": "string",
         "id": "int",
         "lastNameOrSurname": "string",
         "middleNameOrInitial": "string",
         "phoneNumbers": {
            "home": "string",
            "mobile": "string",
            "work": "string"
         }
      },
      "card": {
         "cardNumberPartOrMask": "string",
         "expireMonth": "short",
         "expireYear": "short",
         "isCardInfoSaved": "bool",
         "isUsedRecurring": "bool",
         "nameOnCard": "string",
         "paymentOrCardType": "string",
         "paymentServiceCardId": "string"
      },
      "isSameBillingShippingAddress": "bool",
      "paymentType": "string",
      "storeCreditCode": "string"
   },
   "changeMessages": [
      {
         "amount": "decimal",
         "appId": "string",
         "appKey": "string",
         "appName": "string",
         "correlationId": "string",
         "createDate": "DateTime",
         "id": "string",
         "identifier": "string",
         "message": "string",
         "metadata": "object",
         "newValue": "string",
         "oldValue": "string",
         "subject": "string",
         "subjectType": "string",
         "success": "bool",
         "userFirstName": "string",
         "userId": "string",
         "userLastName": "string",
         "userScopeType": "string",
         "verb": "string"
      }
   ],
   "id": "string",
   "interactions": [
      {
         "amount": "decimal",
         "auditInfo": {
            "createBy": "string",
            "createDate": "DateTime",
            "updateBy": "string",
            "updateDate": "DateTime"
         },
         "checkNumber": "string",
         "currencyCode": "string",
         "gatewayAuthCode": "string",
         "gatewayAVSCodes": "string",
         "gatewayCVV2Codes": "string",
         "gatewayInteractionId": "int",
         "gatewayResponseCode": "string",
         "gatewayResponseText": "string",
         "gatewayTransactionId": "string",
         "id": "string",
         "interactionDate": "DateTime",
         "interactionType": "string",
         "isManual": "bool",
         "isRecurring": "bool",
         "note": "string",
         "orderId": "string",
         "paymentEntryStatus": "string",
         "paymentId": "string",
         "paymentTransactionInteractionIdReference": "int",
         "status": "string"
      }
   ],
   "isRecurring": "bool",
   "orderId": "string",
   "paymentServiceTransactionId": "string",
   "paymentType": "string",
   "status": "string"
}

For information about the properties in the response, refer to the REST API Help.

exec.setActionPreAuthFlag

Enable pre-authorization for an order payment. Pre-authorization authorizes a small dollar amount (e.g. $1) in order to check the authorization response for errors (incorrect CVV, etc.) before the full amount is authorized. This feature provides a cleaner method for authorizing large-value orders.

To enable this feature, contact your Kibo representative. At this moment, Cybersource is the only payment gateway that supports this feature.

ParametersTypeDescription
isPreAuthBooleanEnables pre-authorization when true.

Example:

context.exec.setActionPreAuthFlag(true);

Response:

{
   "amountCollected": "decimal",
   "amountCredited": "decimal",
   "amountRequested": "decimal",
   "auditInfo": {
      "createBy": "string",
      "createDate": "DateTime",
      "updateBy": "string",
      "updateDate": "DateTime"
   },
   "availableActions": "string",
   "billingInfo": {
      "auditInfo": {
         "createBy": "string",
         "createDate": "DateTime",
         "updateBy": "string",
         "updateDate": "DateTime"
      },
      "billingContact": {
         "address": {
            "address1": "string",
            "address2": "string",
            "address3": "string",
            "address4": "string",
            "addressType": "string",
            "cityOrTown": "string",
            "countryCode": "string",
            "isValidated": "bool",
            "postalOrZipCode": "string",
            "stateOrProvince": "string"
         },
         "companyOrOrganization": "string",
         "email": "string",
         "firstName": "string",
         "id": "int",
         "lastNameOrSurname": "string",
         "middleNameOrInitial": "string",
         "phoneNumbers": {
            "home": "string",
            "mobile": "string",
            "work": "string"
         }
      },
      "card": {
         "cardNumberPartOrMask": "string",
         "expireMonth": "short",
         "expireYear": "short",
         "isCardInfoSaved": "bool",
         "isUsedRecurring": "bool",
         "nameOnCard": "string",
         "paymentOrCardType": "string",
         "paymentServiceCardId": "string"
      },
      "isSameBillingShippingAddress": "bool",
      "paymentType": "string",
      "storeCreditCode": "string"
   },
   "changeMessages": [
      {
         "amount": "decimal",
         "appId": "string",
         "appKey": "string",
         "appName": "string",
         "correlationId": "string",
         "createDate": "DateTime",
         "id": "string",
         "identifier": "string",
         "message": "string",
         "metadata": "object",
         "newValue": "string",
         "oldValue": "string",
         "subject": "string",
         "subjectType": "string",
         "success": "bool",
         "userFirstName": "string",
         "userId": "string",
         "userLastName": "string",
         "userScopeType": "string",
         "verb": "string"
      }
   ],
   "id": "string",
   "interactions": [
      {
         "amount": "decimal",
         "auditInfo": {
            "createBy": "string",
            "createDate": "DateTime",
            "updateBy": "string",
            "updateDate": "DateTime"
         },
         "checkNumber": "string",
         "currencyCode": "string",
         "gatewayAuthCode": "string",
         "gatewayAVSCodes": "string",
         "gatewayCVV2Codes": "string",
         "gatewayInteractionId": "int",
         "gatewayResponseCode": "string",
         "gatewayResponseText": "string",
         "gatewayTransactionId": "string",
         "id": "string",
         "interactionDate": "DateTime",
         "interactionType": "string",
         "isManual": "bool",
         "isRecurring": "bool",
         "note": "string",
         "orderId": "string",
         "paymentEntryStatus": "string",
         "paymentId": "string",
         "paymentTransactionInteractionIdReference": "int",
         "status": "string"
      }
   ],
   "isRecurring": "bool",
   "orderId": "string",
   "paymentServiceTransactionId": "string",
   "paymentType": "string",
   "status": "string"
}

For information about the properties in the response, refer to the REST API Help.

exec.setBillingInfo

Set the billing info object for a payment.

ParametersTypeDescription
billingInfoobjectThe billingInfo object for the payment resource.

Example:

context.exec.setBillingInfo(billingInfo);

Response:

{
   "amountCollected": "decimal",
   "amountCredited": "decimal",
   "amountRequested": "decimal",
   "auditInfo": {
      "createBy": "string",
      "createDate": "DateTime",
      "updateBy": "string",
      "updateDate": "DateTime"
   },
   "availableActions": "string",
   "billingInfo": {
      "auditInfo": {
         "createBy": "string",
         "createDate": "DateTime",
         "updateBy": "string",
         "updateDate": "DateTime"
      },
      "billingContact": {
         "address": {
            "address1": "string",
            "address2": "string",
            "address3": "string",
            "address4": "string",
            "addressType": "string",
            "cityOrTown": "string",
            "countryCode": "string",
            "isValidated": "bool",
            "postalOrZipCode": "string",
            "stateOrProvince": "string"
         },
         "companyOrOrganization": "string",
         "email": "string",
         "firstName": "string",
         "id": "int",
         "lastNameOrSurname": "string",
         "middleNameOrInitial": "string",
         "phoneNumbers": {
            "home": "string",
            "mobile": "string",
            "work": "string"
         }
      },
      "card": {
         "cardNumberPartOrMask": "string",
         "expireMonth": "short",
         "expireYear": "short",
         "isCardInfoSaved": "bool",
         "isUsedRecurring": "bool",
         "nameOnCard": "string",
         "paymentOrCardType": "string",
         "paymentServiceCardId": "string"
      },
      "isSameBillingShippingAddress": "bool",
      "paymentType": "string",
      "storeCreditCode": "string"
   },
   "changeMessages": [
      {
         "amount": "decimal",
         "appId": "string",
         "appKey": "string",
         "appName": "string",
         "correlationId": "string",
         "createDate": "DateTime",
         "id": "string",
         "identifier": "string",
         "message": "string",
         "metadata": "object",
         "newValue": "string",
         "oldValue": "string",
         "subject": "string",
         "subjectType": "string",
         "success": "bool",
         "userFirstName": "string",
         "userId": "string",
         "userLastName": "string",
         "userScopeType": "string",
         "verb": "string"
      }
   ],
   "id": "string",
   "interactions": [
      {
         "amount": "decimal",
         "auditInfo": {
            "createBy": "string",
            "createDate": "DateTime",
            "updateBy": "string",
            "updateDate": "DateTime"
         },
         "checkNumber": "string",
         "currencyCode": "string",
         "gatewayAuthCode": "string",
         "gatewayAVSCodes": "string",
         "gatewayCVV2Codes": "string",
         "gatewayInteractionId": "int",
         "gatewayResponseCode": "string",
         "gatewayResponseText": "string",
         "gatewayTransactionId": "string",
         "id": "string",
         "interactionDate": "DateTime",
         "interactionType": "string",
         "isManual": "bool",
         "isRecurring": "bool",
         "note": "string",
         "orderId": "string",
         "paymentEntryStatus": "string",
         "paymentId": "string",
         "paymentTransactionInteractionIdReference": "int",
         "status": "string"
      }
   ],
   "isRecurring": "bool",
   "orderId": "string",
   "paymentServiceTransactionId": "string",
   "paymentType": "string",
   "status": "string"
}

For information about the properties in the response, refer to the REST API Help.

Context Objects Available to All Actions

apiContext

Accesses tenant information.

PropertiesTypeDescription
baseUrlstringThe base URL for the site.
basePciUrlstringThe base PCI URL for the site.
tenantPodstringThe name of the tenant pod in which the tenant resides.
appClaimsstringThe application claims token.
appKeystringThe application key.
tenantIdintegerUnique identifier for the tenant.
siteIdintegerUnique identifier for the site. This ID is used at all levels of a store, catalog, and tenant to associate objects to a site.
masterCatalogIdintegerUnique identifier for the master catalog.
catalogIdintegerThe unique identifier for the product catalog. Catalogs are part of a master catalog.
currencyCodestringThe default three-letter ISO currency code for monetary amounts.
previewDatedate/timeThe date and time that the content is being viewed. This might be a future date if the content is previewed with an active date range set in the future.
localeCodestringThe locale code per the country code provided. This code determines the localized content to use and display.
correlationIdstringThe unique identifier of the API request associated with the event action, which might contain multiple actions.
isAuthorizedAsAdminBooleanIndicates whether the Dev Account user is authorized as an admin.
userClaimsstringThe user claims token.

Example:

context.apiContext.baseUrl;

configuration

Receives a JSON response that contains information about the configuration data set in the Action Management JSON editor.

PropertiesTypeDescription
VariesobjectCustom fields and values that you can set in the Action Management JSON Editor.

Example:

context.configuration.customData;