# Fast Access payout

Disburse funds to a payout instrument using Fast Access.

Endpoint: POST /payouts/fastAccess
Version: 4
Security: BasicAuth

## Request fields (application/vnd.worldpay.payouts-v4+json):

  - `instruction` (object, required)
    An object that contains all the information related to your payout request.

  - `instruction.narrative` (object, required)
    An object that contains identification and further details of the merchant.

  - `instruction.narrative.line1` (string, required)
    First line of text that appears on your customer's statement.

  - `instruction.narrative.line2` (string)
    Second line of text that appears on your customer's statement.

  - `instruction.payoutInstrument` (object, required) — one of (discriminator: type):
    An object that contains your customer's payout type.
    - card/plain:
      - `type` (string, required)
      - `cardNumber` (string, required)
        Your customer's payout card number.
      - `cardExpiryDate` (object, required)
        The expiry date of your customer's card. Must be a date in the future.
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `cardHolderName` (string)
        The name on your customer's card. This is a mandatory field for US domiciled merchants only, however it is recommended that you supply this to improve authorization rates. If not supplied, the default is "Not Supplied". Must not contain only numeric characters.
      - `billingAddress` (object)
        An object containing the billing address information. This is a mandatory field for US domiciled merchants only, however we recommend you provide billingAddress fields for all Payout requests.
      - `billingAddress.countryCode` (string, required)
        Must be provided in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).
      - `billingAddress.postalCode` (string, required)
      - `billingAddress.address1` (string)
        First line of the address. Required if city is provided.
      - `billingAddress.address2` (string)
        Second line of the address.
      - `billingAddress.address3` (string)
        Third line of the address.
      - `billingAddress.city` (string)
        City. Required if address1 is provided.
      - `billingAddress.state` (string)
        Billing contact state code.

 * For North America, you must use the two-letter state abbreviations as defined in the latter part of the [ISO 3166-2 standard](https://www.iso.org/obp/ui/#iso:code:3166:US).
 * For all other regions and provinces around the world, this is a free text field.

 Example:

 * AZ

 * Cambridgeshire
    - card/tokenized:
      - `type` (string, required)
      - `href` (string, required)
        An object that contains your link to an Access Token.
    - card/networkToken:
      - `type` (string, required)
      - `tokenNumber` (string, required)
        The network payment token number.
        Example: "4444333322221111"
      - `expiryDate` (object, required)
        The expiry date of the network token. Must be a date in the future.
      - `expiryDate.month` (integer, required)
      - `expiryDate.year` (integer, required)
    - card/networkToken+applepay:
      - `type` (string, required)
      - `dpan` (string, required)
        The device primary account number (DPAN).
        Example: "4444333322221111"
      - `cardExpiryDate` (object, required)
        The expiry date of the payout DPAN. Must be a date in the future.
      - `cardExpiryDate.month` (integer, required)
      - `cardExpiryDate.year` (integer, required)
      - `billingAddress` (object)
        An object containing the billing address information. This is a mandatory field for US domiciled merchants only, however we recommend you provide billingAddress fields for all Payout requests.
      - `billingAddress.countryCode` (string, required)
        Must be provided in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).
      - `billingAddress.postalCode` (string, required)
      - `billingAddress.address1` (string)
        First line of the address. Required if city is provided.
      - `billingAddress.address2` (string)
        Second line of the address.
      - `billingAddress.address3` (string)
        Third line of the address.
      - `billingAddress.city` (string)
        City. Required if address1 is provided.
      - `billingAddress.state` (string)
        Billing contact state code.

 * For North America, you must use the two-letter state abbreviations as defined in the latter part of the [ISO 3166-2 standard](https://www.iso.org/obp/ui/#iso:code:3166:US).
 * For all other regions and provinces around the world, this is a free text field.

 Example:

 * AZ

 * Cambridgeshire
      - `cardHolderName` (string)
        The name on your customer's card. This is a mandatory field for US domiciled merchants only, however it is recommended that you supply this to improve authorization rates. If not supplied, the default is "Not Supplied". Must not contain only numeric characters.

  - `instruction.value` (object, required)
    An object that contains payout amount and currency.

  - `instruction.value.amount` (integer, required)
    The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.
    Example: 250

  - `instruction.value.currency` (string, required)
    The three character currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes).
    Example: "USD"

  - `instruction.routing` (object)

  - `instruction.routing.preferredCardBrand` (string)
    Specifies the preferred card brand to be used for routing the transaction, where a card supports more than one routing option. If the supplied card brand is not supported by the card payout instrument, we will route the card payout to the available route. 
 Available for US-domiciled merchants only.
    Enum: "maestro", "mastercard"

  - `instruction.routing.fallbackToBasic` (string)
    We check whether the supplied card supports Visa Direct / Mastercard Send disbursements. By default, we will fall back to a [basic disbursement](/products/card-payouts/payouts#standard-payout) where we do not get a response from the scheme. Select this option to disable this behavior and instead receive an error.
    Enum: "disabled", "enabled"

  - `merchant` (object, required)
    An object that contains information about the merchant.

  - `merchant.entity` (string, required)
    Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.
    Example: "default"

  - `transactionReference` (string, required)
    A unique reference generated by you, used to identify a payout throughout its lifecycle.

## Response 201 fields (application/vnd.worldpay.payouts-v4+json):

  - `outcome` (string, required)
    Outcome of payouts request.
    Enum: "requested", "pending", "approved", "disbursed", "refused", "error", "requestReceived", "inReview"

  - `scheme` (object)

  - `scheme.name` (string, required)
    The name of the card scheme that was used to process your payout request
    Enum: "visa", "mastercard"

  - `scheme.reference` (string)
    The reference returned by the card scheme for your payout request.
    Example: "520000000001"

  - `receivedAt` (string, required)
    A timestamp of when the payout request was received.

  - `_links` (object, required)

  - `_links.payouts:payout` (object)
    Your card payout resource.

  - `_links.payouts:payout.href` (string)
    Your card payout resource.
    Example: "https://try.access.worldpay.com/payouts/Mjp4VmNLR1YyYzJTYWtvTkdRS25adStRPT06QEVTL0NCRy9QS0NTMVBhZGRpfmc6a0NZTDVlQno3bDRRNWJtdGlpTlNpTlgtYnAFRmEwVFA2eFhBWlRyREtPRG1xdUJhE0JKamh6dmJhV1p2dmlOdlJBTkcrZXhIQmIrOEg3V2ZxajVud2hkQWFIMFCkQjVrencyc4VGL3gZU0k9"

## Response 400 fields (application/vnd.worldpay.payouts-v4+json):

  - `errorName` (string)
    Error name
    Example: "bodyDoesNotMatchSchema"

  - `message` (string)
    Error message
    Example: "There were field validation errors. The errors that occurred are within the validationErrors array."

  - `validationErrors` (array)
    Further error details

  - `validationErrors.errorName` (string)
    Example: "fieldHasInvalidValue"

  - `validationErrors.message` (string)
    Example: "The identified field does not contain an expected value. This field must contain one of the expected valid values."

  - `validationErrors.jsonPath` (string)
    Example: "$.instruction.value.currency"

## Response 422 fields (application/vnd.worldpay.payouts-v4+json):

  - `errorName` (string)
    Error name
    Example: "fieldHasInvalidValue"

  - `message` (string)
    Error message
    Example: "Your merchant boarding process has not enabled payouts for this merchant entity. Please contact support, or use a valid entity."

  - `jsonPath` (string)
    Example: "$.merchant.entity"

## Response 500 fields (application/vnd.worldpay.payouts-v4+json):

  - `errorName` (string)
    Error name
    Example: "internalErrorOccurred"

  - `message` (string)
    Error message
    Example: "An error occurred within the service (potentially due to an interaction with a downstream service)"