Payouts

Creates a new payout.

Swagger narrows payout.currency to the currencies currently configured for holding accounts and payout.fxDestinationCurrency to the currencies currently configured for Banking Circle FX support. The authoritative lists for the current environment are exposed by GET /api/v1/currencies.

<b>Authorization</b>: End user or Merchant token is required.

<b>User permissions required</b>: CanCreatePayouts

post/api/v1/payouts

Request

Base URL: https://api.nofrixion.com
URL: https://api.nofrixion.com/api/v1/payouts
Auth: API key in header Authorization

Request body

accountIDstring uuid required

The ID of the source account for the payout.

The type of account identifier to use for the payout destination.

descriptionstring nullable

currency'EUR' | 'GBP' | 'USD' required

Source payout currency. Swagger narrows this property to the currencies currently configured for holding accounts. The authoritative list for the current environment is exposed by GET /api/v1/currencies?capability=Holding.

amountnumber double nullable

Optional but one of Amount or FxDestinationAmount must be set.

For single currency payouts this property is mandatory.
For multi-currency payouts this property is optional. If FxDestinationAmount is set this field must be set to 0 and it will be dynamically adjusted based on the FX rate.

yourReferencestring nullable

The Your reference field is an optional field that gets set locally on the payer's transaction record. It does not get sent out through the payment network. The maximum length for the field is 256 characters. An empty value is also supported. Supported chracters: a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space In addition the field cannot start with a : or - character.

theirReferencestring nullable

The Their reference field gets sent to the payee and appears on their transaction record. The maximum length for the field varies depending on the payment network. For SEPA (Euro) it is 140 characters. For Faster Payments (GBP) it is 18 characters. a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space In addition the field cannot start with a : or - character.

invoiceIDstring nullable

Optional field to associate the payout with the invoice from an external application such as Xero. The InvoiceID needs to be unique for each account.

allowIncompleteboolean

If set to true the payout will get created even if the business validation rules fail. The basic data validation rules must still pass. The original purpose of this flag was to allow payouts to be created from i3rd party applications, such as Xero, that may not have things like an IBAN set for a supplier. The missing information must be filled, either by an update from the 3rd party application, or manually, before the payout can be submitted for processing.

tagIdsstring[] nullable

An optional list of tag ids to add to the payout.

scheduledboolean

Should this payout be scheduled for a future date?

scheduleDatestring date-time nullable

The date the payout should be submitted.

beneficiaryIDstring uuid nullable

Optional. The ID of the beneficiary to use for the payout destination.

batchPayoutIDstring uuid nullable

The ID of the batch payout this payout is part of.

topupPayrunIDstring uuid nullable

Optional, if set it indicates that this payout will be used to top up a payment account for a pay run by an internal transfer.

paymentRail'Default' | 'SEPA_CT' | 'SEPA_INST' | 'TARGET2'

Optional field to indicate the preferred payment rail intent for the payout. If not set, provider default routing logic is applied.

chargeBearer'Default' | 'BEN' | 'OUR' | 'SHA'

Optional field to set who should pay any fees for the payout. Typically only used for international payments and ignored for SEPA and Faster Payments.

fxDestinationCurrency'AED' | 'AUD' | 'CAD' | 'CHF' | 'CNH' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HKD' | 'HUF' | 'ILS' | 'JPY' | 'MXN' | 'NOK' | 'NZD' | 'PLN' | 'RON' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'USD' | 'ZAR' nullable

Optional. For an FX payout this is the currency that the beneficiary should be sent. Swagger narrows this property to the currencies currently configured for FX conversion support. The authoritative list for the current environment is exposed by GET /api/v1/currencies?capability=FxConversion.

fxDestinationAmountnumber double nullable

Optional but one of Amount or FxDestinationAmount must be set. If specified this will be the amount sent to the payee. The payout's Amount will be dynamically adjusted based on this amount and the FX rate.

fxUseDestinationAmountboolean

For a multi-currency payout this indicates how the Amount and FxDestinationAmount are treated. If true the FxDestinationAmount is authoritative and the Amount is set based on the FxRate. If false then the Amount is authoritative and the FxDestinationAmount is set based on the Amount and FxRate.

fxQuoteIDstring nullable

