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
Fetch Payments with Number	GET /billing/{tenantLocator}/payments/numbers/{paymentNumber}
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
Set Payment Number	POST /billing/{tenantLocator}/payments/{locator}/number/set
Execute Payment	PATCH /billing/{tenantLocator}/payments/{locator}/request
Cancel Payment	PATCH /billing/{tenantLocator}/payments/{locator}/cancel
Fail Payment	PATCH /billing/{tenantLocator}/payments/{locator}/fail
Fetch shortfall credits	GET /billing/{tenantLocator}/payments/{locator}/shortfallCredits/list

Fetch

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

fetchSubpayments

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

Fetch Payments with Number

fetchPaymentsWithNumber

GET /billing/{tenantLocator}/payments/numbers/{paymentNumber}

Request Parameters:

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

Response:PaymentResponse[]
Security Group:payments   Permissions:read,list

ListPageResponsePaymentResponse

required
listCompleted boolean
items PaymentResponse[]

PaymentResponse

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

optional
accountLocator string?
aggregatePaymentLocator string?
externalCashTransactionLocator string?
retryPlanName string?
anonymizedAt datetime?
nextRequestTime datetime?
paymentMode Enum? aggregate | normal
paymentNumber string?
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 | invoiceItem | subpayment

optional
amount number?

PaymentRequestExecutionLogItem

required
paymentRequestLocator string
paymentRequestState Enum completed | error | failed | pending
data map<string,object>

optional
note string?
requestTime datetime?
transactionId string?

Create and Update

Create a Payment

createPayment

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
data map<string,object>
targets CreditItem[]

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

Update a Payment

updatePayment

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?
retryPlanName string?
currency string?
amount number?
nextRequestTime datetime?
paymentMode Enum? aggregate | normal
transactionMethod Enum? ach | cash | eft | standard | wire
transactionNumber string?
type string?
useDefaultFinancialInstrument boolean?

Update a Payment (overwrite extension data)

updatePaymentOverwriteData

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

Set Payment Number

setPaymentNumber

POST /billing/{tenantLocator}/payments/{locator}/number/set

Request Parameters:

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

Response:PaymentResponse
Security Group:payments   Permission:write

Payment Requests

Execute Payment

executePayment

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

Request Parameters:

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

Response:PaymentResponse
Security Group:payments   Permission:write

Cancel Payment

cancelPayment

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

Request Parameters:

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

Response:PaymentResponse
Security Group:payments   Permission:write

Fail Payment

failPayment

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

Request Parameters:

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

Response:PaymentResponse
Security Group:payments   Permission:write

Shortfall Credits

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 | shortfallWriteOff | subpayment | writeOff
createdAt datetime
createdBy uuid
targets CreditItem[]

optional
reversalReason string?

Payments by invoice

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

PaymentListResponse

required
listCompleted boolean
items PaymentResponse[]

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
includeReversed	query	boolean?	optional
offset	query	int?	optional
count	query	int?	optional
extended	query	boolean?	optional

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

See Also

• Payments