Payments API

Endpoint Index

Action	Endpoint
Fetch a Payment	GET /billing/{tenantLocator}/payments/{locator}
Fetch Multiple Payments	GET /billing/{tenantLocator}/payments/list
Fetch Subpayments	GET /billing/{tenantLocator}/payments/{locator}/subpayments/list
Create a Payment	POST /billing/{tenantLocator}/payments
Update a Payment	PATCH /billing/{tenantLocator}/payments/{locator}
Update a Payment (overwrite extension data)	PUT /billing/{tenantLocator}/payments/{locator}
Validate a Payment	PATCH /billing/{tenantLocator}/payments/{locator}/validate
Post a Payment	PATCH /billing/{tenantLocator}/payments/{locator}/post
Reverse a Posted Payment	PATCH /billing/{tenantLocator}/payments/{locator}/reverse
Reset a Validated Payment Back to Draft State	PATCH /billing/{tenantLocator}/payments/{locator}/reset
Discard a Payment	PATCH /billing/{tenantLocator}/payments/{locator}/discard
Fetch shortfall credits	GET /billing/{tenantLocator}/payments/{locator}/shortfallCredits/list

Fetch a Payment

fetchPayment

GET /billing/{tenantLocator}/payments/{locator}

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Response:PaymentResponse
Security Group:payments   Permission:read

Fetch Multiple Payments

fetchMultiplePayments

GET /billing/{tenantLocator}/payments/list

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
offset	query	int?	optional
count	query	int?	optional
accountLocator	query	string?	optional
targetContainerLocator	query	string?	optional
extended	query	boolean?	optional

Response:ListPageResponsePaymentResponse
Security Group:payments   Permissions:read,list

Fetch Subpayments

listSubpayments

GET /billing/{tenantLocator}/payments/{locator}/subpayments/list

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required
offset	query	int?	optional
count	query	int?	optional

Response:ListPageResponsePaymentResponse
Security Group:payments   Permissions:read,list

ListPageResponsePaymentResponse

required
listCompleted boolean
items PaymentResponse[]

PaymentResponse

required
locator string
currency string
paymentState Enum draft | validated | posted | reversed | discarded
amount number
type string
createdAt datetime
createdBy uuid
shortfallCreditLocators string[]
subpayments SubpaymentResponse[]
targets CreditItem[]

optional
accountLocator string?
aggregatePaymentLocator string?
externalCashTransactionLocator string?
paymentMode Enum? aggregate | normal
postedAt datetime?
remainingAmount number?
reversalReason string?
reversedAt datetime?
reversedBy uuid?
validationResult ValidationResult?
data map<string,object>?

SubpaymentResponse

required
subpaymentLocator string
amount number

CreditItem

required
containerLocator string
containerType Enum account | invoice | subpayment

optional
amount number?

Create a Payment

addPayment

POST /billing/{tenantLocator}/payments

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required

Request:PaymentCreateRequest
Response:PaymentResponse
Security Group:payments   Permission:write

PaymentCreateRequest

required
amount number
type string
useDefaultFinancialInstrument boolean
data map<string,object>
targets CreditItem[]

optional
accountLocator string?
financialInstrumentLocator string?
currency string?
paymentMode Enum? aggregate | normal
transactionMethod Enum? ach | cash | eft | standard | wire
transactionNumber string?

Update a Payment

patchPayment

PATCH /billing/{tenantLocator}/payments/{locator}

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Request:PaymentUpdateRequest
Response:PaymentResponse
Security Group:payments   Permission:write

PaymentUpdateRequest

required
addTargets CreditItem[]
removeData map<string,object>
removeTargets string[]
setData map<string,object>

optional
accountLocator string?
financialInstrumentLocator string?
currency string?
amount number?
paymentMode Enum? aggregate | normal
transactionMethod Enum? ach | cash | eft | standard | wire
transactionNumber string?
type string?
useDefaultFinancialInstrument boolean?

Update a Payment (overwrite extension data)

putPayment

PUT /billing/{tenantLocator}/payments/{locator}

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Request:PaymentCreateRequest
Response:PaymentResponse
Security Group:payments   Permission:write

Validate a Payment

validatePayment

PATCH /billing/{tenantLocator}/payments/{locator}/validate

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Response:PaymentResponse
Security Group:payments   Permission:write

Post a Payment

postPayment

PATCH /billing/{tenantLocator}/payments/{locator}/post

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Response:PaymentResponse
Security Group:payments   Permission:write

Reverse a Posted Payment

reversePayment

PATCH /billing/{tenantLocator}/payments/{locator}/reverse

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Request:CreditDistributionReverseRequest
Response:PaymentResponse
Security Group:payments   Permission:write

Reset a Validated Payment Back to Draft State

resetPayment

PATCH /billing/{tenantLocator}/payments/{locator}/reset

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Response:PaymentResponse
Security Group:payments   Permission:write

Discard a Payment

discardPayment

PATCH /billing/{tenantLocator}/payments/{locator}/discard

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required

Response:PaymentResponse
Security Group:payments   Permission:write

Fetch Payments for an Invoice

fetchPaymentsForAnInvoice

GET /billing/{tenantLocator}/invoices/{locator}/payments/list

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required
includeReversed	query	boolean?	optional
offset	query	int?	optional
count	query	int?	optional
extended	query	boolean?	optional

Response:PaymentListResponse
Security Group:invoices   Permissions:read,list

Fetch Invoices Targeted By a Payment

fetchInvoicesTargetedByAPayment

GET /billing/{tenantLocator}/payments/{locator}/invoices/list

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required
offset	query	int?	optional
count	query	int?	optional
extended	query	boolean?	optional

Response:InvoiceListResponse
Security Group:payments   Permissions:read,list

Fetch shortfall credits

listShortfallCredits

GET /billing/{tenantLocator}/payments/{locator}/shortfallCredits/list

Request Parameters:

Name	Position	Type	Required
tenantLocator	path	uuid	required
locator	path	string	required
offset	query	int?	optional
count	query	int?	optional

Response:ListPageResponseShortfallCreditResponse
Security Group:payments   Permissions:read,list

ListPageResponseShortfallCreditResponse

required
listCompleted boolean
items ShortfallCreditResponse[]

ShortfallCreditResponse

required
locator string
accountLocator string
parentCreditLocator string
currency string
shortfallCreditState Enum draft | distributed | reversed
amount number
creditType Enum creditDistribution | disbursement | payment | refund | shortfallWriteOff | subpayment | writeOff
createdAt datetime
createdBy uuid
targets CreditItem[]

optional
reversalReason string?

See Also

• Payments