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




Payments API Endpoints

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

EndpointDescription
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/paymentMethodsReturns an array of strings that represent the current acceptable payment methods. Has acceptable values "Cash", "Check", "Visa", "Master Card", "Amex", "Discover".
GET /payments/cashRegisterReturns 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.




Payments API Parameters

There are no parameters included with payments calls.




Payments API Request Body/Payloads

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"
}




Payments API Responses

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
}




Payments Object Values 


Property Name
Data Type
Required
Description
amountintegerYesDisplays the monetary amount recorded as paid or refunded.
avsAddressstring

avsZipCode


businessIdintegerYesProvides unique numeric ID for the business issuing the invoice for which you are recording the specified payment/refund.
calendarIdinteger
Provides unique numeric ID for the calendar of the business issuing the invoice for which you are recording the specified payment/refund.
cardExpirationDatestring
Displays the expiration date of the credit card used in the specified payment in MM-DD-YYYY form.
cardNumberstring
Repurposed to record and display comments added while recording payment/refund in the TimeTap UI.
cardTypestring
Displays as the type of credit card used to make the specified payment/refund.
clientobject
Client object for client of the specified payment - for more info, see Clients API page.
clientIdinteger
Provides unique numeric ID for the client that made the specified payment/refund.
createdDateinteger
Displays as the date the specified payment/refund was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
createdUserstring
Displays as username of the user who created the specified payment/refund.
currencystring
Displays the ISO 4217 currency code for the currency used to make the specified payment/refund.
gatewaystring
Displays as plain-text identifier to specify which payment gateway was used to record the specified payment/refund.
gatewayChargeIdstring
Provides unique alphanumeric ID for the gateway charged.
gatewayIdinteger
Provides unique numeric ID for the payment gateway used to record the specified payment/refund.
giftcardUUIDstring
Provides unique alphanumeric ID for the specified gift card.
invoiceIdintegerYesProvides unique numeric ID for the invoice to which you are applying the specified payment/refund.
modifiedDateinteger
Displays as date on which the specified payment/refund was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifiedUserstring
Displays as username of the user who last modified the specified payment/refund. 
mwTokenstring
Provides a unique system identifier.
paymentDateinteger
Displays as date on which the specified payment object was created.
paymentHistorystring
Displays the payment history for the specified payment/refund.
paymentIdinteger
Provides unique numeric ID for the specified payment object.
paymentModestring
Displays as plain-text identifier used to specify which method of payment was used to record the specified payment/refund.
paymentTypestring
Displays as the payment type of the specified payment. Has acceptable values Sale, 
professionalIdinteger
Provides unique numeric ID for the staff member recording the specified payment/refund.
rawDatastring
Displays the payment data as a JSON.
salesForceIdstring
Provides unique alphanumeric ID for the SalesForce account associated with the specified payment/refund.
statusstring
Displays as status of the specified payment. Has acceptable values OPEN, CLOSED, VOID, DELETED.
statusSummarystring