Request Objects

The request objects are structured objects that are used to pass data from you, the merchant, to Cardinal that describes a transaction or event. 

Complete Object

The complete object is used to send an authorization attempt result to Cardinal.

FieldTypeRequiredDescription
StatusstringYes

The status of the authorization attempt.

Possible Values:

  • Success
  • Failure

Order Object

An order object describes an order you'd like to process with Songbird. This request object can be passed within a request JWT as the 'Payload' field or passed within the browser via Songbird.js. 

Object Merging

If you pass a request object in both the JWT and the browser, we will merge the objects together where the browser overwrites the JWT object as it is considered the most recently captured data. For more information on object merging refer to the object merging section.

Example JSON

Full Order Object as JSON
{
  "Authorization": {
    "AuthorizeAccount": false
  },
  "Cart": [
    {
      "Name": "",
      "SKU": "",
      "Quantity": "",
      "Description": ""
    }
  ],
  "Consumer": {
    "Email1": "",
    "Email2": "",
    "ShippingAddress": {
      "FullName": "",
      "FirstName": "",
      "MiddleName": "",
      "LastName": "",
      "Address1": "",
      "Address2": "",
      "Address3": "",
      "City": "",
      "State": "",
      "PostalCode": "",
      "CountryCode": "",
      "Phone1": "",
      "Phone2": ""
    },
    "BillingAddress": {
      "FullName": "",
      "FirstName": "",
      "MiddleName": "",
      "LastName": "",
      "Address1": "",
      "Address2": "",
      "Address3": "",
      "City": "",
      "State": "",
      "PostalCode": "",
      "CountryCode": "",
      "Phone1": "",
      "Phone2": ""
    },
    "Account": {
      "AccountNumber": 0,
      "ExpirationMonth": 0,
      "ExpirationYear": 0,
      "CardCode": 0,
      "NameOnAccount": ""
    }
  },
  "Options": {
    "EnableCCA": ""
  },
  "OrderDetails": {
    "OrderNumber": "",
    "Amount": "",
    "CurrencyCode": "",
    "OrderDescription": "",
    "OrderChannel": "",
    "TransactionId": ""
  },
  "Token": {
    "Token": "",
    "CardCode": 0,
    "ExpirationMonth": 0,
    "ExpirationYear": 0
  }
} 

Object Definition

FieldTypeDescriptionRequired
CartList<CartItem Object>The items in the cart for the current transaction
ConsumerConsumer ObjectConsumer object containing BillingAddress, ShippingAddress, and Account
OptionsOptions ObjectAn object containing any additional option flags
OrderDetailsOrderDetails ObjectThe object that describes basic details about the order
TokenToken ObjectThe token details associated with this transaction

CartItem

FieldTypeDescriptionRequired
NameAN(128)Name of Item Purchased.
SKUAN(20)Merchant SKU of Item.
QuantityN(20)Count of items being purchased
DescriptionAN(256)Brief description of the item being purchased
PriceNThe price of the item

Options

FieldTypeDescriptionRequired
EnableCCAboolean

A flag that will enable or disable CCA processing for this transaction.

Possible Values:

  • true - Enables CCA for this transaction
  • false - Disables CCA for this transaction

NOTE: While this flag can be used to enable CCA, your merchant account must be configured to process CCA beforehand. This flag simply lets you control when CCA will be used to authenticate consumers.

OrderDetails

FieldTypeRequiredDescription
OrderNumberAN(50)YESThis represents your Order Number or transaction identifier.
AmountN(20)YESUnformatted total transaction amount without any decimalization.
Example: $100.00 = 10000, $123.67 = 12367, $.99 = 99
CurrencyCodeAN(3)YES3 digit ISO 4217 value. Accepts either the Currency Number or Currency Code.
Example: "840" or "USD"
OrderDescriptionAN(256)NOBrief Description of Items purchased.
OrderChannelAN(16)YESSpecifies the order channel where the transaction was initiated.
  • M – MOTO (Mail Order Telephone Order)
  • R – Retail
  • S – eCommerce
  • P – Mobile Device
  • T – Tablet
TransactionIdAN(50)CThis value is the TransactionId field from a cmpi_lookup response from Centinel. This field is only used with a hybrid integration. This field is required for a hybrid integration.

Shared Objects

The below objects are general objects and can be found on both the request and response. Their placement within the parent object may differ between request and response however.

These objects are found in both the request and response objects.

Account

FieldTypeDescriptionRequired
AccountNumberNConsumer's Account Number. This represents the Consumer's Credit Card Number.N
ExpirationMonthNAccount/Credit Card Expiration Month in MM format.
Example: January = 01
N
ExpirationYearNAccount/Credit Card Expiration Year in YYYY format.
Example: 2016
N
NameOnAccountANName on the Consumer's Account/Credit Card.N
CardCodeN(4)This is the CVV Code present on the back (or on the front in the case of AMEX) of a Consumer's Credit Card . This is required on Credit Card transactions.

Address

FieldTypeRequired
FullNameANN
FirstNameANN
MiddleNameANN
LastNameANN
Address1ANN
Address2ANN
Address3ANN
CityANN
StateANN
PostalCodeANN
CountryCodeANN
Phone1ANN
Phone2ANN

Consumer

FieldTypeDescriptionRequired
Email1AN(255)Consumer's primary E-mail Address.N
Email2AN(255)Consumer's alternate E-mail Address.N
ShippingAddressAddress ObjectConsumer's Shipping Address.N
BillingAddressAddress ObjectConsumer's Billing Address.N
AccountAccount ObjectConsumer's Account Information.N

Token

FieldTypeDescriptionRequired
TokenAN(20)If the merchant account has tokenization enabled through Cardinal or another payment platform, the token will be returned in this field
CardCodeN(4)

The CVV2 on the back of the card that was the token represents.

This field is required when using Processor Module.


ExpirationMonthN(2)Account/Credit Card Expiration Month in MM format.
Example: January = 01

ExpirationYearN(4)Account/Credit Card Expiration Year in YYYY format.
Example: 2016