The Payouts API from Worldpay — 4 operation(s) for payouts.
openapi: 3.0.1
info:
title: 3DS 3DS actions Payouts API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Payouts
paths:
/payouts/{resource}:
get:
summary: Retrieve payout details
description: 'Retrieve the details of an existing basic disbursement or Fast Access payout.
'
operationId: getPayoutsDetails
parameters:
- name: resource
in: path
description: The `payouts:payout` href value returned in the response to your basic disbursement or Fast Access payout request.
required: true
schema:
type: string
responses:
'200':
description: Payout resource.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_payouts_200_response'
examples:
'Basic Disbursement: Successful resource retrieval with outcome requestReceived':
description: 'Basic Disbursement: Successful resource retrieval with outcome requestReceived'
value:
outcome: requestReceived
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Basic Disbursement: Successful resource retrieval with outcome refused':
description: 'Basic Disbursement: Successful resource retrieval with outcome refused'
value:
outcome: refused
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Basic Disbursement: Successful resource retrieval with outcome error':
description: 'Basic Disbursement: Successful resource retrieval with outcome error'
value:
outcome: error
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access Payout: Successful resource retrieval with outcome requested':
description: 'Fast Access Payout: Successful resource retrieval with outcome requested'
value:
outcome: requested
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
payouts:update:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access Payout: Successful resource retrieval with outcome pending':
description: 'Fast Access Payout: Successful resource retrieval with outcome pending'
value:
outcome: pending
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
payouts:update:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access Payout: Successful resource retrieval with outcome approved':
description: 'Fast Access Payout: Successful resource retrieval with outcome approved'
value:
outcome: approved
receivedAt: '2023-09-01T10:37:36.923Z'
scheme:
name: visa
reference: '400200004000001'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
payouts:update:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access Payout: Successful resource retrieval with outcome disbursed':
description: 'Fast Access Payout: Successful resource retrieval with outcome disbursed'
value:
outcome: disbursed
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access Payout: Successful resource retrieval with outcome refused':
description: 'Fast Access Payout: Successful resource retrieval with outcome refused'
value:
outcome: refused
receivedAt: '2023-09-01T10:37:36.923Z'
scheme:
name: visa
reference: '400200004000009'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access Payout: Successful resource retrieval with outcome error':
description: 'Fast Access Payout: Successful resource retrieval with outcome error'
value:
outcome: error
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access Payout: Successful resource retrieval with outcome inReview':
description: 'Fast Access Payout: Successful resource retrieval with outcome inReview'
value:
outcome: inReview
receivedAt: '2023-09-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'401':
description: Access to the requested resource has been denied. This may occur if your entity is not configured for card payouts.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_payouts_401_response'
examples:
Access denied:
description: Access to the requested resource has been denied.
value:
errorName: accessDenied
message: Access to the requested resource has been denied
'404':
description: We could not find the requested resource. Please check the `path` and try again.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_payouts_404_response'
examples:
Resource not found:
description: We could not find the requested resource.
value:
errorName: resourceNotFound
message: The resource you are trying to access does not exist.
tags:
- Payouts
/payouts/query:
get:
summary: Retrieve payout details from a historic resource
description: 'Query by transaction reference and entity to retrieve a payout.
'
operationId: queryPayouts
parameters:
- name: transactionReference
in: query
description: A unique reference generated by you, used to identify a payout throughout its lifecycle.
required: true
schema:
type: string
example: '12345'
- name: entity
in: query
description: merchant entity
required: true
schema:
type: string
example: default
responses:
'200':
description: Returns a payout resource, provided one matches the transaction and entity references.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_query_200_response'
examples:
'Basic Disbursement: An existing resource is retrieved with outcome ''requestReceived''':
description: 'Basic Disbursement: An existing resource is retrieved with outcome ''requestReceived'''
value:
outcome: requestReceived
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Basic Disbursement: An existing resource is retrieved with outcome ''refused''':
description: 'Basic Disbursement: An existing resource is retrieved with outcome ''refused'''
value:
outcome: refused
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Basic Disbursement: An existing resource is retrieved with outcome ''error''':
description: 'Basic Disbursement: An existing resource is retrieved with outcome ''error'''
value:
outcome: error
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access: An existing resource is retrieved with outcome ''requested''':
description: 'Fast Access: An existing resource is retrieved with outcome ''requested'''
value:
outcome: requested
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access: An existing resource is retrieved with outcome ''pending''':
description: 'Fast Access: An existing resource is retrieved with outcome ''pending'''
value:
outcome: pending
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access: An existing resource is retrieved with outcome ''approved''':
description: 'Fast Access: An existing resource is retrieved with outcome ''approved'''
value:
outcome: approved
receivedAt: '2025-08-01T10:37:36.923Z'
scheme:
name: visa
reference: '400200004000001'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access: An existing resource is retrieved with outcome ''disbursed''':
description: 'Fast Access: An existing resource is retrieved with outcome ''disbursed'''
value:
outcome: disbursed
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access: An existing resource is retrieved with outcome ''refused''':
description: 'Fast Access: An existing resource is retrieved with outcome ''refused'''
value:
outcome: refused
receivedAt: '2025-08-01T10:37:36.923Z'
scheme:
name: visa
reference: '400200004000009'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access: An existing resource is retrieved with outcome ''error''':
description: 'Fast Access: An existing resource is retrieved with outcome ''error'''
value:
outcome: error
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'Fast Access: An existing resource is retrieved with outcome ''inReview''':
description: 'Fast Access: An existing resource is retrieved with outcome ''inReview'''
value:
outcome: inReview
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'400':
description: We could not process the request due to a client error.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_payouts_400_response'
examples:
Query parameters missing:
description: We could not process the request due to a client error. For example, one or more of the mandatory query parameters (`transactionReference` and `entity`) are missing.
value:
errorName: urlContainsInvalidValue
message: The URL contains a value or values that are invalid.
validationErrors:
- errorName: fieldIsMissing
message: A query parameter in the request is missing. This query parameter is a mandatory element of the request. The name of the query parameter is in the queryParameter field.
queryParameter: transactionReference
'401':
description: Access to the requested resource has been denied. This may occur if your entity is not configured for card payouts.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_payouts_401_response'
examples:
Access denied:
description: Access to the requested resource has been denied.
value:
errorName: accessDenied
message: Access to the requested resource has been denied
'404':
description: We could not find the requested resource. Please check the `transactionReference` query parameter and try again.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_payouts_404_response'
examples:
Resource not found:
description: We could not find the requested resource.
value:
errorName: resourceNotFound
message: The resource you are trying to access does not exist.
'422':
description: The request was syntactically valid, but couldn't be processed. For example, your merchant entity is not configured to process card payouts.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_basicDisbursement_422_response'
examples:
Could not process request:
description: Card payouts not enabled
value:
errorName: fieldHasInvalidValue
message: Your merchant boarding process has not enabled payouts for this merchant entity. Please contact support, or use a valid entity.
jsonPath: $.merchant.entity
tags:
- Payouts
/payouts/basicDisbursement:
post:
summary: Standard payout
description: 'Disburse funds to a payout instrument.
'
operationId: basicDisbursement
requestBody:
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_basicDisbursement'
examples:
Successful Basic Disbursement:
description: Successful Basic Disbursement
value:
merchant:
entity: default
instruction:
value:
amount: 300
currency: GBP
payoutInstrument:
type: card/plain
cardHolderName: Sherlock Holmes
cardExpiryDate:
month: 1
year: 2025
cardNumber: '4444333322221111'
billingAddress:
address1: address1
address2: address2
address3: address3
postalCode: postalCode
city: city
state: state
countryCode: GB
narrative:
line1: STATEMENT
line2: OPTIONAL
transactionReference: transaction-ref
Unsuccessful Payout request:
description: Unsuccessful Payout request
value:
merchant:
entity: default
instruction:
value:
amount: 300
currency: GBP
payoutInstrument:
type: card/plain
cardHolderName: Sherlock Holmes
cardExpiryDate:
month: 1
year: 2025
cardNumber: '4444333322221111'
billingAddress:
address1: address1
address2: address2
address3: address3
postalCode: postalCode
city: city
state: state
countryCode: GB
narrative:
line1: STATEMENT
line2: OPTIONAL
transactionReference: transaction-ref
Successful Basic Disbursement to a token:
description: Successful Basic Disbursement to a token
value:
merchant:
entity: default
instruction:
value:
amount: 300
currency: GBP
payoutInstrument:
type: card/tokenized
href: https://tokens/token
narrative:
line1: STATEMENT
line2: OPTIONAL
transactionReference: transaction-ref
Successful Basic Disbursement to a networkToken:
description: Successful Basic Disbursement to a networkToken
value:
merchant:
entity: default
instruction:
value:
amount: 300
currency: GBP
payoutInstrument:
type: card/networkToken
cardHolderName: Sherlock Holmes
expiryDate:
month: 12
year: 2029
tokenNumber: '5555555555554444'
billingAddress:
address1: address1
address2: address2
address3: address3
postalCode: AB1 2CD
city: city
state: state
countryCode: GB
narrative:
line1: STATEMENT
line2: OPTIONAL
transactionReference: transaction-ref
Successful Basic Disbursement to a decrypted applepay token:
description: Successful Basic Disbursement to a decrypted applepay token
value:
merchant:
entity: default
instruction:
value:
amount: 300
currency: GBP
payoutInstrument:
type: card/networkToken+applepay
cardHolderName: Sherlock Holmes
cardExpiryDate:
month: 1
year: 2025
dpan: '4444333322221111'
billingAddress:
address1: address1
address2: address2
address3: address3
postalCode: postalCode
city: city
state: state
countryCode: GB
narrative:
line1: STATEMENT
line2: OPTIONAL
transactionReference: transaction-ref
responses:
'201':
description: The outcome of your card payout request.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_basicDisbursement_201_response'
examples:
Successful Basic Disbursement:
description: Successful Basic Disbursement
value:
outcome: requestReceived
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
Unsuccessful Payout request:
description: Unsuccessful Payout request
value:
outcome: refused
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
Successful Basic Disbursement to a token:
description: Successful Basic Disbursement to a token
value:
outcome: requestReceived
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
Successful Basic Disbursement to a networkToken:
description: Successful Basic Disbursement to a networkToken
value:
outcome: requestReceived
receivedAt: '2024-08-28T13:49:36.956145Z'
_links:
payouts:payout:
href: https://npe.access.worldpay.com/payouts/MjpkSzMxRnRQT0tqaUplUk1rSG5sWXFRPT06QUVTL0NCQy9QS0NTNVBhZGRpbmc6b0d5RWhlMVNKVUJadWdzeEtBUW9xR1ozTWVZNGcwbUFPMDFpL1F4V1c5cGxOQ0hiVXNnWHZRb0pBZUhhUFg4QjY0dndoNHVpM1NGSjZTcWEvMDhQTVE9PQ==
curies:
- name: payouts
href: https://npe.access.worldpay.com/rels/payouts/{rel}
templated: true
curies:
- name: payouts
href: https://npe.access.worldpay.com/rels/payouts/{rel}
templated: true
Successful Basic Disbursement to a decrypted applepay token:
description: Successful Basic Disbursement to a decrypted applepay token
value:
outcome: requestReceived
receivedAt: '2025-08-01T10:37:36.923Z'
_links:
payouts:payout:
href: https://try.access.worldpay.com/payouts/{resource}
curies:
- name: payouts
href: https://try.access.worldpay.com/rels/payouts/{rel}
templated: true
'400':
description: We could not process the request due to a client error.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_basicDisbursement_400_response'
examples:
Invalid currency:
description: A validation error for an unrecognized currency value
value:
errorName: bodyDoesNotMatchSchema
message: There were field validation errors. The errors that occurred are within the validationErrors array.
validationErrors:
- errorName: fieldHasInvalidValue
message: The identified field does not contain an expected value. This field must contain one of the expected valid values.
jsonPath: $.instruction.value.currency
'422':
description: The request was syntactically valid, but couldn't be processed. For example, your merchant entity is not configured to process card payouts.
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_basicDisbursement_422_response'
examples:
Could not process request:
description: Card payouts not enabled
value:
errorName: fieldHasInvalidValue
message: Your merchant boarding process has not enabled payouts for this merchant entity. Please contact support, or use a valid entity.
jsonPath: $.merchant.entity
'500':
description: Internal server error
content:
application/vnd.worldpay.payouts-v4+json:
schema:
$ref: '#/components/schemas/payouts_basicDisbursement_500_response'
examples:
Internal error:
description: Internal error
value:
errorName: internalErrorOccurred
message: An error occurred within the servi
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-payouts-api-openapi.yml