Payments API

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
Generate Payment Number	POST/billing/{tenantLocator}/payments/{locator}/number/generate
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
Preview Payment Validation	GET/billing/{tenantLocator}/payments/{locator}/previewValidate
Preview Payment Post	GET/billing/{tenantLocator}/payments/{locator}/previewPost

Fetch

Fetch a Payment

Fetch a PaymentfetchPayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

read

Fetch Multiple Payments

Fetch Multiple PaymentsfetchMultiplePayments

GET/billing/{tenantLocator}/payments/list

Parameters

Name	In	Type	Required
`tenantLocator`	path	`uuid`	Yes
`offset`	query	`integer?`	No
`count`	query	`integer?`	No
`accountLocator`	query	`ulid?`	No
`targetContainerLocator`	query	`ulid?`	No
`extended`	query	`boolean?`	No

Response:ListPageResponsePaymentResponse

Security Group:payments

Permissions:

read,list

Fetch Subpayments

Fetch SubpaymentsfetchSubpayments

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

Parameters

Name	In	Type	Required
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes
`offset`	query	`integer?`	No
`count`	query	`integer?`	No

Response:ListPageResponsePaymentResponse

Security Group:payments

Permissions:

read,list

Fetch Payments With Number

Fetch Payments With NumberfetchPaymentsWithNumber

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`paymentNumber`	path	`string`	Yes

Response:PaymentResponse[]

Security Group:payments

Permissions:

read,list

ListPageResponsePaymentResponse

Required properties

Property	Type	Description
`listCompleted`	`boolean`
`items`	`PaymentResponse[]`

PaymentResponse

Required properties

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

Optional properties

Property	Type	Description
`accountLocator`	`ulid?`
`aggregatePaymentLocator`	`ulid?`
`externalCashTransactionLocator`	`ulid?`
`retryPlanName`	`string?`
`anonymizedAt`	`datetime?`
`nextRequestTime`	`datetime?`
`paymentMode`	`Enum? normal \| aggregate`
`paymentNumber`	`string?`
`postedAt`	`datetime?`
`remainingAmount`	`number?`
`reversalReason`	`string?`
`reversedAt`	`datetime?`
`reversedBy`	`uuid?`
`validationResult`	`ValidationResult?`
`data`	`map<string, object>?`

SubpaymentResponse

Required properties

Property	Type	Description
`subpaymentLocator`	`ulid`
`amount`	`number`

CreditItem

Required properties

Property	Type	Description
`containerLocator`	`ulid`
`containerType`	`Enum invoice \| account \| subpayment \| invoiceItem`

Optional properties

Property	Type	Description
`amount`	`number?`

PaymentRequestExecutionLogItem

Required properties

Property	Type	Description
`paymentRequestLocator`	`ulid`
`paymentRequestState`	`Enum pending \| completed \| failed \| error`
`data`	`map<string, object>`

Optional properties

Property	Type	Description
`note`	`string?`
`requestTime`	`datetime?`
`transactionId`	`string?`

Create and Update

Create a Payment

Create a PaymentcreatePayment

POST/billing/{tenantLocator}/payments

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes

Request:PaymentCreateRequest

Response:PaymentResponse

Security Group:payments

Permission:

write

PaymentCreateRequest

Required properties

Property	Type	Description
`amount`	`number`
`type`	`string`
`data`	`map<string, object>`
`targets`	`CreditItem[]`

Optional properties

Property	Type	Description
`accountLocator`	`ulid?`
`financialInstrumentLocator`	`ulid?`
`retryPlanName`	`string?`
`currency`	`string?`
`paymentMode`	`Enum? normal \| aggregate`
`transactionMethod`	`Enum? ach \| cash \| eft \| standard \| wire`
`transactionNumber`	`string?`
`useDefaultFinancialInstrument`	`boolean?`

Update a Payment

Update a PaymentupdatePayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Request:PaymentUpdateRequest

Response:PaymentResponse

Security Group:payments

Permission:

write

PaymentUpdateRequest

Required properties

Property	Type	Description
`addTargets`	`CreditItem[]`
`removeData`	`map<string, object>`
`removeTargets`	`ulid[]`
`setData`	`map<string, object>`

Optional properties

Property	Type	Description
`accountLocator`	`ulid?`
`financialInstrumentLocator`	`ulid?`
`retryPlanName`	`string?`
`currency`	`string?`
`amount`	`number?`
`nextRequestTime`	`datetime?`
`paymentMode`	`Enum? normal \| aggregate`
`transactionMethod`	`Enum? ach \| cash \| eft \| standard \| wire`
`transactionNumber`	`string?`
`type`	`string?`
`useDefaultFinancialInstrument`	`boolean?`

Update a Payment (overwrite extension data)

Update a Payment (overwrite extension data)updatePaymentOverwriteData

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Request:PaymentCreateRequest

Response:PaymentResponse

Security Group:payments

Permission:

write

Validate a Payment

Validate a PaymentvalidatePayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Post a Payment

Post a PaymentpostPayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Reverse a Posted Payment

Reverse a Posted PaymentreversePayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Request:CreditDistributionReverseRequest

Response:PaymentResponse

Security Group:payments

Permission:

write

Reset a Validated Payment Back to Draft State

Reset a Validated Payment Back to Draft StateresetPayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Discard a Payment

Discard a PaymentdiscardPayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Set Payment Number

Set Payment NumbersetPaymentNumber

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

Parameters

Name	In	Type	Required
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes
`paymentNumber`	query	`string`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Generate Payment Number

Generate Payment NumbergeneratePaymentNumber

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Payment Requests

Execute Payment

