Data Integration
With Data integration, you take care of presenting an interface to customers where they can select tips.
An endpoint can require a location identifier if it performs a function that can work differently from location to location. Location identifiers will be assigned to you by tippy.
v1/data/app/locations#
Before you can start making transaction, we need to map your locations with ours. This endpoint allows you to send a list of all locations that a business owns.
For each location you are sending in the payload we need a unique identifier and either address fields or geo fields. If you provide geo fields (lat, long),
the address fields are not required. If you send address fields (address, address2, city, state, zip and country), the geo fields are not required.
Many of subsequent calls to endpoints require that you provide the unique locationId (in this call known as identifier). We recommend to use the location id
from your system that you can easily reference to in the future.
Once mapping is successful the given identifier could not be used for the other location in a Tippy system. If there is a mistake in data mapping and identifier
is already mapped, you will get LocationMappingError. If such error with mapping is returned and you want to re-map identifier you should reach out to our support
to remove existing mapping.
Request body structure (TS notation)
When we receive the payload, we will attempt to match addresses on our side based on accountToken and either geo fields or address fields.
The endpoint will return the list of locations that were successfully mapped together with the count of requested mappings and count of successful mappings.
Locations must already exist in our system for mapping to work. This endpoint will not create new locations if mapping was unsuccessful.
Response body structure (TS notation)
Request example
Response example
v1/data/tips/proposals#
Start the checkout process by calling this v1/data/tips/proposals with the
service amounts for which you want to receive tip proposals.
Request body structure (TS notation)
For each service amount, you'll get back a low, medium and high
proposal. You should present these to the customer so they can pick one. It's
recommended to still leave them the option to enter a custom amount if they
don't want to use any of the predefined proposals.
Response body structure (TS notation)
For example, if two staff members were involved in a service and one provided
a service for which the customer will be charged $20 and the other provided a
service for $50, serviceAmounts equals [20,50].
Request example
Response example
v1/data/tips/fees#
Returns the fees for a given array of tip amounts. Fees are returned
when you fetch proposals, so you don't usually have to call this endpoint.
However, v1/data/tips/proposals should only be called when you have the
full list of service amounts.
If you want to display fees as the customer is entering tips or after the customer enters a custom tip, you'll have to call this endpoint to get an informative calculation.
Request body structure (TS notation)
Response body structure (TS notation)
Request example
Response example
v1/data/transaction/intent#
Once the customer has chosen their tips, call v1/data/transaction/intent to
start a tip transaction. Pass the customer info and the tip selections.
Returns a transactionId an array of chosen tips with fees, the fees summed
together and the total.
Tipping without serviceAmount is also available. What this means is that those kind of tips will
not be counted in aggregate reports. You could use this option in cases when a customer
wants to tip an assistant, etc. Sending 0 for serviceAmount will be treated as not sending it at all.
Request body structure (TS notation)
Response body structure (TS notation)
Request example
Response example
v1/data/transaction/confirm#
Once you've charged the customer, call this to let us know that the payment was successful. We'll distribute the tips among the staff members involved.
Returns a 200 response on success.
Request body structure (TS notation)
Request example
v1/data/transaction/cancel#
If a transaction you've created is unable to be completed, call
v1/data/transaction/cancel to let us know. We'll mark it as canceled on
our end.
Request body structure (TS notation)
Request example
v1/data/transaction/details#
This endpoint allows you to retrieve the details of a specific transaction based on its unique ID. You will need to provide the unique transaction ID in order to access this endpoint.
A successful call to this endpoint will return a 200 OK response with a JSON structure containing the following properties:
transactionId(string): The unique ID of the transaction.status(string): The status of the transaction.isAsync(boolean): Indicates whether the transaction is running in async mode. This will always be false for transactions with data integration.createdAt(string): The date and time when the transaction was created.customer(object): Information about the customer associated with the transaction.tipSelections(array): A list of employees and the amounts used to create the transactions.tips(array): A list of tips for each employee involved in the transaction.refunds(array): A list of refunds created for this transaction.gross(number): The gross value of the transaction.net(number): The net value of the transaction.fee(number): The fee associated with the transaction.
The status property can be one of the following values:
pending: The transaction was created and is awaiting further action.confirmed: The transaction has been successfully confirmed and processed.failed: The transaction has been marked as failed.canceled: The transaction has been canceled before it was completed.refunded: The transaction has been fully refunded.
The tips array in the response contains objects representing tips for each employee involved in the transaction. Each tip object has the following properties:
employeeId(string): The ID of the employee who received the tip.status(string): The status of the tip.level(string): The tip level, which can be one of the following values: "low," "medium," "high," or "custom."serviceAmount(number): The amount of the service for which the tip is intended.gross(number): The gross value of the tip.net(number): The net value of the tip.fee(number): The fee associated with the tip.createdAt(string): The date and time when the tip was created.
The status property of the tip can be one of the following values:
pending: The tip has been created, but the transaction is awaiting confirmation.confirmed: The tip has been confirmed and sent to the employee.void: The tip has been canceled or refunded.
Request body structure (TS notation)
Request example
Response example
v1/data/transaction/refund#
If a transaction is refunded, notify Tippy by calling
v1/data/transaction/refund. That way, we can keep track on our
side and subtract the refunded amounts from the staff members' tip balances.
A refund can be full or partial. In the case of a full refund, just set
partial to false and leave out the amount field. In the case of a partial
refund, set partial to true and specify the amount.
If you want to control distribution of the refunded tips between staff members
who were part of a service whose transaction is being refunded, use the talents
field. talents is an array of object, each object containing an employeeId field
that uniquely identifies the staff member and an amount field that specifies
what the amount subtracted from that employee's tip balance should be. If you don't
specify talents, we split the refund evenly between staff members.
A partial refund amount will always be deducted from the gross amount of the entire transaction (including fees).
If you want to simulate a refund, you can set the parameter dryRun to true. This
will return the result with the calculations as if the refund had actually taken place,
but nothing will be executed or saved. Suitable if you want to check the numbers before
making the refund.
Returns a 200 response on success.
Request body structure (TS notation)
Response body structure (TS notation)
Refund response is an array of objects. If you refund the entire transaction, a response will be single refund object without employeeId information. If you initiate a partial refund with a specific amount, you will receive response object for each of the employees involved in the original transaction.
Request examples
Response example
Full refund:
Partial refund (amount $6):
v1/data/transaction/transfer#
If you want to re-distribute tips between different staff members once you already collected payments,
and do not want to swipe card again, notify Tippy by calling v1/data/transaction/transfer.
That way, the tip net amount will be re-distributed.
If you want to control distribution of the transferred tips between staff members
who were part of a service, use the talents field.
talents is an array of object, each object containing an employeeId field
that uniquely identifies the staff member, it's firstName, lastName, and avatar.
Those fields are required if we want to distribute tips to staff member that is not created
yet on Tippy side. The last field of talents object is amount. That field specifies
what amount should be re-distributed to each talent. If you specify amounts, it should be
specified for each talent, if not endpoint will return an error, also amounts sum must match
the net tip amount of transaction. If you don't specify amount to any talent,
we split the net amount evenly between staff members.
Returns a 200 response on success.
Request body structure (TS notation)
Request examples