Optional. For multi-currency payouts this is the ID of a held rate that can be used for the FX conversion. If left empty the mid-market FX rate will be used.

tagsstring[] nullable

Optional list of tag names to add to the payout.

Example request

{
  "type": "IBAN"
}

Response

idstring uuid

The ID for the payout.

payrunIDstring uuid nullable

The ID of the payrun that this payout is associated with.

accountIDstring uuid

Gets or Sets Account Id of sending account

merchantIDstring uuid

The ID of the merchant that owns the account.

userIDstring uuid nullable

Gets or Sets User ID of who created the payout request

approverIDstring uuid nullable

Gets the User ID of person that approved the payout.

topupPayrunIDstring uuid nullable

The ID of a payrun that needs an account top up. Payouts can be used to top up payrun accounts.

type'Unknown' | 'SCAN' | 'IBAN' | 'DD' | 'BTC' | 'BIC'

Gets or Sets payout type

descriptionstring nullable

Gets or Sets description of payout request

currency'NONE' | 'GBP' | 'EUR' | 'USD' | 'AUD' | 'BGN' | 'CAD' | 'CZK' | 'DKK' | 'HUF' | 'ISK' | 'CHF' | 'NOK' | 'PLN' | 'RON' | 'AED' | 'CNH' | 'HKD' | 'ILS' | 'JPY' | 'MXN' | 'NZD' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'ZAR' | 'BTC'

Gets or Sets Currency of payout request

amountnumber double

Gets or Sets payout amount

amountMinorUnitsinteger

The payout amount expressed in the currency’s minor units (e.g. cents, pence).

formattedAmountstring nullable

Currency and formatted amount string.

yourReferencestring nullable

Gets or Sets your reference ID

theirReferencestring nullable

Gets or Sets destination reference ID

canProcessboolean

If set to true indicates the payout has been flagged as safe to process after transaction monitoring.

batchPayoutIDstring uuid nullable

The ID of the batch the payout is associated with.

merchantTokenDescriptionstring nullable

Gets or Sets the status of payout request

currentUserIDstring uuid nullable

The ID of the user that requested access to the PayOut record. Note this is NOT necessarily the user that created it.

approvePayoutUrlstring nullable

This field is used when returning an payout record to a client. If set it holds the URL the user needs to visit in order to complete a strong authentication check in order to approve the payout.

createdBystring nullable

createdByEmailAddressstring nullable

insertedstring date-time

lastUpdatedstring date-time

sourceAccountCurrency'NONE' | 'GBP' | 'EUR' | 'USD' | 'AUD' | 'BGN' | 'CAD' | 'CZK' | 'DKK' | 'HUF' | 'ISK' | 'CHF' | 'NOK' | 'PLN' | 'RON' | 'AED' | 'CNH' | 'HKD' | 'ILS' | 'JPY' | 'MXN' | 'NZD' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'ZAR' | 'BTC'

The currency of the source account.

sourceAccountNamestring nullable

The name of the account the payout is being made from.

sourceAccountIbanstring nullable

The IBAN of the account the payout is being made from.

sourceAccountNumberstring nullable

The account number of the account the payout is being made from.

sourceAccountSortcodestring nullable

The sort code of the account the payout is being made from.

sourceAccountBicstring nullable

The BIC of the account the payout is being made from.

sourceAccountAvailableBalancenumber double nullable

The available balance of the account the payout is being made from.

sourceAccountAvailableBalanceMinorUnitsinteger nullable

The available balance of the source account expressed in the currency’s minor units (e.g. cents, pence).

formattedSourceAccountAvailableBalancestring nullable

The available balance of the account the payout is being made from.

invoiceIDstring nullable

Optional field to associate the payout with the invoice from an external application such as Xero. The InvoiceID needs to be unique for each account.

scheduledboolean nullable

Should this payout be scheduled for a future date?

scheduleDatestring date-time nullable

The date the payout should be submitted.

formattedScheduleDayOnlystring nullable

formattedSchedulestring nullable

authorisersRequiredCountinteger

The number of authorisers required for this payout. Is determined by business settings on the source account and/or merchant.

authorisersCompletedCountinteger

The number of distinct authorisers that have authorised the payout.

canAuthoriseboolean

