Skip to content
APIs/Account Payouts/
Make a single payout

Last updated: 25 June 2026 | Change log

Make a single payout

Make a single payout to an account using our Account Payouts endpoint.

Request

POST https://try.access.worldpay-bsh.securedataplatform.com/accountPayouts


Account Payout request example

application/json
{
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "value": {
      "sourceCurrency": "GBP",
      "sourceAmount": 0,
      "targetCurrency": "EUR",
      "targetAmount": 199.99
    },
    "narrative": {
      "line1": "PushtoAccount with Worldpay"
    },
    "purposeOfPayment": {
      "code": "WPREMT",
      "description": "Money Remittance"
    },
    "countryCode": "GB",
    "transactionType": "customerToCustomer",
    "quoteId": "",
    "expandableKeyValuePairs": {
      "remitterSourceOfIncome": "salary",
      "intermediaryBankSwiftBic": "BARCGB22"
    },
    "beneficiaryBankDetails": {
      "accountType": "checking",
      "accountNumber": "12345677",
      "iban": "GB41CITI18500818404062",
      "branchCode": "",
      "bankCode": "185008",
      "swiftBic": "CITIGB2L",
      "bankName": "Citibank London",
      "address": {
        "address1": "25 Canada Square",
        "address2": "",
        "city": "London",
        "state": "",
        "postalCode": "E14 5LB",
        "countryCode": "GB"
      }
    },
    "parties": [
      {
        "partyType": "beneficiary",
        "personalDetails": {
          "type": "Person",
          "title": "Mr",
          "firstName": "John",
          "middleName": "",
          "lastName": "Doe",
          "dateOfBirth": "1993-12-31",
          "email": "john@domain.com",
          "phones": [
            {
              "number": "7777777777",
              "prefix": "44"
            }
          ],
          "identityDocuments": [
            {
              "type": "passport",
              "number": "E1122234",
              "issuingInstitution": "Mayor of London",
              "issuingCountry": "GB",
              "validFrom": "2013-05-22",
              "validTo": "2014-05-21"
            }
          ]
        },
        "address": {
          "address1": "25 Walbrook",
          "address2": "",
          "city": "London",
          "state": "",
          "postalCode": "EC4N 8AF",
          "countryCode": "GB",
          "type": "home",
          "residentialStatus": "resident"
        }
      },
      {
        "partyType": "payer",
        "customerReference": "Account123456",
        "personalDetails": {
          "type": "Person",
          "title": "Ms",
          "firstName": "Maria",
          "middleName": "",
          "lastName": "Doe",
          "dateOfBirth": "1994-05-12",
          "email": "maria@domain.com",
          "phones": [
            {
              "number": "7888888888",
              "prefix": "44"
            }
          ],
          "identityDocuments": [
            {
              "type": "passport",
              "number": "E1122277",
              "issuingInstitution": "Mayor of London",
              "issuingCountry": "GB",
              "validFrom": "2017-06-15",
              "validTo": "2027-06-14"
            }
          ]
        },
        "address": {
          "address1": "De Entree 248",
          "address2": "",
          "city": "Amsterdam",
          "state": "",
          "postalCode": "1101 EE",
          "countryCode": "NL",
          "type": "home",
          "residentialStatus": "resident"
        }
      }
    ]
  },
  "transactionReference": "ABC123456"
}

Request schema

merchantobject(WP.FXT.SinglePayoutApi.Domain.Payout.V3.Models.Merchant)
instructionobject(WP.FXT.SinglePayoutApi.Domain.Payout.V3.Models.PayoutInstruction)
transactionReferencestring[ 6 .. 50 ]required

Reference for the payout request provided by you. We recommend you specify a value which is unique across all of your payouts to ensure you receive the right data throughout the payout lifecycle. <a href="/products/marketplaces/coverage/bank/additionalinfo#special-characters">Special characters</a> are allowed.

notificationUrlstring or null<= 250

Currently not in use.

Response

The response to your Payout request is the same for standard Account Payout and Marketplaces flows.

Success example

{
  "payoutRequestId": "PZ000EC4",
  "idempotencyKey": "idopKey",
  "entity": "default"
}

Response schema

payoutRequestIdstring

Payout Request ID associated with a payout submitted through our Account Payouts API. PN/PZ/PO prefix plus 6 characters.

idempotencyKeyany

Unique reference from the request header of the same name.

entitystring

Your entity reference created as part of on-boarding. Used to route the request in Access Worldpay.

You can see more errors and responses in our API reference.

Payout routing

We offer intelligent routing with built-in redundancy to maximize payout success rates. By default, we handle routing and fail-over automatically. However, if you want full control over how payouts are routed and how failover occurs, you can use the optional properties source.accountNumber and channel in your payout request payload.

  • source.accountNumber - decides which of your merchant accounts (ledgers) is debited for the payout
  • channel - defines which payout routes we should use and in what priority order

Both properties are optional, but using them gives you greater control over:

  • routing logic
  • fail-over behavior in case of partner issues or incorrect beneficiary data

Control the funding source with source.accountNumber

By default we set up each merchant account with one account per currency. If you don't specify the source.accountNumber we debit the default account for the payout currency.

If you want multiple ledgers for the same currency, you must specify the source.accountNumber in the payout request. We can configure these accounts during onboarding or later through our support team.

Important

Additional accounts require unique funding references for each ledger. The account number format is 16 digits. You can retrieve account details and balances via the Balance API. When you specify source.accountNumber we will:

  • validate ownership of the account
  • ensure the account currency matches the sourceCurrency in your request

Control routing and failover with channel

If you do not specify a channel we use standard routing and failover logic.

Use the channel property to define:

  • which routes we can use
  • the priority order for failover

Available channels for account payouts

  • ach sd
  • ach nd
  • wire
  • dom wire
  • instant
  • arbitrum
  • base
  • binance
  • ethereum
  • polygon
  • solana
  • paypal
Note

Your available channels depend on your onboarding configuration. Contact your Implementation Manager for further information.

Examples

ChannelDescription
Single channelinstantWe attempt real-time payout only. If it fails, funds are reversed to your ledger.
Multiple channels with priorityinstant, ach sdWe try real-time first, then ACH same day if real-time fails.
Reverse priorityach sd, instantWe try ACH same day first, then real-time

You can be flexible based on your payout model and SLAs.

Future enhancements

Coming soon

  • specify the delivery date in your request
  • automatic failover to faster routes if cut-off times are missed

Next steps

Event webhooks
Testing