Execute PaymentexecutePayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Cancel Payment

Cancel PaymentcancelPayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Fail Payment

Fail PaymentfailPayment

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PaymentResponse

Security Group:payments

Permission:

write

Shortfall Credits

Fetch shortfall credits

Fetch shortfall creditslistShortfallCredits

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

Parameters

Name	In	Type	Required
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes
`offset`	query	`integer?`	No
`count`	query	`integer?`	No

Response:ListPageResponseShortfallCreditResponse

Security Group:payments

Permissions:

read,list

ListPageResponseShortfallCreditResponse

Required properties

Property	Type	Description
`listCompleted`	`boolean`
`items`	`ShortfallCreditResponse[]`

ShortfallCreditResponse

Required properties

Property	Type	Description
`locator`	`ulid`
`accountLocator`	`ulid`
`parentCreditLocator`	`ulid`
`currency`	`string`
`shortfallCreditState`	`Enum draft \| distributed \| reversed`
`amount`	`number`
`creditType`	`Enum creditDistribution \| disbursement \| payment \| subpayment \| shortfallWriteOff \| writeOff`
`createdAt`	`datetime`
`createdBy`	`uuid`
`targets`	`CreditItem[]`

Optional properties

Property	Type	Description
`reversalReason`	`string?`

Payments by invoice

Fetch Payments For An Invoice

Fetch Payments For An InvoicefetchPaymentsForAnInvoice

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

Parameters

Name	In	Type	Required
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes
`includeReversed`	query	`boolean?`	No
`offset`	query	`integer?`	No
`count`	query	`integer?`	No
`extended`	query	`boolean?`	No

Response:PaymentListResponse

Security Group:invoices

Permissions:

read,list

PaymentListResponse

Required properties

Property	Type	Description
`listCompleted`	`boolean`
`items`	`PaymentResponse[]`

Fetch Invoices Targeted By APayment

Fetch Invoices Targeted By A PaymentfetchInvoicesTargetedByAPayment

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

Parameters

Name	In	Type	Required
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes
`includeReversed`	query	`boolean?`	No
`offset`	query	`integer?`	No
`count`	query	`integer?`	No
`extended`	query	`boolean?`	No

Response:InvoiceListResponse

Security Group:payments

Permissions:

read,list

Payment Previews

Preview Payment Validation

Preview Payment ValidationpreviewPaymentValidate

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PreviewPaymentResponse

Security Group:payments

Permission:

read

Preview Payment Post

Preview Payment PostpreviewPaymentPost

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

Parameters

Name	In	Type	Required	Description
`tenantLocator`	path	`uuid`	Yes
`locator`	path	`ulid`	Yes

Response:PreviewPaymentResponse

Security Group:payments

Permission:

read

PreviewPaymentResponse

Required properties

Property	Type	Description
`locator`	`ulid`
`currency`	`string`
`paymentState`	`Enum draft \| validated \| requested \| executing \| posted \| failed \| cancelled \| reversed \| discarded`
`amount`	`number`
`type`	`string`
`data`	`map<string, object>`
`createdAt`	`datetime`
`createdBy`	`uuid`
`credits`	`CreditWithBalance[]`
`shortfallCredits`	`ShortfallCreditPreviewResponse[]`
`targets`	`CreditItem[]`

Optional properties

Property	Type	Description
`accountLocator`	`ulid?`
`aggregatePaymentLocator`	`ulid?`
`externalCashTransactionLocator`	`ulid?`
`invoices`	`ListPageResponseInvoicePaymentPreview?`
`paymentMode`	`Enum? normal \| aggregate`
`postedAt`	`datetime?`
`remainingAmount`	`number?`
`validationResult`	`ValidationResult?`
`subpayments`	`PreviewPaymentResponse[]?`

CreditWithBalance

Required properties

Property	Type	Description
`locator`	`ulid`
`amount`	`number`
`type`	`Enum accountCreditBalance \| invoiceCreditBalance \| cash \| creditCash \| charge \| credit \| installmentItem \| invoiceItem \| account \| policy \| accountExpenseBalance`

ShortfallCreditPreviewResponse

Required properties

Property	Type	Description
`locator`	`ulid`
`accountLocator`	`ulid`
`currency`	`string`
`shortfallCreditState`	`Enum draft \| distributed \| reversed`
`amount`	`number`
`creditType`	`Enum creditDistribution \| disbursement \| payment \| subpayment \| shortfallWriteOff \| writeOff`
`targets`	`CreditItem[]`

ListPageResponseInvoicePaymentPreview

Required properties

Property	Type	Description
`listCompleted`	`boolean`
`items`	`InvoicePaymentPreview[]`

InvoicePaymentPreview

Required properties

Property	Type	Description
`locator`	`ulid`
`accountLocator`	`ulid`
`invoiceState`	`Enum open \| settled \| discarded`

Optional properties

Property	Type	Description
`amount`	`number?`
`remainingAmount`	`number?`

Payments API

Fetch

Fetch a Payment

Fetch Multiple Payments

Fetch Subpayments

Fetch Payments With Number

Create and Update

Create a Payment

Update a Payment

Update a Payment (overwrite extension data)

Validate a Payment

Post a Payment

Reverse a Posted Payment

Reset a Validated Payment Back to Draft State

Discard a Payment

Set Payment Number

Generate Payment Number

Payment Requests

Execute Payment

Cancel Payment

Fail Payment

Shortfall Credits

Fetch shortfall credits

Payments by invoice

Fetch Payments For An Invoice

Fetch Invoices Targeted By APayment

Payment Previews

Preview Payment Validation

Preview Payment Post

See Also

On this page