Welcome‎ > ‎Version 2‎ > ‎Publisher Api (Read/Write)‎ > ‎Methods‎ > ‎2 - Order‎ > ‎

Purchase

This will purchase an offer.

Method: POST /api/v2/publisher/order

This method requires three different data points.
 
ConsumerInfo - Information about the user purchasing the offer.
  BillingInfo - Information about the payment terms for the offer
  Offer Info - Which offer is being purchased, quantity, gifts, etc
  Affiliate Info - Information about affiliate tracking for purchases.

Within the data points, the required fields change depending on the type of purchase.

Scenario 1: New Consumer / Full Credit Card Details

The ConsumerInfo object needs to be fully defined so a consumer user can be created in the system.
The BillingInfo object requires all the credit card information.

Post
Required Form Name Explanation
Yes
ConsumerInfo.UserKey
The publisher assigned userKey.  Typically a Guid or email address. This is the unique representation of the consumer
Yes
ConsumerInfo.Email The email address for the consumer.
Yes
ConsumerInfo.FirstName The first name of the consumer.
Yes
ConsumerInfo.LastName The last name of the consumer.
Yes
OfferId The Id of the offer being purchased.
Yes
OfferOptionId The offer option id being purchased.
Yes
Quantity
The quantity being purchased for the consumer.  Gifts are calculated separately.  Can be zero if Gifts are defined.
Yes
SegmentKey
The segment the offer is being purchased from.
Yes
BillingInfo.NameOnCard The name listed on the CC.
Yes
BillingInfo.CardNumber The Credit Card number.
Yes
BillingInfo.CVV The 3 or 4 digit CVV listed on the back of the card.
No
BillingInfo.StoreCreditCard Whether or not the credit card should be stored at the provider. Default value is false.
Yes
BillingInfo.ExpirationMonth Integer value for the month the CC expires.
Yes
BillingInfo.ExpirationYear Integer value for the year the CC expires.
No
BillingInfo.BillingPhone The billing phone number on the CC account.
Yes
BillingInfo.BillingAddress The billing address for the CC.
No
BillingInfo.BillingAddress2 Optional second address line.
Yes
BillingInfo.BillingCity The city of the billing address.
Yes
BillingInfo.BillingState The state of the billing address.
Yes
BillingInfo.BillingZip The zip code of the billing address.
No
BillingInfo.BillingCountry The country of the billing address.
No
BillingInfo.PaymentType The payment type of the CC.  Valid types: { Unknown, HouseAccount, MasterCard, Visa, Amex, Discover, DinersClub, JCB, enRoute }
No
AffiliateInfo.AffiliateId The affiliate id for tracking affiliate referrals. If present then AffiliateInfo.CreateDateTime must be present as well.
No
AffiliateInfo.CreateDateTime The DateTime at which the user clicked the affiliate's link.
No
AffiliateInfo.AffiliateSource An optional free-text value used for affiliate reporting.

Scenario 2: Existing Consumer / Using Stored Credit Card

The Consumer - Credit Cards method will return a list of previously used credit cards if the consumer has requested they be stored at the provider.  The StoredCreditCardId can be set to use an existing card.

Although the ConsumerInfo. { Email, FirstName, LastName } fields are not required, it is suggested to supply these to update any changes from the consumer.

Post
Required Form Name Explanation
Yes
ConsumerInfo.UserKey
The publisher assigned userKey.  Typically a Guid or email address. This is the unique representation of the consumer
No
ConsumerInfo.Email Will update the email address for the consumer.
No
ConsumerInfo.FirstName Will update the first name of the consumer.
No
ConsumerInfo.LastName Will update the last name of the consumer.
Yes
OfferId The Id of the offer being purchased.
Yes
OfferOptionId The offer option id being purchased.
Yes
Quantity
The quantity being purchased for the consumer.  Gifts are calculated separately.  Can be zero if Gifts are defined.
Yes
SegmentKey
The segment the offer is being purchased from.
Yes
BillingInfo.StoredCreditCardId The credit card id returned from the Consumer - Credit Cards method.
No
AffiliateInfo.AffiliateId The affiliate id for tracking affiliate referrals. If present then AffiliateInfo.CreateDateTime must be present as well.
No
AffiliateInfo.CreateDateTime The DateTime at which the user clicked the affiliate's link.
No
AffiliateInfo.AffiliateSource An optional free-text value used for affiliate reporting.
 

Scenario 3: New Consumer / Full Credit Card Details / Gifting (Buy for a friend)

The ConsumerInfo object needs to be fully defined so a consumer user can be created in the system.
The BillingInfo object requires all the credit card information.
The Gift collection should be populated

