# Payments API



<EndpointIndex
  names={[
  	'fetchPayment',
  	'fetchMultiplePayments',
  	'fetchSubpayments',
  	'fetchPaymentsWithNumber',
  	'createPayment',
  	'updatePayment',
  	'updatePaymentOverwriteData',
  	'validatePayment',
  	'postPayment',
  	'reversePayment',
  	'resetPayment',
  	'discardPayment',
  	'setPaymentNumber',
  	'generatePaymentNumber',
  	'executePayment',
  	'cancelPayment',
  	'failPayment',
  	'listShortfallCredits',
  	'previewPaymentValidate',
  	'previewPaymentPost',
  ]}
  titles={{
  	fetchPayment: 'Fetch a Payment',
  	fetchMultiplePayments: 'Fetch Multiple Payments',
  	fetchSubpayments: 'Fetch Subpayments',
  	createPayment: 'Create a Payment',
  	updatePayment: 'Update a Payment',
  	updatePaymentOverwriteData: 'Update a Payment (overwrite extension data)',
  	validatePayment: 'Validate a Payment',
  	postPayment: 'Post a Payment',
  	reversePayment: 'Reverse a Posted Payment',
  	resetPayment: 'Reset a Validated Payment Back to Draft State',
  	discardPayment: 'Discard a Payment',
  	listShortfallCredits: 'Fetch shortfall credits',
  	previewPaymentValidate: 'Preview Payment Validation',
  }}
/>

