VGC V3

Description
Request URL
Path and Query Parameters
Sample Requests and Responses
Error Codes

Description

Macy’s VGC service enables its partners to order a Gift Card for their partnership programs. The intended audience for this document are the partners of Macy's who want to order a VGC from Macy's for various partnership programs.

This is an enahancement to the Virtual Gift Card V.1 call available under Order Services. This enhancement allows user to place an order for a Virtual Gift Card.

HTTP Method and Request URL

POST

https://api.macys.com/v3/order/vgc

Path and Query Parameters

HTTP Header Parameters

Parameter	Description	Mandatory	Sample Value
x-macys-webservice-client-id	Pass the apikey as a header value which is called x-macys-webservice-client-id. The api key is the 24 character alphanumeric string assigned to your application when you registered it.Click here for a list of your API keys.	Yes	xmj9js4jkdpe1983fmwu98gh
Accept	Detemines output format. Can be application/json or application/xml.	Yes	application/json application/xml
Content-Type	Specifies the format of body sent. Can be application/json or application/xml.	Yes	application/json application/xml

Request Body Parameters

Parameter	Description	Mandatory	Sample Value
transactionId	Transaction Number	Yes	2778859t27
customerEmail	Customer Email	Yes	daniel.smith@macys.com
upcNumber	UPC Number of the Gift Card (This will always be 478000208694)	Yes	478000208694
giftAmount	Gift Amount	Yes	5
giftMessage	Gift Message	Yes	Happy Birthday!
giftTo	Gift To	Yes	Ms. Smith
giftFrom	Gift From	Yes	Mr. Smith
payment	Heading for Payment Fields	Yes	N/A
creditCard	Heading for Creditcard Fields	Yes	N/A
cardNumber	Card Number	Yes	4012888888881881
typeCode	Type Code	Yes	v
expirationMonth	Expiration Month	No, required if expirationYear provided	3
expirationYear	Expiration Year	No, required if expirationMonth provided	2012
verificationNumber	Verification Number	Yes	111
billingAddress	Heading for Address Details Fields	Yes	N/A
firstName	First Name	Yes	Daniel
lastName	Last Name	Yes	Smith
phoneNumber	Phone Number	Yes	415-555-5555
emailAddress	Email Address	Yes	daniel.smith@macys.com
addressDetails	Heading for Address Details Fields	Yes	N/A
addressLine1	Address Line 1	Yes	685 market st
city	City	Yes	San Francisco
stateCode	State Code	Yes	CA
countryCode	Country Code	Yes	USA
postalCode	Postal Code	Yes	94103

Response Fields

Field	Description	Mandatory	Sample Value
orderStatus		mandatory	RCMPL, RPEND, BCMPL, BPEND
transactionId	Initially supplied to Macys by Shopcick	mandatory
orderNumber	Macys(SDP) generated order number	mandatory
reservationId	Macys generated id associated with Order number	mandatory
paymentStatus		mandatory	ACCEPTED, REJECTED
amountCharged		mandatory
taxes		mandatory

Sample Requests and Responses

Sample Request

Request URL:

POST

https://api.macys.com/v3/vgc/order

HTTP Header:

x-macys-webservice-client-id: xmj9js4jkdpe1983fmwu98gh

Accept: application/json

Content-Type: application/json

Sample Request Body

{
   "transactionId":"2778859227",
   "orderInfo":[
      {
         "customerEmail":"daniel.smith@macys.com",
         "upcNumber":"478000208694",
         "giftAmount":200,
         "giftMessage":"Happy Birthday!",
         "giftTo":"Ms. Smith",
         "giftFrom":"Mr. Smith"
      }
   ],
   "payment":{
      "creditCard":{
         "cardNumber":4012888888881881,
         "typeCode":"V",
         "expirationMonth":10,
         "expirationYear":2014,
         "verificationNumber":111
      },
      "billingAddress":{
         "firstName":"Daniel",
         "lastName":"Smith",
         "phoneNumber":"4155555555",
         "emailAddress":"daniel.smith@macys.com",
         "addressDetails":{
            "addressLine1":"685 market st",
            "city":"San Francisco",
            "stateCode":"CA",
            "countryCode":"USA",
            "postalCode":"94103"
         }
      }
   }
}

Sample Response

{"string": "
Order Status : RCMPL
TransactionId: vgc2778859t27
orderNumber:  abc939494969trer 
reservationId: 492919020
paymentStatus: ACCEPTED
amountCharged: 200.0
taxes: 0.0"}

Error Codes

Call Specific Error Codes:

"giftMessage":["test","test1","test2"],

HTTP Error code	Error Code Reason	Error Example
400	Invalid data	CS_INVALID_FNAME_MAXLENGTH_BILLING_ADDR
		CS_INVALID_LNAME_MAXLENGTH_BILLING_ADDR
		CS_INVALID_ADDRESSLINE1_MAX_LENGTH_BILLING_ADDR
		CS_INVALID_ZIPCODE_BILLING_ADDR
		CS_INVALID_EXPIRATION_DATE
		CS_MISMATCH_CC_TYPE_AND_CODE
		CS_PYMNT_INVALID_CC
		CS_INVALID_UPC
		CS_SHIPPING_ADDRESS_INVALID
		CS_GIFT_MESSAGE1_LEN_EXCEEDS
		CS_GIFT_MESSAGE2_LEN_EXCEEDS
		CS_GIFT_SENDER_NAME_LEN_EXCEEDS
		CS_INVALID_TRANSACTION_ID
		CS_INVALID_CUSTOMER_EMAIL
		CS_ORDER_NOT_VIRTUAL
		CS_GREETING_MESSAGE_EXCEEDS_LIMIT
		CS_INVALID_ORDER
		CS_INVALID_AMOUNT
		CS_INVALID_MNAME_MAXLENGTH_BILLING_ADDR
		CS_INVALID_PAYMENT_DETAILS
		CS_GREETING_MESSAGE_PROFANITY_FAILURE
		CS_CUSTOMER_EMAIL_PROFANITY_FAILURE
		CS_RESERVATION_ALREADY_FULFILLED
		CS_INVALID_PHONE_NUMBER_RECIPIENT
404	No data provided	CS_NO_TRANSACTION_ID
		CS_EMPTY_LNAME_BILLING_ADDR
		CS_EMPTY_ADDR1_BILLING_ADDR
		CS_BILLING_ADDR_MISSING_5DIG_ZIP
		CS_CVV2_MISSING
		CS_EXPIRATION_DATE_MISSING
		CS_EMPTY_ZIPCODE_SHIPPING_ADDR
		CS_EMPTY_FNAME_SHIPPING_ADDR
		CS_EMPTY_LNAME_SHIPPING_ADDR
		CS_EMPTY_ADDR1_SHIPPING_ADDR
		CS_EMPTY_STATE_SHIPPING_ADDR
		CS_EMPTY_CITY_SHIPPING_ADDR
		CS_EMPTY_LNAME_BILLING_ADDR
		CS_EMPTY_FNAME_BILLING_ADDR
		CS_EMPTY_CITY_BILLING_ADDR
		CS_EMPTY_ZIPCODE_BILLING_ADDR
		CS_EMPTY_STATE_BILLING_ADDR
		CS_SHIPPING_CONTACT_EMPTY
500	Internal error

General Error Handling Documentation:

Click Here