# Standard payout

Disburse funds to a payout instrument.

Endpoint: POST /payouts/basicDisbursement
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 payout 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"

  - `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.

  - `receivedAt` (string, required)
    A timestamp of receivedAt.

  - `_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)"