Post
Required Form Name Explanation
Yes
ConsumerInfo.UserKey
The publisher assigned userKey.  Typically a Guid or email address. This is the unique representation of the consumer
Yes
ConsumerInfo.Email The email address for the consumer.
Yes
ConsumerInfo.FirstName The first name of the consumer.
Yes
ConsumerInfo.LastName The last name of the consumer.
Yes
OfferId The Id of the offer being purchased.
Yes
OfferOptionId The offer option id being purchased.
Yes
Quantity
The quantity being purchased for the consumer.  Gifts are calculated separately.  Can be zero if Gifts are defined.
Yes
SegmentKey
The segment the offer is being purchased from.
Yes
BillingInfo.NameOnCard The name listed on the CC.
Yes
BillingInfo.CardNumber The Credit Card number.
Yes
BillingInfo.CVV The 3 or 4 digit CVV listed on the back of the card.
No
BillingInfo.StoreCreditCard Whether or not the credit card should be stored at the provider. Default value is false.
Yes
BillingInfo.ExpirationMonth Integer value for the month the CC expires.
Yes
BillingInfo.ExpirationYear Integer value for the year the CC expires.
No
BillingInfo.BillingPhone The billing phone number on the CC account.
Yes
BillingInfo.BillingAddress The billing address for the CC.
No
BillingInfo.BillingAddress2 Optional second address line.
Yes
BillingInfo.BillingCity The city of the billing address.
Yes
BillingInfo.BillingState The state of the billing address.
Yes
BillingInfo.BillingZip The zip code of the billing address.
No
BillingInfo.BillingCountry The country of the billing address.
No
BillingInfo.PaymentType The payment type of the CC.  The system will try to infer the CC type if not supplied.  Valid types: { Unknown, HouseAccount, MasterCard, Visa, Amex, Discover, DinersClub, JCB, enRoute }
No
Gifts[0...N] A list of Gift objects.
No
AffiliateInfo.AffiliateId The affiliate id for tracking affiliate referrals. If present then AffiliateInfo.CreateDateTime must be present as well.
No
AffiliateInfo.CreateDateTime The DateTime at which the user clicked the affiliate's link.
No
AffiliateInfo.AffiliateSource An optional free-text value used for affiliate reporting.

Gift Model

These are the fields for a gift model.  The form post follows this format.

Gifts[0].FirstName=Sylvester
Gifts[0].LastName=Martin
Gifts[0].FromName=
Gifts[0].Quantity=1

Required Form Name Explanation
Yes
FirstName
The first name of the gift recipient.  Can be a full name.
No
LastName
Optional last name of the gift recipient.
Yes
EmailAddress
The email address of the recipient.  The voucher information will be sent here.
Yes
Quantity
The quantity of gifts for this recipient.  Must be between 1 and 999.
Yes
FromName The name the gift is from.
No
Message An optional message to be placed for the gift.


Returns:
  orderId - The orderId if the order was successful.  Will be not be present if the order was not successful.
  success - A bool value whether the order was successful.
  errors - A list of errors that contain additional information about why the order failed.

Sample Request:
POST  /api/v2/publisher/order/purchase HTTP/1.1

OfferId=1325&OfferOptionId=600&Quantity=1&SegmentKey=vegas&ConsumerInfo.Email=&ConsumerInfo.UserKey=5509477&ConsumerInfo.FirstName=&ConsumerInfo.LastName=&BillingInfo.NameOnCard=Sylvester+Martin&BillingInfo.CardNumber=4111111111111111&BillingInfo.PaymentType=Visa&BillingInfo.CVV=666&BillingInfo.ExpirationMonth=3&BillingInfo.ExpirationYear=2014&BillingInfo.BillingPhone=1112223333&BillingInfo.BillingAddress=123+Sesame+St.&BillingInfo.BillingAddress2=&BillingInfo.BillingCity=Groverland&BillingInfo.BillingState=NY&BillingInfo.BillingZip=12345&BillingInfo.BillingCountry=&BillingInfo.StoreCreditCard=False&BillingInfo.StoredCreditCardId=

Authorization: OAuth oauth_signature="%2bpLcmXC4fxIoxi%2f6xM9FHqn1sro%3d", oauth_nonce="2348333", oauth_timestamp="1307040525", oauth_consumer_key="43c5c674-620c-4f2b-bdcf-3082c99e8186", oauth_signature_method="HMAC-SHA1", oauth_version="1.0"

Host: api.groupcommerce.local

Sample XML Response:
<purchaseResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <errors>
        <error>
            <key>BillingInfo.CardNumber</key>
            <value>Please enter a valid credit card number</value>
        </error>
        <error>
            <key>BillingInfo.CVV</key>
            <value>Your card's security code is required </value>
        </error>
    </errors>
    <success>false</success>
</purchaseResult>


Sample JSON Response:
{
    "errors":[],
    "orderId":8129,
    "success":true
}

Comments