---
title: "Estimate pay run costs"
method: POST
path: "/organisations/{organisationId}/pay-runs/estimate"
tags: ["Organisations", "Pay Runs"]
---

# Estimate pay run costs

`POST /organisations/{organisationId}/pay-runs/estimate`

Estimates costs for a pay run without creating it. Accepts minimal beneficiary details (country code only). Returns detailed fee breakdown, batch assignments, and routing information.

## Path parameters

- `organisationId` string, uuid, required

## Headers

- `Crezco-Version` string

## Request body

- PayRunEstimateResourceRepresentationVersion4 — Model for requesting a pay run estimate with minimal beneficiary details
  - `partnerEntityId` string, nullable — Globally Unique Id of this estimate in the partner system
  - `scheduledExecutionDate` string, date, nullable — <p> The date that this pay run is scheduled to be paid represented in ISO 8601 complete date delimited format (e.g. 2022-05-12 would be 12th May 2022) </p> <p> If omitted, payment will be assumed to be immediate </p>
  - `payerBankAccountId` string, uuid, nullable — The bank account to pay from. For backwards compatibility, this field is still supported. New integrations should use PaymentSourceType and PaymentSourceId instead.
  - `paymentSourceType` 'BankAccount' | 'Card'
  - `paymentSourceId` string, uuid, nullable — ID of the payment source. Optional for estimates — fee calculations do not depend on a specific bank account. Required for actual pay runs if PaymentSourceType is Bank. Optional if PaymentSourceType is Card (for stored cards).
  - `payables` PayRunEstimatePayableResourceRepresentationVersion4[], required — Collection of individual payable items for estimation. For estimates, minimal beneficiary details are required (country code is sufficient).
    - `partnerEntityId` string — Globally Unique Id of this payment in the partner system
    - `recipientAmount` PayableRecipientAmountResourceRepresentationVersion4, required
      - `currencyCode` string, required — <p> <a href="https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes">ISO 4217 alpha-3 Currency Code</a> for this payment (i.e. GBP) </p>
      - `amountInMinorUnits` integer, required — Value of the payment in the minor unit of the currency. For GBP this would be the amount in pence e.g. a money value of £12.75 would have an AmountInMinorUnits of 1275.
    - `beneficiary` PayRunEstimateBeneficiaryResourceRepresentationVersion4, required — Minimal beneficiary details required for pay run estimation. For estimates, only the country is required to calculate routing and fees. Currency is determined from the payable amount.
      - `country` string, required — The ISO 3166-1 alpha-2 Country Code of the beneficiary bank account. This is used to determine payment routing and applicable fees.
      - `bankAccount` BeneficiaryBankAccountResourceRepresentationVersion4
        - `country` string, required — The ISO 3166-1 alpha-2 Country Code of the bank account.
        - `accountCurrency` string, required — The ISO4217:2015 Alpha-3 currency code of the bank account.
        - `accountRoutingName` string, required — The account routing name of the bank account.
        - `gbSortCode` string, nullable — United Kingdom Sort code
        - `gbAccountNumber` string, nullable — United Kingdom Account number
        - `mxClabe` string, nullable — Mexico CLABE
        - `usFedwireAba` string, nullable — United States of America Fedwire routing number
        - `usAchAba` string, nullable — United States of America ACH routing number
        - `auBsb` string, nullable — Australia BSB code
        - `dkBankCode` string, nullable — Denmark Bank code
        - `seBankCode` string, nullable — Sweden Bank code
        - `caTransitNumber` string, nullable — Canada Transit number
        - `caInstitutionNumber` string, nullable — Canada Institution number
        - `cnCnaps` string, nullable — China CNAPS code
        - `sgAccountNumber` string, nullable — Singapore Account number
        - `usAccountNumber` string, nullable — United States of America Account number
        - `idAccountNumber` string, nullable — Indonesia Account number
        - `myAccountNumber` string, nullable — Malaysia Account number
        - `afAccountNumber` string, nullable — Afghanistan Account number
        - `agAccountNumber` string, nullable — Antigua and Barbuda Account number
        - `aiAccountNumber` string, nullable — Anguilla Account number
        - `amAccountNumber` string, nullable — Armenia Account number
        - `aoAccountNumber` string, nullable — Angola Account number
        - `aqAccountNumber` string, nullable — Antarctica Account number
        - `arAccountNumber` string, nullable — Argentina Account number
        - `asAccountNumber` string, nullable — American Samoa Account number
        - `auAccountNumber` string, nullable — Australia Account number
        - `awAccountNumber` string, nullable — Aruba Account number
        - `bbAccountNumber` string, nullable — Barbados Account number
        - `bdAccountNumber` string, nullable — Bangladesh Account number
        - `bfAccountNumber` string, nullable — Burkina Faso Account number
        - `bjAccountNumber` string, nullable — Benin Account number
        - `bmAccountNumber` string, nullable — Bermuda Account number
        - `bnAccountNumber` string, nullable — Brunei Darussalam Account number
        - `boAccountNumber` string, nullable — Bolivia Plurinational State of Account number
        - `bqAccountNumber` string, nullable — Bonaire Sint Eustatius and Saba Account number
        - `bsAccountNumber` string, nullable — Bahamas Account number
        - `btAccountNumber` string, nullable — Bhutan Account number
        - `bvAccountNumber` string, nullable — Bouvet Island Account number
        - `bwAccountNumber` string, nullable — Botswana Account number
        - `bzAccountNumber` string, nullable — Belize Account number
        - `caAccountNumber` string, nullable — Canada Account number
        - `ccAccountNumber` string, nullable — Cocos (Keeling Islands) Account number
        - `cdAccountNumber` string, nullable — Congo the Democratic Republic of the Account number
        - `cfAccountNumber` string, nullable — Central African Republic Account number
        - `cgAccountNumber` string, nullable — Congo Account number
        - `ciAccountNumber` string, nullable — Côte d'Ivoire Account number
        - `ckAccountNumber` string, nullable — Cook Islands Account number
        - `clAccountNumber` string, nullable — Chile Account number
        - `cmAccountNumber` string, nullable — Cameroon Account number
        - `cnAccountNumber` string, nullable — China Account number
        - `coAccountNumber` string, nullable — Colombia Account number
        - `cuAccountNumber` string, nullable — Cuba Account number
        - `cvAccountNumber` string, nullable — Cabo Verde Account number
        - `cwAccountNumber` string, nullable — Curaçao Account number
        - `cxAccountNumber` string, nullable — Christmas Island Account number
        - `djAccountNumber` string, nullable — Djibouti Account number
        - `dkAccountNumber` string, nullable — Denmark Account number
        - `dmAccountNumber` string, nullable — Dominica Account number
        - `dzAccountNumber` string, nullable — Algeria Account number
        - `ecAccountNumber` string, nullable — Ecuador Account number
        - `ehAccountNumber` string, nullable — Western Sahara Account number
        - `erAccountNumber` string, nullable — Eritrea Account number
        - `etAccountNumber` string, nullable — Ethiopia Account number
        - `fjAccountNumber` string, nullable — Fiji Account number
        - `fkAccountNumber` string, nullable — Falkland Islands (Malvinas) Account number
        - `fmAccountNumber` string, nullable — Micronesia Federated States of Account number
        - `gaAccountNumber` string, nullable — Gabon Account number
        - `gdAccountNumber` string, nullable — Grenada Account number
        - `ghAccountNumber` string, nullable — Ghana Account number
        - `gmAccountNumber` string, nullable — Gambia Account number
        - `gnAccountNumber` string, nullable — Guinea Account number
        - `gqAccountNumber` string, nullable — Equatorial Guinea Account number
        - `gsAccountNumber` string, nullable — South Georgia and the South Sandwich Islands Account number
        - `guAccountNumber` string, nullable — Guam Account number
        - `gwAccountNumber` string, nullable — Guinea-Bissau Account number
        - `gyAccountNumber` string, nullable — Guyana Account number
        - `hkAccountNumber` string, nullable — Hong Kong Account number
        - `hkBankCode` string, nullable — Hong Kong Bank code
        - `hmAccountNumber` string, nullable — Heard Island and McDonald Islands Account number
        - `hnAccountNumber` string, nullable — Honduras Account number
        - `htAccountNumber` string, nullable — Haiti Account number
        - `inAccountNumber` string, nullable — India Account number
        - `ioAccountNumber` string, nullable — British Indian Ocean Territory Account number
        - `irAccountNumber` string, nullable — Iran Islamic Republic of Account number
        - `jmAccountNumber` string, nullable — Jamaica Account number
        - `jpAccountNumber` string, nullable — Japan Account number
        - `keAccountNumber` string, nullable — Kenya Account number
        - `kgAccountNumber` string, nullable — Kyrgyzstan Account number
        - `khAccountNumber` string, nullable — Cambodia Account number
        - `kiAccountNumber` string, nullable — Kiribati Account number
        - `kmAccountNumber` string, nullable — Comoros Account number
        - `knAccountNumber` string, nullable — Saint Kitts and Nevis Account number
        - `kpAccountNumber` string, nullable — Korea Democratic People’s Republic of Account number
        - `krAccountNumber` string, nullable — Korea Republic of Account number
        - `kyAccountNumber` string, nullable — Cayman Islands Account number
        - `laAccountNumber` string, nullable — Lao People’s Democratic Republic Account number
        - `lkAccountNumber` string, nullable — Sri Lanka Account number
        - `lrAccountNumber` string, nullable — Liberia Account number
        - `lsAccountNumber` string, nullable — Lesotho Account number
        - `maAccountNumber` string, nullable — Morocco Account number
        - `mgAccountNumber` string, nullable — Madagascar Account number
        - `mhAccountNumber` string, nullable — Marshall Islands Account number
        - `mlAccountNumber` string, nullable — Mali Account number
        - `mmAccountNumber` string, nullable — Myanmar Account number
        - `mnAccountNumber` string, nullable — Mongolia Account number
        - `moAccountNumber` string, nullable — Macao Account number
        - `mpAccountNumber` string, nullable — Northern Mariana Islands Account number
        - `msAccountNumber` string, nullable — Montserrat Account number
        - `mvAccountNumber` string, nullable — Maldives Account number
        - `mwAccountNumber` string, nullable — Malawi Account number
        - `mzAccountNumber` string, nullable — Mozambique Account number
        - `naAccountNumber` string, nullable — Namibia Account number
        - `ncAccountNumber` string, nullable — New Caledonia Account number
        - `neAccountNumber` string, nullable — Niger Account number
        - `nfAccountNumber` string, nullable — Norfolk Island Account number
        - `ngAccountNumber` string, nullable — Nigeria Account number
        - `niAccountNumber` string, nullable — Nicaragua Account number
        - `noAccountNumber` string, nullable — Norway Account number
        - `noBankCode` string, nullable — Norway Bank code
        - `npAccountNumber` string, nullable — Nepal Account number
        - `nrAccountNumber` string, nullable — Nauru Account number
        - `nuAccountNumber` string, nullable — Niue Account number
        - `nzAccountNumber` string, nullable — New Zealand Account number
        - `omAccountNumber` string, nullable — Oman Account number
        - `paAccountNumber` string, nullable — Panama Account number
        - `peAccountNumber` string, nullable — Peru Account number
        - `pfAccountNumber` string, nullable — French Polynesia Account number
        - `pgAccountNumber` string, nullable — Papua New Guinea Account number
        - `phAccountNumber` string, nullable — Philippines Account number
        - `pnAccountNumber` string, nullable — Pitcairn Account number
        - `prAccountNumber` string, nullable — Puerto Rico Account number
        - `pwAccountNumber` string, nullable — Palau Account number
        - `pyAccountNumber` string, nullable — Paraguay Account number
        - `ruAccountNumber` string, nullable — Russian Federation Account number
        - `rwAccountNumber` string, nullable — Rwanda Account number
        - `sbAccountNumber` string, nullable — Solomon Islands Account number
        - `seAccountNumber` string, nullable — Sweden Account number
        - `shAccountNumber` string, nullable — Saint Helena Ascension and Tristan da Cunha Account number
        - `sjAccountNumber` string, nullable — Svalbard and Jan Mayen Account number
        - `slAccountNumber` string, nullable — Sierra Leone Account number
        - `snAccountNumber` string, nullable — Senegal Account number
        - `soAccountNumber` string, nullable — Somalia Account number
        - `srAccountNumber` string, nullable — Suriname Account number
        - `ssAccountNumber` string, nullable — South Sudan Account number
        - `sxAccountNumber` string, nullable — Sint Maarten (Dutch part) Account number
        - `syAccountNumber` string, nullable — Syrian Arab Republic Account number
        - `szAccountNumber` string, nullable — Eswatini Account number
        - `tcAccountNumber` string, nullable — Turks and Caicos Islands Account number
        - `tdAccountNumber` string, nullable — Chad Account number
        - `tfAccountNumber` string, nullable — French Southern Territories Account number
        - `tgAccountNumber` string, nullable — Togo Account number
        - `thAccountNumber` string, nullable — Thailand Account number
        - `tjAccountNumber` string, nullable — Tajikistan Account number
        - `tkAccountNumber` string, nullable — Tokelau Account number
        - `tmAccountNumber` string, nullable — Turkmenistan Account number
        - `toAccountNumber` string, nullable — Tonga Account number
        - `ttAccountNumber` string, nullable — Trinidad and Tobago Account number
        - `tvAccountNumber` string, nullable — Tuvalu Account number
        - `twAccountNumber` string, nullable — Taiwan Province of China Account number
        - `tzAccountNumber` string, nullable — Tanzania United Republic of Account number
        - `ugAccountNumber` string, nullable — Uganda Account number
        - `umAccountNumber` string, nullable — United States Minor Outlying Islands Account number
        - `uyAccountNumber` string, nullable — Uruguay Account number
        - `uzAccountNumber` string, nullable — Uzbekistan Account number
        - `vcAccountNumber` string, nullable — Saint Vincent and the Grenadines Account number
        - `veAccountNumber` string, nullable — Venezuela Bolivarian Republic of Account number
        - `viAccountNumber` string, nullable — Virgin Islands U.S. Account number
        - `vnAccountNumber` string, nullable — Vietnam Account number
        - `vuAccountNumber` string, nullable — Vanuatu Account number
        - `wfAccountNumber` string, nullable — Wallis and Futuna Account number
        - `wsAccountNumber` string, nullable — Samoa Account number
        - `xxAccountNumber` string, nullable — Unknown Country Account number
        - `yeAccountNumber` string, nullable — Yemen Account number
        - `zaAccountNumber` string, nullable — South Africa Account number
        - `zmAccountNumber` string, nullable — Zambia Account number
        - `zwAccountNumber` string, nullable — Zimbabwe Account number
        - `iban` string, nullable — IBAN
        - `swiftBic` string, nullable — SWIFT BIC
        - `inIfsc` string, nullable — India IFSC code
    - `payNetworkType` 'Regular' | 'Priority'
    - `purposeCode` 'Construction' | 'IntellectualProperty' | 'IntercompanyTransfer' | 'RealEstateAndProperty' | 'Expenses' | 'BusinessAndAdvisoryServices' | 'InvestmentActivity' | 'DirectEmployeeSalaries' | 'Insurance' | 'PayingForGoods'
    - `fees` PayableFeesResourceRepresentationVersion4
      - `partnerFixedFee` PayablePartnerFixedFeeResourceRepresentationVersion4
        - `currencyCode` string
        - `amountInMinorUnits` integer
      - `partnerVariableFee` PayablePartnerVariableFeeResourceRepresentationVersion4
        - `currencyCode` string
        - `percentage` number, double, required
        - `isEstimated` boolean, nullable
        - `amountInMinorUnits` integer, nullable
      - `providerFixedFee` PayableProviderFixedFeeResourceRepresentationVersion4
        - `isChargedToEndUser` boolean, required
        - `currencyCode` string
        - `amountInMinorUnits` integer
      - `providerVariableFee` PayableProviderVariableFeeResourceRepresentationVersion4
        - `isChargedToEndUser` boolean, required
        - `percentage` number, double
        - `currencyCode` string
        - `isEstimated` boolean
        - `amountInMinorUnits` integer
        - `amountInMinorUnitsExcludingDiscount` integer, nullable
        - `discountMultiplier` number, double — Discount applied to the original amount, in the form a multiplier. For example, a discount of 10% would be expressed as 0.9.
  - `groups` PayableGroupResourceRepresentationVersion4[], nullable — <p> Optional collection of payable groups for estimation </p> <p> Payables can be grouped by beneficiary. Grouped payables to the same beneficiary will, once paid, appear as a single line item on the payer's bank statements. </p>
    - `groupId` string, uuid
    - `status` 'Unknown' | 'Open' | 'Processed' | 'UserInitiationInProgress' | 'Processing' | 'Cancelling' | 'Draft' — Mapping for https://crezco.readme.io/reference/statuses so we don't expose internal statuses
    - `partnerEntityId` string, required — Globally Unique Id of this payment group in the partner system
    - `partnerPayableIds` PayableIdentifiersResourceRepresentationVersion4[], required — <p> Collection of Payables which should be grouped together </p>
      - `payableId` string, uuid — ID of this payable in the Crezco system
      - `partnerEntityId` string, required — Globally Unique Id of this payable in the partner system
    - `reference` string, required — Customer reference for this payment group
  - `metadata` PayRunMetadataResourceRepresentationVersion4[] — Partner-defined metadata for this estimate
    - `key` string, required
    - `value` string, required

