Payments

The Payments API is used to record a payment or refund made to an invoice, update acceptable payment methods, and access the payment history of an invoice. The Payments API is connected to the Appointments and Products APIs, as payments are made to a business for either appointments or products incurred, and is connected to the Invoices API as invoices act as logs of the payments and refunds made by or to a client. Since payments are necessary for your business to collect revenue, it is crucial that you familiarize yourself with how to get and create payments on your account.

On this page

These are the endpoints that are available under the /payments path, which lists all the different payments on an account.

Endpoint	Description
GET /payments/invoice/{invoiceId}	Returns all payment objects which represent payments or refunds that have been recorded to specified invoice in array format.
GET /payments/paymentMethods	Returns an array of strings that represent the current acceptable payment methods. Has acceptable values "Cash", "Check", "Visa", "Master Card", "Amex", "Discover".
GET /payments/cashRegister	Returns all payment that have the gateway property set to MANUAL and have paymentMode set to "Cash".
GET /payments/giftCard/{giftCardUUID}	Returns all payment objects that have been made with specified gift card in array format.
POST /payments/manualPayment	Creates a new payment object on an invoice. Request body/payload: Must pass a payment object in request body/payload, and must set the gateway field to "MANUAL". For these calls, you need to pass a payments object with all required fields and any fields you want to set filled in the body of the payload. We have an example of a payments object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.
POST /invoicePaymentMap/{invoiceId}	Returns a payment portal object that contains a redirectUrl and a postUrl. If the redirectUrl is not null, then the payment portal has an embeddable page that you can display in the modal window (true for Square, Stripe, Authorize.net). If the redirectUrl is null, then a postUrl will be provided that can be used along with the map property returned from this POST response to create a form post and pass the user’s browser to the external URL (true for PayPal). Request body/payload: Must pass amount to be charged in request body/payload.
POST /invoice/charge/stripe/{invoiceId}/{clientId}	This endpoint can only be used when the client object's stripeCustomerId property is filled in. Request body/payload: Must pass amount to be charged in request body/payload.
POST /payments/payByGiftCard	Creates a new payment object on an invoice that has paymentMode = "GiftCard". Request body/payload: Must pass a payment object with giftCardUUID property filled in request body/payload.
DELETE /payments/{paymentId}	Deletes a payment or refund object previously recorded to an invoice from your account by setting its active property to false.

There are no parameters included with payments calls.

The objects below represent the minimum viable objects to pass that are needed to create or update a payments object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.

POST /payments/manualPayment

{
    "amount": 20,
    "businessId": 43111,
    "cardNumber": "123ABC",
    "createdDate": 1687793475990,
    "invoiceId": 2523045,
    "paymentDate": "2023-06-26T04:00:00.000Z",
    "paymentMode": "Cash"
}

POST /invoicePaymentMap/{invoiceId}

10.0

POST /invoice/charge/stripe/{invoiceId}/{clientId}

25.0

POST /payments/payByGiftCard

{
    "amount": 1.5,
    "businessId": 43111,
    "cardNumber": "test",
    "createdDate": 1687797782535,
    "gateway": "MANUAL",
    "giftCard": {Gift card object for gift card of payment - for more info, see Gift Cards API page},
    "giftCardUUID": "Uql9KTXtTSiFhAiYDYSNIg",
    "invoiceId": 2523045,
    "paymentDate": "2023-06-26T04:00:00.000Z",
    "paymentMode": "GiftCard",
    "paymentType": "Sale",
    "status": "Success"
}

GET /payments/invoice/{invoiceId}

[{
    "amount": 1,
    "avsAddress": null,
    "avsZipCode": null,
    "businessId": 43111,
    "calendarId": null,
    "cardExpirationDate": null,
    "cardNumber": "Test Comment 2",
    "cardType": null,
    "client": null,
    "clientId": null,
    "createdDate": 1536264114914,
    "createdUser": "JoeSchmo",
    "currency": "USD",
    "gateway": "MANUAL",
    "gatewayChargeId": null,
    "gatewayId": null,
    "giftCardUUID": null,
    "invoiceId": 451918,
    "modifiedDate": 1536264114914,
    "modifiedUser": "JoeSchmo",
    "mwToken": null,
    "paymentDate": 1536192000000,
    "paymentHistory": null,
    "paymentId": 291394,
    "paymentMode": "Cash",
    "paymentType": null,
    "professionalId": null,
    "rawData": null,
    "salesForceId": null,
    "status": "Success",
    "statusSummary": null
}]

GET /payments/paymentMethod

{
    "0": "Check",
    "1": "Visa",
    "2": "Master Card",
    "3": "Discover
}

GET /payments/cashRegister

