The ticketing tool "amiando" is now the "XING TicketingManager". With that re-branding we switched our domain from amiando.com to xing-events.com. Please update you API implementations to use the new domain. The API will be served on amiando.com until 01.05.2017

REST API Payments

From XING Events Developer Documentation
Jump to: navigation, search

Object type: payment

This page contains information about all properties and methods regarding payments.

For an example of the calls needed to create payment to re-fill the ticketshop for known ticket buyers, see our example in the How-To section: Pre-fill the ticketshop IFrame with buyer data

Properties

Attributes: R - accessible in read requests W - accessible in write (update) requests C - accessible in create requests

Property
Type
Attributes Description
id
Integer
R--
The internal id of this object.
identifier
String
R--
The invoice number.
lastModified Date R--
When the payment was modified the last time.
creationTime
Date
R--
When the payment was created.
buyerId
Integer
R--
The internal id of the buyer associated with the payment.
eventId Integer R--
The id of the associated event.
startDate Date R--
The date the payment started.
discountCode String R--
The discount code used in the payment.
amount Money R--
The amount to be paid.
distributionChannel String R-C
The distribution channel can be set on payment creation and you can use it to differentiate between different initiations of the purchase, e.g. "Website A" and "Website B". At the revenue statistics you can see your sales grouped by this channels and the value is also available in our reports. The default is "CHANNEL_API_V1".
applicationData String R-C
The application data passed through an integrated iframe. Click here for detailed information
status String R--
Status of payment. Details
type String R--
Type of payment. Details
language Language R--
In which language did the buyer make his purchase.
numTickets Integer R--
The number of tickets associated with the payment.
userData Array of UserData R--
This array holds user data objects. User data objects hold additional values to the payment.

Objects

Objects inside an payment, nested objects can be accessed through URLs like /api/payment/<id>/<object>. For example /api/payment/345543/address/buyer.

Name
Description
tickets returns an array of Ticket ids that are associated with this payment. Example response: {"tickets":[882472,882473],"success":true}
address/buyer Detailed information about the buyer address.
address/shipment Detailed information about the shipment address.

Methods

Read

Call GET /api/payment/<id>
Description This request will return the payment object with the specified internal id. The response contains all properties marked with R.
Response {"payment":{"numTickets": ...}, "success":true}.
Errors See General Errorcodes.


Create

Call POST /api/event/<id>/payment/create
Description This request will return a new and empty payment. To add tickets to the payment, you have call the set ticket count method.
Response {"id":<id>, "success":true}.
Errors See General Errorcodes.


Set ticket count

Call POST /api/payment/<id>/setTicketCount
Parameters <ticket category id> — Amount of tickets you want to buy for this ticket category. It is possible to set the ticket count for more than one ticket category in a single request (e.g. 123456=5&123457=2 (<ticket category id>=<amount of tickets to buy>)). To retrieve the ids of the available categories use the Enumerate ticket categories function
Description This request will add the specified amount of tickets to the payment. If you wish to finish the payment call start payment.
Response {"success":true}.
Errors com.amiando.ticketing.TicketShop.DiscountCodeRequired
com.amiando.api.rest.CannotUpdateNonDraftPayment
com.amiando.ticketing.TicketShop.AmountBelowZero
com.amiando.ticketing.TicketShop.TooManyItems
com.amiando.ticketing.TicketShop.BelowMinSell
com.amiando.ticketing.TicketShop.ExceededMaxSell
See General Errorcodes.


Start payment

Call POST /api/payment/<id>/start
Description This request will return a url, that will start the payment process.
Response {"startIdentifier":"<start id>","startUrl":"<url to start the payment process>","queueIdentifier":"<queue id>","success":true}.
Errors com.amiando.api.rest.CannotUpdateNonDraftPayment

com.amiando.Payment.TicketsRequired com.amiando.ticketing.TicketShop.TooManyItems
See General Errorcodes.


Apply discount code

Call POST /api/payment/<id>/applyDiscountCode
Description This request applies a promotion code to the payment (see CodeDefinition on how to get or create promotion codes for an event).
Parameters discountCode - The discount code you want to apply (required)
Response {"success":true}.
Errors com.amiando.api.rest.CannotUpdateNonDraftPayment
com.amiando.api.rest.DiscountCodeUsedUp
com.amiando.api.rest.DataPrefilled
com.amiando.api.rest.InvalidDiscountCode

See General Errorcodes.


Finalize payment

Call POST /api/payment/<id>/finalize
Description With this call you can finalize a previously created payment by API. So if you create a payment by API, fill it with all needed data and use this call, this will result in a fully finalized payment as if the payment was finalized in the shop by the user. You can use this call for example to import known participants like speaker, special guests, etc..

Obviously this call only works for free payments/tickets - apply a 100% discount code in advance in case you want to use paid tickets.

Parameters queueIdentifier the queueIdentifier you received in the payment's start call.

acceptedTermsAndConditions must be set to "1" or "true" to signal that you are allowed to do this import in the name of the person you provided in the payment.

Response {"success":true}.
Errors com.amiando.api.rest.PaymentHasNoZeroAmount

com.amiando.api.rest.TermsAndConditionsMustBeAcceptedException
See General Errorcodes.


Enumerate payments

Call GET /api/event/<id>/payments
See Enumerate payments.


Enumerate tickets

Call GET /api/payment/<id>/tickets
Description This request will return all the specified internal ids of the payment's tickets.
Response {"tickets":[...],"success":true}.
Errors See General Errorcodes.


Enumerate products

Call GET /api/payment/<id>/products
Description This request will return all existing (ordered) products for this payment. Be careful there could also be some products belonging to the tickets you bought/ordered with this payment.
Response {"products": {...}, "success":true}.
Errors See General Errorcodes.


Payment Status

The status property indicates the current status of the payment. Possible values are:

Payment Status
Description
new
Means that the payment has been bought but the buyer did not receive the tickets yet (an example would be prepayment. The buyer gets the tickets when we receive the payment)
authorized
means that the payment was purchased but it is not yet paid (an example would be invoice. here the buyer already receives the ticket but pays at a later time)
paid
Means that the payment was purchased and paid
disbursed
Means that the payment was purchased, paid and XING Events already disbursed the money to the event host
cancelled
Means that the payment was initially bought but later cancelled


Payment Type

The type property indicates the way the payment will be / was paid. Possible values are:

Payment Type
Description
directdebit
The payment was bought using direct debit ("Lastschrift")
creditcard
The payment was bought using a credit card
invoice
The payment was paid by invoice
prepayment
The payment was bought using prepayment
paypal
The payment was paid using the PayPal service
sofort
The payment using "Sofort" (Sofortüberweisung)
free
The payment didn't need to be paid since it was free
REST API Contents
Getting Started Get your API key Overview Formats Errors
Data Types Event Participant Payment Ticket
Ticket Categories ProductDefinition Products CodeDefinition
TicketShop Addresses Ticket Types Payment Types
BankAccount UserDataDefinition UserData User
Partner ApiKey
Data Synchronization Sync Interface