Request Objects
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
Object Definition
| Field | Type | Description | Required |
|---|---|---|---|
| Cart | List<CartItem Object> | The items in the cart for the current transaction | |
| Consumer | Consumer Object | Consumer object containing BillingAddress, ShippingAddress, and Account | |
| Options | Options Object | An object containing any additional option flags | |
| OrderDetails | OrderDetails Object | The object that describes basic details about the order | |
| Token | Token Object | The token details associated with this transaction |
CartItem
| Field | Type | Description | Required |
|---|---|---|---|
| Name | AN(128) | Name of Item Purchased. | |
| SKU | AN(20) | Merchant SKU of Item. | |
| Quantity | N(20) | Count of items being purchased | |
| Description | AN(256) | Brief description of the item being purchased | |
| Price | N | The price of the item |
Options
| Field | Type | Description | Required |
|---|---|---|---|
| EnableCCA | boolean | A flag that will enable or disable CCA processing for this transaction. Possible Values:
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
| Field | Type | Required | Description |
|---|---|---|---|
| OrderNumber | AN(50) | YES | This represents your Order Number or transaction identifier. |
| Amount | N(20) | YES | Unformatted total transaction amount without any decimalization. Example: $100.00 = 10000, $123.67 = 12367, $.99 = 99 |
| CurrencyCode | AN(3) | YES | 3 digit ISO 4217 value. Accepts either the Currency Number or Currency Code. Example: "840" or "USD" |
| OrderDescription | AN(256) | NO | Brief Description of Items purchased. |
| OrderChannel | AN(16) | YES | Specifies the order channel where the transaction was initiated.
|
| TransactionId | AN(50) | C | This 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
| Field | Type | Description | Required |
|---|---|---|---|
| AccountNumber | N | Consumer's Account Number. This represents the Consumer's Credit Card Number. | N |
| ExpirationMonth | N | Account/Credit Card Expiration Month in MM format. Example: January = 01 | N |
| ExpirationYear | N | Account/Credit Card Expiration Year in YYYY format. Example: 2016 | N |
| NameOnAccount | AN | Name on the Consumer's Account/Credit Card. | N |
| CardCode | N(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. | |
| CardBin | N(6) | Represents the first six numbers of the CardNumber field | |
| CardType | String | Type of cards used for purchase. Possible Values: VSA - Visa MSC - Mastercard VSD - Visa Delta/Debit (UK) VSE - Visa Electron MAE - Maestro (UK, Spain & Austria) AMX - American Express DSC - Discover DIN - Diners CBLA - Carte Blanche CB JCB - JCB ENR - EnRoute JAL - JAL CTB - Carte Bleue DNK - Dankort CSI - CartaSi EAN - Encoded Account Number UATP - UATP MAEI - Maestro (International) CB - Cartes Bancaires ELO - ELO UPI - UnionPay International EFTPOS - eftpos Australia | |
| CardLastFour | N(4) | Represents the last four numbers of the CardNumber field |
Address
| Field | Type | Required |
|---|---|---|
| FullName | AN | N |
| FirstName | AN | N |
| MiddleName | AN | N |
| LastName | AN | N |
| Address1 | AN | N |
| Address2 | AN | N |
| Address3 | AN | N |
| City | AN | N |
| State | AN | N |
| PostalCode | AN | N |
| CountryCode | AN | N |
| Phone1 | AN | N |
| Phone2 | AN | N |
Consumer
| Field | Type | Description | Required |
|---|---|---|---|
| Email1 | AN(255) | Consumer's primary E-mail Address. | N |
| Email2 | AN(255) | Consumer's alternate E-mail Address. | N |
| ShippingAddress | Address Object | Consumer's Shipping Address. | N |
| BillingAddress | Address Object | Consumer's Billing Address. | N |
| Account | Account Object | Consumer's Account Information. | N |
Token
| Field | Type | Description | Required |
|---|---|---|---|
| Token | AN(20) | If the merchant account has tokenization enabled through Cardinal or another payment platform, the token will be returned in this field | |
| CardCode | N(4) | The CVV2 on the back of the card that was the token represents. This field is required when using Processor Module. | |
| ExpirationMonth | N(2) | Account/Credit Card Expiration Month in MM format. Example: January = 01 | |
| ExpirationYear | N(4) | Account/Credit Card Expiration Year in YYYY format. Example: 2016 |