[{
    "amount": 15,
    "avsAddress": null,
    "avsZipCode": null,
    "businessId": 43111,
    "calendarId": null,
    "cardExpirationDate": null,
    "cardNumber": null,
    "cardType": null,
    "client": null,
    "clientId": null,
    "createdDate": 1536676080811,
    "createdUser": "JoeSchmo",
    "currency": "USD",
    "gateway": "MANUAL",
    "gatewayChargeId": null,
    "gatewayId": null,
    "giftCardUUID": null,
    "invoiceId": 451918,
    "modifiedDate": 1536676080811,
    "modifiedUser": "JoeSchmo",
    "mwToken": null,
    "paymentDate": 1536624000000,
    "paymentHistory": null,
    "paymentId": 302618,
    "paymentMode": "Cash",
    "paymentType": null,
    "professionalId": null,
    "rawData": null,
    "salesForceId": null,
    "status": "Success",
    "statusSummary": null
}]

GET /payments/giftCard/{giftCardUUID}

[{
    "amount": 5,
    "avsAddress": null,
    "avsZipCode": null,
    "businessId": 43111,
    "calendarId": null,
    "cardExpirationDate": null,
    "cardNumber": null,
    "cardType": null,
    "client": null,
    "clientId": null,
    "createdDate": 1538148338329,
    "createdUser": "JoeSchmo",
    "currency": "USD",
    "gateway": "MANUAL",
    "gatewayChargeId": null,
    "gatewayId": null,
    "giftCardUUID": "rSnVGKkHSGCYfalfOuae1g",
    "invoiceId": 469501,
    "modifiedDate": 1538148338329,
    "modifiedUser": "JoeSchmo",
    "mwToken": null,
    "paymentDate": 1538092800000,
    "paymentHistory": null,
    "paymentId": 343138,
    "paymentMode": "GiftCard",
    "paymentType": "Sale",
    "professionalId": null,
    "rawData": null,
    "salesForceId": null,
    "status": "Success",
    "statusSummary": null
}]

POST /payments/manualPayment

{
    "amount": 3.2,
    "avsAddress": null,
    "avsZipCode": null,
    "businessId": 43111,
    "calendarId": null,
    "cardExpirationDate": null,
    "cardNumber": "ABC123",
    "cardType": null,
    "clientId": null,
    "createdDate": 1536679770308,
    "createdUser": "JoeSchmo",
    "currency": "USD",
    "gateway": "MANUAL",
    "gatewayChargeId": null,
    "gatewayId": null,
    "giftCardUUID": null,
    "invoiceId": 451918,
    "modifiedDate": 1536679770308,
    "modifiedUser": "JoeSchmo",
    "mwToken": null,
    "paymentDate": 15366779692856,
    "paymentHistory": null,
    "paymentId": 302779,
    "paymentMode": "Cash",
    "paymentType": null,
    "professionalId": null,
    "rawData": null,
    "salesForceId": null,
    "status": "Success",
    "statusSummary": null
}

POST /invoicePaymentMap/{invoiceId}

{
    "buttonImageUrl": null,
    "gateway": "STRIPE",
    "html": null,
    "map": {},
    "postUrl": null,
    "redirectUrl": "https://www.timetap.com/ttcs/app/home/MORGANKEARNEY#/invoices/9bb023ab49ac4c01aadd1c65311dfe38?paying=true&showHeader=0&invoiceHash=9bb023ab49ac4c01aadd1c65311dfe38&paymentAmount=10.0&username=MORGANKEARNEY"
}

POST /invoicePaymentMap/{invoiceId} with map (PayPal)

{
	buttonImageUrl: "https://www.paypalobjects.com/webstatic/mktg/logo/AM_mc_vs_dc_ae.jpg"
	gateway: "PAYPAL"
	html: null
	map: {
		add: "1"
		amount: "2"
		bn: "TimeTap_SP_EC"
		business: "Y3DD3H27YNEUL"
		cancel_return: "https://www.timetap.com/businessWeb/web/payment/cancel/19510/451910"
		cmd: "_xclick"
		currency_code: "USD"
		custom: "451910"
		email: "jane@email.com"
		first_name: "Jane"
		invoice: "451910"
		item_name: "Invoice #451910"
		last_name: "Doe"
		notify_url: "https://www.timetap.com/businessWeb/businessIPN2.do"
		return: "https://www.timetap.com/businessWeb/web/payment/complete/19510/451910"
		shipping: "0.0"
		tax: "0.0"
		tax_cart: "0.0"
	}
	postUrl: "https://www.paypal.com/cgi-bin/webscr"
	redirectUrl: null
}

POST /invoice/charge/stripe/{invoiceId}/{clientId}

