API Transaction

The transaction API enables managers to create, by way of a RESTful API, bookings for schedules.

API Definition

TYPE: RESTful & CORS enabled
URL: https://www.shopperee.com/apidmp/transaction
Verb: PUT
Data Format: JSON
Data Input Specification: { 'Basic Parameters …', "payload": Data Set }
Data Success Specification: { "success": true, "transaction_reference_id": unique identifier for transaction, "booking_customer_count": Count of Booked Customers }
Data Error Specification: { "success": false, "error": Error Message }

Basic Parameters

Use these parameters to log in.

Parameter Type Mandatory Default Description
api_username String Y Get the username directly from the manager.
api_password String Y Get the password directly from the manager.

Sample Transactions

Sample Code At jsfiddle

Method URL
Simple Transaction - Default & Override Pricing & Bulk Purchase http://jsfiddle.net/shopperee/a0k7rusu/
Simple Transaction - Package Pricing & Bulk Purchase http://jsfiddle.net/shopperee/an4934hh/
Multi Customer Transaction http://jsfiddle.net/shopperee/dm1fevbj/

Implementation Notes

Security

While the sample code is in Javascript, use the API in server or backend calls and not client or front end calls. This will dramatically improve security for your application and your customer (the Shopperee merchant).

Note that Shopperee terms & conditions state that exposing data and or parameters in the client side will result in barred API use.

Ticket Sales

Capacity

Ensure that a schedule's capacity is checked (via api-services) before transactions are committed. Any breach of capacity automatically results in transaction failure.

Package Pricing

Package pricing may be used to consolidate the sell price of a group of tickets, enabling client platforms to freely auction or nominate pricing which is free of algorithmic or rule based frameworks.

Override Sell Price

Any ticket's price may be overridden by specifying the appropriate parameter. See the ticket set object for more information.

Bulk Purchases

A bulk (or group) purchase is a sale which reduces the data demand of client platforms. In such cases, only the billing customer's details are collected. However, the set of tickets which comprises the sale will still be mandatory.

General Booking

Receipting

A receipt is emailed to the billing customer if the receipted flag is set at N and payment was successful.

Invoicing

An invoice is emailed to the billing customer if payment was not successful.

Base Data Set

The following table describes the base data set required in the payload object. Ticket set and customer objects are included in the base data set where necessary.

Data Element Mandatory Default Description
schedule_id Y Unique identifier from schedule obtained from API Services.
platform Y Identifier of the platform accessing the API.
bulk_purchase_yn N N Set to Y when only billing customer data is available - no booking customer data will be required.
payment_success_yn N N Set to Y when payment is successfully collected. This ensures Shopperee does not invoice the billing customer.
payment_type payment_success_yn=Y CREDIT CARD, PAYPAL, CASH, CHEQUE, DIRECT DEPOSIT or OTHER
payment_reference N NO REF Specify an invoice or receipt reference for successful payments.
receipted_yn N N Set to Y when a payment is receipted. This ensures Shopperee does not receipt the billing customer.
package_sell_price_yn N N Use to specify a package or whole price rather than using default Shopperee pricing.
package_description package_sell_price_yn=Y NO DESC The description or name of the packaged price.
package_sell_price package_sell_price_yn=Y The package price.
ticket_set Y for TICKET Priced Schedules An Array of JSON Ticket Objects
billing_customer Y A JSON Customer Object
booking_customers bulk_purchase_yn=N An Array of JSON Customer Objects

Ticket Set Object

Data Element Mandatory Default Description
ticket_type Y ADULT, CHILD, TODDLER, INFANT, SENIOR, STUDENT, FAMILY, COMBO1, COMBO2
ticket_count Y The number of tickets bought.
override_sell_price N The overridden sell price for this ticket object.

Customer Object

Data Element Mandatory Default Description
surname Y Surname of customer.
firstname Y Firstname of customer.
address N Address line 1 of customer.
suburb N Suburb of customer address.
postcode N Postcode of customer address.
state N State of customer address.
country N Country of customer address.
mobile_phone Y for billing customers Mobile phone number of customer.
email Y for billing customers Customer email address
ticket_type Y for TICKET priced schedules See ticket_type in Ticket Object.
date_of_birth Format yyyy-mm-dd
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License