Fetch [#fetch]

Fetch a Payment [#fetch-a-payment]

<ApiEndpoint name="fetchPayment" title="Fetch a Payment" />

Fetch Multiple Payments [#fetch-multiple-payments]

<ApiEndpoint name="fetchMultiplePayments" title="Fetch Multiple Payments" />

Fetch Subpayments [#fetch-subpayments]

<ApiEndpoint name="fetchSubpayments" title="Fetch Subpayments" />

Fetch Payments With Number [#fetch-payments-with-number]

<ApiEndpoint name="fetchPaymentsWithNumber" />

<ApiSchema name="ListPageResponsePaymentResponse" />

<ApiSchema name="PaymentResponse" />

<ApiSchema name="SubpaymentResponse" />

<ApiSchema name="CreditItem" />

<ApiSchema name="PaymentRequestExecutionLogItem" />

Create and Update [#create-and-update]

Create a Payment [#create-a-payment]

<ApiEndpoint name="createPayment" title="Create a Payment" />

<ApiSchema name="PaymentCreateRequest" />

Update a Payment [#update-a-payment]

<ApiEndpoint name="updatePayment" title="Update a Payment" />

<ApiSchema name="PaymentUpdateRequest" />

Update a Payment (overwrite extension data) [#update-a-payment-overwrite-extension-data]

<ApiEndpoint name="updatePaymentOverwriteData" title="Update a Payment (overwrite extension data)" />

Validate a Payment [#validate-a-payment]

<ApiEndpoint name="validatePayment" title="Validate a Payment" />

Post a Payment [#post-a-payment]

<ApiEndpoint name="postPayment" title="Post a Payment" />

Reverse a Posted Payment [#reverse-a-posted-payment]

<ApiEndpoint name="reversePayment" title="Reverse a Posted Payment" />

Reset a Validated Payment Back to Draft State [#reset-a-validated-payment-back-to-draft-state]

<ApiEndpoint name="resetPayment" title="Reset a Validated Payment Back to Draft State" />

Discard a Payment [#discard-a-payment]

<ApiEndpoint name="discardPayment" title="Discard a Payment" />

Set Payment Number [#set-payment-number]

<ApiEndpoint name="setPaymentNumber" />

Generate Payment Number [#generate-payment-number]

<ApiEndpoint name="generatePaymentNumber" />

Payment Requests [#payment-requests]

Execute Payment [#execute-payment]

<ApiEndpoint name="executePayment" />

Cancel Payment [#cancel-payment]

<ApiEndpoint name="cancelPayment" />

Fail Payment [#fail-payment]

<ApiEndpoint name="failPayment" />

Shortfall Credits [#shortfall-credits]

Fetch shortfall credits [#fetch-shortfall-credits]

<ApiEndpoint name="listShortfallCredits" title="Fetch shortfall credits" />

<ApiSchema name="ListPageResponseShortfallCreditResponse" />

<ApiSchema name="ShortfallCreditResponse" />

Payments by invoice [#payments-by-invoice]

Fetch Payments For An Invoice [#fetch-payments-for-an-invoice]

<ApiEndpoint name="fetchPaymentsForAnInvoice" />

<ApiSchema name="PaymentListResponse" />

Fetch Invoices Targeted By APayment [#fetch-invoices-targeted-by-apayment]

<ApiEndpoint name="fetchInvoicesTargetedByAPayment" />

Payment Previews [#payment-previews]

Preview Payment Validation [#preview-payment-validation]

<ApiEndpoint name="previewPaymentValidate" title="Preview Payment Validation" />

Preview Payment Post [#preview-payment-post]

<ApiEndpoint name="previewPaymentPost" />

<ApiSchema name="PreviewPaymentResponse" />

<ApiSchema name="CreditWithBalance" />

<ApiSchema name="ShortfallCreditPreviewResponse" />

<ApiSchema name="ListPageResponseInvoicePaymentPreview" />

<ApiSchema name="InvoicePaymentPreview" />

See Also [#see-also]

* [Payments](/features/billing/payments)


## API Reference

GET /billing/{tenantLocator}/payments/{locator} — fetchPayment
Tags: payments-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

GET /billing/{tenantLocator}/payments/list — fetchMultiplePayments
Tags: payments-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  offset (integer, query)
  count (integer, query)
  accountLocator (ulid, query)
  targetContainerLocator (ulid, query)
  extended (boolean, query)
Responses:
  200 ListPageResponsePaymentResponse — OK

GET /billing/{tenantLocator}/payments/{locator}/subpayments/list — fetchSubpayments
Tags: payments-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
Responses:
  200 ListPageResponsePaymentResponse — OK

GET /billing/{tenantLocator}/payments/numbers/{paymentNumber} — fetchPaymentsWithNumber
Tags: payments-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  paymentNumber (string, path, required)
Responses:
  200 PaymentResponse[] — OK

POST /billing/{tenantLocator}/payments — createPayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
Request body (PaymentCreateRequest):
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator} — updatePayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (PaymentUpdateRequest):
Responses:
  200 PaymentResponse — OK

PUT /billing/{tenantLocator}/payments/{locator} — updatePaymentOverwriteData
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (PaymentCreateRequest):
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/validate — validatePayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/post — postPayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/reverse — reversePayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Request body (CreditDistributionReverseRequest):
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/reset — resetPayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/discard — discardPayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

POST /billing/{tenantLocator}/payments/{locator}/number/set — setPaymentNumber
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  paymentNumber (string, query, required)
Responses:
  200 PaymentResponse — OK

POST /billing/{tenantLocator}/payments/{locator}/number/generate — generatePaymentNumber
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/request — executePayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/cancel — cancelPayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

PATCH /billing/{tenantLocator}/payments/{locator}/fail — failPayment
Tags: payments-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PaymentResponse — OK

GET /billing/{tenantLocator}/payments/{locator}/shortfallCredits/list — listShortfallCredits
Tags: payments-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  offset (integer, query)
  count (integer, query)
Responses:
  200 ListPageResponseShortfallCreditResponse — OK

GET /billing/{tenantLocator}/invoices/{locator}/payments/list — fetchPaymentsForAnInvoice
Tags: invoices-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  includeReversed (boolean, query)
  offset (integer, query)
  count (integer, query)
  extended (boolean, query)
Responses:
  200 PaymentListResponse — OK

GET /billing/{tenantLocator}/payments/{locator}/invoices/list — fetchInvoicesTargetedByAPayment
Tags: payments-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
  includeReversed (boolean, query)
  offset (integer, query)
  count (integer, query)
  extended (boolean, query)
Responses:
  200 InvoiceListResponse — OK

GET /billing/{tenantLocator}/payments/{locator}/previewValidate — previewPaymentValidate
Tags: payments-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PreviewPaymentResponse — OK

GET /billing/{tenantLocator}/payments/{locator}/previewPost — previewPaymentPost
Tags: payments-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PreviewPaymentResponse — OK

ListPageResponsePaymentResponse
Properties:
  listCompleted (boolean, required)
  items (PaymentResponse[], required)

PaymentResponse
Properties:
  locator (ulid, required)
  paymentState (Enum draft | validated | requested | executing | posted | failed | cancelled | reversed | discarded, required)
  type (string, required)
  currency (string, required)
  amount (number, required)
  remainingAmount (number)
  data (map<string, object>)
  createdAt (datetime, required)
  createdBy (uuid, required)
  accountLocator (ulid)
  targets (CreditItem[], required)
  externalCashTransactionLocator (ulid)
  validationResult (ValidationResult)
  postedAt (datetime)
  reversalReason (string)
  reversedAt (datetime)
  reversedBy (uuid)
  shortfallCreditLocators (ulid[], required)
  subpayments (SubpaymentResponse[], required)
  paymentMode (Enum normal | aggregate)
  aggregatePaymentLocator (ulid)
  paymentNumber (string)
  anonymizedAt (datetime)
  executionLog (PaymentRequestExecutionLogItem[], required)
  nextRequestTime (datetime)
  retryPlanName (string)

SubpaymentResponse
Properties:
  subpaymentLocator (ulid, required)
  amount (number, required)

CreditItem
Properties:
  containerLocator (ulid, required)
  containerType (Enum invoice | account | subpayment | invoiceItem, required)
  amount (number)

PaymentRequestExecutionLogItem
Properties:
  paymentRequestLocator (ulid, required)
  paymentRequestState (Enum pending | completed | failed | error, required)
  requestTime (datetime)
  transactionId (string)
  note (string)
  data (map<string, object>, required)

PaymentCreateRequest
Properties:
  accountLocator (ulid)
  type (string, required)
  amount (number, required)
  currency (string)
  data (map<string, object>, required)
  targets (CreditItem[], required)
  useDefaultFinancialInstrument (boolean)
  financialInstrumentLocator (ulid)
  transactionMethod (Enum ach | cash | eft | standard | wire)
  transactionNumber (string)
  paymentMode (Enum normal | aggregate)
  retryPlanName (string)

PaymentUpdateRequest
Properties:
  accountLocator (ulid)
  type (string)
  amount (number)
  setData (map<string, object>, required)
  removeData (map<string, object>, required)
  addTargets (CreditItem[], required)
  removeTargets (ulid[], required)
  useDefaultFinancialInstrument (boolean)
  financialInstrumentLocator (ulid)
  transactionMethod (Enum ach | cash | eft | standard | wire)
  transactionNumber (string)
  currency (string)
  paymentMode (Enum normal | aggregate)
  retryPlanName (string)
  nextRequestTime (datetime)

ListPageResponseShortfallCreditResponse
Properties:
  listCompleted (boolean, required)
  items (ShortfallCreditResponse[], required)

ShortfallCreditResponse
Properties:
  locator (ulid, required)
  creditType (Enum creditDistribution | disbursement | payment | subpayment | shortfallWriteOff | writeOff, required)
  shortfallCreditState (Enum draft | distributed | reversed, required)
  currency (string, required)
  amount (number, required)
  createdAt (datetime, required)
  createdBy (uuid, required)
  accountLocator (ulid, required)
  targets (CreditItem[], required)
  parentCreditLocator (ulid, required)
  reversalReason (string)

PaymentListResponse
Properties:
  listCompleted (boolean, required)
  items (PaymentResponse[], required)

PreviewPaymentResponse
Properties:
  locator (ulid, required)
  paymentState (Enum draft | validated | requested | executing | posted | failed | cancelled | reversed | discarded, required)
  type (string, required)
  currency (string, required)
  amount (number, required)
  data (map<string, object>, required)
  createdAt (datetime, required)
  createdBy (uuid, required)
  accountLocator (ulid)
  remainingAmount (number)
  externalCashTransactionLocator (ulid)
  validationResult (ValidationResult)
  postedAt (datetime)
  paymentMode (Enum normal | aggregate)
  aggregatePaymentLocator (ulid)
  targets (CreditItem[], required)
  credits (CreditWithBalance[], required)
  shortfallCredits (ShortfallCreditPreviewResponse[], required)
  subpayments (PreviewPaymentResponse[])
  invoices (ListPageResponseInvoicePaymentPreview)

CreditWithBalance
Properties:
  type (Enum accountCreditBalance | invoiceCreditBalance | cash | creditCash | charge | credit | installmentItem | invoiceItem | account | policy | accountExpenseBalance, required)
  locator (ulid, required)
  amount (number, required)

ShortfallCreditPreviewResponse
Properties:
  locator (ulid, required)
  creditType (Enum creditDistribution | disbursement | payment | subpayment | shortfallWriteOff | writeOff, required)
  shortfallCreditState (Enum draft | distributed | reversed, required)
  currency (string, required)
  amount (number, required)
  accountLocator (ulid, required)
  targets (CreditItem[], required)

ListPageResponseInvoicePaymentPreview
Properties:
  listCompleted (boolean, required)
  items (InvoicePaymentPreview[], required)

InvoicePaymentPreview
Properties:
  locator (ulid, required)
  accountLocator (ulid, required)
  invoiceState (Enum open | settled | discarded, required)
  amount (number)
  remainingAmount (number)