{
    "balanceAmount": 0,
    "billingLocationId": 40632,
    "billingStaffId": 43573,
    "businessId": 43111,
    "chargeDate": 1688062229137,
    "clientId": 2196939,
    "comments": null,
    "createdDate": 1664203348069,
    "createdUser": "WebClient",
    "currency": null,
    "depositAmount": 5,
    "discountAmount": 0,
    "hasBeenPreAuthed": false,
    "invoiceDate": 1664203348069,
    "invoiceDueDate": null,
    "invoiceHash": "30f80d07baa041e5a9342357839592a3",
    "invoiceId": 26485,
    "invoiceItem": [invoiceItem object for Invoice Item of payment - for more info, see Invoice Items API page],
    "invoiceNumber": "26485",
    "invoiceTotalAmount": 25,
    "invoiceType": "INVOICE",
    "invoiceUrl": null,
    "lastStatus": null,
    "lastStatusDate": 1688062227473,
    "modifiedDate": 1688062229137,
    "modifiedUser": "Stripe",
    "open": false,
    "paidAmount": 25,
    "paidOnDate": 1688062227473,
    "payBtnClickTime": 1664203352374,
    "paymentAmount": 0,
    "preAuthPayment": false,
    "status": "CLOSED",
    "statusText": "CLOSED - Paid",
    "subStatus": "Paid",
    "subtotalAmount": 25,
    "tax2Amount": 0,
    "taxAmount": 0,
    "tipAmount": 0,
    "transactionFeeAmount": 0,
    "writeOffAmount": 0
}

POST /payments/payByGiftCard

{
    "amount": 5,
    "avsAddress": null,
    "avsZipCode": null,
    "businessId": 43111,
    "calendarId": null,
    "cardExpirationDate": null,
    "cardNumber": null,
    "cardType": null,
    "client": null,
    "clientId": null,
    "createdDate": 1538148338329,
    "createdUser": "JoeSchmo",
    "currency": null,
    "gateway": "MANUAL",
    "gatewayChargeId": null,
    "gatewayId": null,
    "giftCardUUID": "rSnVGKkHSGCYfalfOuae1g,
    "invoiceId": 469501,
    "modifiedDate": 1538148338329,
    "modifiedUser": "JoeSchmo",
    "mwToken": null,
    "paymentDate": 1538148338329,
    "paymentHistory": null,
    "paymentId": 343138,
    "paymentMode": "GiftCard",
    "paymentType": "Sale",
    "professionalId": null,
    "rawData": null,
    "salesForceId": null,
    "status": "Success",
    "statusSummary": null
}

Property Name	Data Type	Required	Description
amount	integer	Yes	Displays the monetary amount recorded as paid or refunded.
avsAddress	string
avsZipCode
businessId	integer	Yes	Provides unique numeric ID for the business issuing the invoice for which you are recording the specified payment/refund.
calendarId	integer		Provides unique numeric ID for the calendar of the business issuing the invoice for which you are recording the specified payment/refund.
cardExpirationDate	string		Displays the expiration date of the credit card used in the specified payment in MM-DD-YYYY form.
cardNumber	string		Repurposed to record and display comments added while recording payment/refund in the TimeTap UI.
cardType	string		Displays as the type of credit card used to make the specified payment/refund.
client	object		Client object for client of the specified payment - for more info, see Clients API page.
clientId	integer		Provides unique numeric ID for the client that made the specified payment/refund.
createdDate	integer		Displays as the date the specified payment/refund was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
createdUser	string		Displays as username of the user who created the specified payment/refund.
currency	string		Displays the ISO 4217 currency code for the currency used to make the specified payment/refund.
gateway	string		Displays as plain-text identifier to specify which payment gateway was used to record the specified payment/refund.
gatewayChargeId	string		Provides unique alphanumeric ID for the gateway charged.
gatewayId	integer		Provides unique numeric ID for the payment gateway used to record the specified payment/refund.
giftcardUUID	string		Provides unique alphanumeric ID for the specified gift card.
invoiceId	integer	Yes	Provides unique numeric ID for the invoice to which you are applying the specified payment/refund.
modifiedDate	integer		Displays as date on which the specified payment/refund was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifiedUser	string		Displays as username of the user who last modified the specified payment/refund.
mwToken	string		Provides a unique system identifier.
paymentDate	integer		Displays as date on which the specified payment object was created.
paymentHistory	string		Displays the payment history for the specified payment/refund.
paymentId	integer		Provides unique numeric ID for the specified payment object.
paymentMode	string		Displays as plain-text identifier used to specify which method of payment was used to record the specified payment/refund.
paymentType	string		Displays as the payment type of the specified payment. Has acceptable values Sale,
professionalId	integer		Provides unique numeric ID for the staff member recording the specified payment/refund.
rawData	string		Displays the payment data as a JSON.
salesForceId	string		Provides unique alphanumeric ID for the SalesForce account associated with the specified payment/refund.
status	string		Displays as status of the specified payment. Has acceptable values OPEN, CLOSED, VOID, DELETED.
statusSummary	string

TimeTap API

Payments

Payments API Endpoints

Payments API Parameters

Payments API Request Body/Payloads

Payments API Responses

Payments Object Values