## Response `200`

OK

- PayRunEstimateResponseRepresentationVersion4 — Response model for pay run estimates. This is a strict subset of PayRunResourceRepresentation with identical structure, but payables contain minimal beneficiary details (country and name only). Contains all cost calculations, batches, and metadata.
  - `organisationId` string, uuid — Organisation identifier (read-only)
  - `scheduledExecutionDate` string, date, nullable — <p> The date that this pay run is scheduled to be paid represented in ISO 8601 complete date delimited format (e.g. 2022-05-12 would be 12th May 2022) </p> <p> If omitted, payment will be instructed as soon as it is authorised </p>
  - `paymentSourceType` 'BankAccount' | 'Card'
  - `paymentSourceId` string, uuid, nullable — ID of the payment source. Required if PaymentSourceType is Bank. Optional if PaymentSourceType is Card (for stored cards).
  - `payables` union[] — Collection of individual payable items with estimated costs. Beneficiary details are minimal (country and name only) compared to full pay run response. Includes both regular payables and fee payables when fees are charged separately. Use the $type discriminator field to distinguish between "Payable" and "FeePayable".
    - union — Base representation for payables in pay run estimate responses. Supports polymorphic payables (regular payables and fee payables) via discriminator field.
      - PayRunEstimatePayableResponseRepresentationVersion4 — Base representation for payables in pay run estimate responses. Supports polymorphic payables (regular payables and fee payables) via discriminator field.
        - `$type` string, required
        - `fundingAmount` PayableFundingAmountResourceRepresentationVersion4
          - `currencyCode` string, required — <p> <a href="https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes">ISO 4217 alpha-3 Currency Code</a> for the funding amount (i.e. GBP) </p>
          - `amountInMinorUnits` integer, required — Value of the funding amount e.g. in GBP, this would be pence. A money value of £12.75 would have an AmountInMinorUnits of 1275.
          - `isEstimated` boolean, required — Is this an estimated funding amount?
        - `isLowPriority` boolean — Sets the payment to be processed last in the batch
      - PayRunEstimateFeePayableResponseRepresentationVersion4 — Base representation for payables in pay run estimate responses. Supports polymorphic payables (regular payables and fee payables) via discriminator field.
        - `$type` string, required
        - `fundingAmount` PayableFundingAmountResourceRepresentationVersion4
          - `currencyCode` string, required — <p> <a href="https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes">ISO 4217 alpha-3 Currency Code</a> for the funding amount (i.e. GBP) </p>
          - `amountInMinorUnits` integer, required — Value of the funding amount e.g. in GBP, this would be pence. A money value of £12.75 would have an AmountInMinorUnits of 1275.
          - `isEstimated` boolean, required — Is this an estimated funding amount?
        - `isLowPriority` boolean — Sets the payment to be processed last in the batch
  - `groups` PayRunEstimateGroupResponseRepresentationVersion4[], nullable — <p> Optional collection of payable groups within this estimate </p> <p> Payables can be grouped by beneficiary. Grouped payables to the same beneficiary will, once paid, appear as a single line item on the payer's bank statements. </p> <p> Attempts to group payments with different beneficiaries will cause pay run creation to fail. </p>
    - `partnerEntityId` string — Globally Unique Id of this payment group in the partner system
    - `partnerPayableIds` PayableIdentifiersResourceRepresentationVersion4[] — <p> Collection of Payables which should be grouped together </p>
      - `payableId` string, uuid — ID of this payable in the Crezco system
      - `partnerEntityId` string, required — Globally Unique Id of this payable in the partner system
    - `reference` string — Customer reference for this payment group
  - `batches` PayRunEstimateBatchResponseRepresentationVersion4[] — Collection of batches showing how payments will be grouped and routed
    - `paymentOrder` integer, required — We maintain an explicit ordering of Batches within a pay run, to ensure we have consistent order during "sequential" payment. We don't anticipate needing to re-order existing batches, although it is possible that batches could be appended (i.e. if a batch gets cancelled and multiple replacements created)
    - `groups` PayRunEstimateGroupIdentifiersRepresentationVersion4[], required — Collection of all payment groups within this batch
      - `partnerEntityId` string, nullable, required — Globally Unique Id of this group in the partner system
    - `payables` PayRunEstimatePayableIdentifiersRepresentationVersion4[], required — Collection of all payables within this batch
      - `partnerEntityId` string, nullable, required — Globally Unique Id of this payable in the partner system
  - `summary` PayRunEstimateFeeSummaryResourceRepresentationVersion4 — Summary of all fees across all payables in a pay run estimate.
    - `totalFeesAmount` PayRunEstimateTotalFeesAmountResourceRepresentationVersion4, required — The total fees amount for a pay run estimate.
      - `currencyCode` string, required — <a href="https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes">ISO 4217 alpha-3 Currency Code</a> for the fees amount (i.e. GBP)
      - `amountInMinorUnits` integer, required — Value of the total fees amount in minor units. e.g. in GBP, this would be pence. A money value of £12.75 would have an AmountInMinorUnits of 1275.
      - `isEstimated` boolean, required — Is this an estimated total fees amount? True if any individual fee is estimated.

## Other responses

- `400` — Bad Request
- `401` — You do not have access. Check your API key is correct.
- `403` — You do not have access to this organisation.
- `404` — Not Found
- `406` — The version of the API that you requested is not available. Check your Crezco-Version header. If you omit this header you will use the latest version of the API.
- `429` — You have made too many requests to the API in too short a period. Wait a while and try again.
- `503` — Service Unavailable

---

[API](https://skmtc.net/crezco/apis/payables-api.md) · [All operations](https://skmtc.net/crezco/apis/payables-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/crezco/payables-api/revisions/4427e79fba09/schema)