True if the payout can be authorised by the user who loaded it.

canUpdateboolean

True if the payout can be updated by the user who loaded it.

hasCurrentUserAuthorisedboolean

True if the payout was loaded for a user and that user has already authorised the latest version of the payout.

authenticationMethodsstring[] nullable

A list of authentication types allowed to authorise the payout.

payrunNamestring nullable

The name of the payrun that this payout is associated with.

The usptream payment processor for the payout.

paymentRail'Default' | 'SEPA_CT' | 'SEPA_INST' | 'TARGET2'

Optional field to indicate the preferred payment rail intent for the payout. If not set, provider default routing logic is applied.

noncestring nullable

chargeBearer'Default' | 'BEN' | 'OUR' | 'SHA'

Optional field to set who should pay any fees for the payout. Typically only used for international payments and ignored for SEPA and Faster Payments.

isSubmittedboolean

Indicates whether the payout has been submitted for processing. Once submitted the payout amount is reserved until the payout is marked as failed or settled.

isFailedboolean

Set to true if a submitted payout subsequently fails. If a payout fails the amount is remvoed from the account's reserved balance.

isSettledboolean

Set to true if a payout was successfully processed and the corresponding transaction has been recorded on the ledger.

fxDestinationCurrency'NONE' | 'GBP' | 'EUR' | 'USD' | 'AUD' | 'BGN' | 'CAD' | 'CZK' | 'DKK' | 'HUF' | 'ISK' | 'CHF' | 'NOK' | 'PLN' | 'RON' | 'AED' | 'CNH' | 'HKD' | 'ILS' | 'JPY' | 'MXN' | 'NZD' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'ZAR' | 'BTC' nullable

For an FX payout this is the currency to send to the beneficiary.

fxRatenumber double nullable

For an FX payout this is the exchange rate to use for the payout.

fxDestinationAmountnumber double nullable

If specified this will be the amount sent to the payee. The payout's Amount will be dynamically adjusted based on this amount and the FX rate.

fxUseDestinationAmountboolean

fxDestinationAmountMinorUnitsinteger nullable

The payout FxDestinationAmount expressed in the currency’s minor units (e.g. cents, pence).

formattedFxDestinationAmountstring nullable

FX destination currency and amount formatted string.

fxQuoteIDstring nullable

Optional. For multi-currency payouts this is the ID of the held rate that was set for the FX conversion. If empty it indicates the mid-market FX rate is being be used.

fxQuoteExpiresAtstring date-time nullable

If an FX held rate quote ID is being used this is the time the quote expires.

transactedFxRatenumber double nullable

The actual FX rate applied during settlement, as recorded on the associated transaction. Null if the payout has no settled FX transaction.

transactedFxAmountnumber double nullable

The actual amount received by the beneficiary in NoFrixion.MoneyMoov.Models.Payout.FxDestinationCurrency, as recorded on the settled transaction. When NoFrixion.MoneyMoov.Models.Payout.FxUseDestinationAmount is true the beneficiary's received amount was fixed at creation, so this should closely match NoFrixion.MoneyMoov.Models.Payout.FxDestinationAmount. When NoFrixion.MoneyMoov.Models.Payout.FxUseDestinationAmount is false the debit amount was fixed, so this may differ from the estimated NoFrixion.MoneyMoov.Models.Payout.FxDestinationAmount due to rate movement between quote and settlement. Null if the payout has no settled FX transaction.

transactedAmountnumber double nullable

The actual amount debited from the account in NoFrixion.MoneyMoov.Models.Payout.Currency, as recorded on the settled transaction. When NoFrixion.MoneyMoov.Models.Payout.FxUseDestinationAmount is false the debit amount was fixed at creation, so this should closely match NoFrixion.MoneyMoov.Models.Payout.Amount. When NoFrixion.MoneyMoov.Models.Payout.FxUseDestinationAmount is true the beneficiary's received amount was fixed, so this may differ from the estimated NoFrixion.MoneyMoov.Models.Payout.Amount due to rate movement between quote and settlement. Null for non-FX payouts and payouts with no settled transaction.

isArchivedboolean

Indicates whether the payout is archived.

Changes

No recorded changes to this endpoint across all 2 revisions of this API.