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. | |
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 |