Last Updated: 29 August 2024 | Change Log
Send funds to your customer's cards.
Pay your customers by sending a request to our payouts:basicDisbursement
action link received in your query the payout root resource request.
If you want to payout to a wallet please read here first.
POST
https://try.access.worldpay.com/payouts/basicDisbursement
Payout request body:
{
"transactionReference": "Memory265-13/08/1876",
"merchant": {
"entity": "default"
},
"instruction": {
"narrative": {
"line1": "The Mind Palace Ltd",
"line2": "Memory265-13/08/1876"
},
"value": {
"currency": "GBP",
"amount": 100
},
"payoutInstrument": {
"type": "card/plain",
"cardHolderName": "Sherlock Holmes",
"cardNumber": "4444333322221111",
"cardExpiryDate": {
"month": 5,
"year": 2035
},
"billingAddress": {
"address1": "221B Baker Street",
"address2": "Marylebone",
"address3": "Westminster",
"postalCode": "NW1 6XE",
"city": "London",
"state": "Greater London",
"countryCode": "GB"
}
}
}
}
An object that contains all the information related to your payout request.
An object that contains identification and further details of the merchant.
First line of text that appears on your customer's statement.
Second line of text that appears on your customer's statement.
An object that contains your customer's payout type.
Your customer's payout card number.
The expiry date of your customer's card. Must be a date in the future.
The name on your customer's card. This is not a mandatory field 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.
An object containing the billing address information. We recommend you provide billingAddress
fields for all Payout requests.
An object that contains payout amount and currency.
The payout amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.
The three character currency code. See list of supported currencies.
An object that contains information about the merchant.
Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.
A unique reference generated by you, used to identify a payout throughout its lifecycle.
Access Worldpay returns a WP-correlationId
in the headers of service responses. We highly recommend you log this. The WP-correlationId
is used by us to examine individual service requests.
In your response we return:
The
outcome
, which could be:requestReceived
- We have received your basic disbursement request and are processing it within 3-5 working days.refused
- This payout method is refused, try another card.error
- A downstream system failed to process your request.
A timestamp of
receivedAt
The location of the payout resource
Example responses:
{
"outcome": "requestReceived",
"receivedAt": "2023-09-06T12:29:39.625884Z",
"_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
}]
}
}
We recommend using our Events service to receive the latest Payout status.
Use Fast Access to pay your customers within 30 minutes or less.
You must be enabled for Fast Access before using it. Please contact your Implementation Manager for more information.
Send your payout request to our payouts:fastAccess
action link received in your query the payout root resource request.
If your customers card is not Fast Access enabled, a standard payout is automatically performed.
If you want to payout to a wallet please read here first.
POST
https://try.access.worldpay.com/payouts/fastAccess
Fast Access payout request body:
{
"transactionReference": "Memory265-13/08/1876",
"merchant": {
"entity": "default"
},
"instruction": {
"narrative": {
"line1": "The Mind Palace Ltd",
"line2": "Memory265-13/08/1876"
},
"value": {
"currency": "GBP",
"amount": 100
},
"payoutInstrument": {
"type": "card/plain",
"cardHolderName": "Sherlock Holmes",
"cardNumber": "4444333322221111",
"cardExpiryDate": {
"month": 5,
"year": 2035
},
"billingAddress": {
"address1": "221B Baker Street",
"address2": "Marylebone",
"address3": "Westminster",
"postalCode": "NW1 6XE",
"city": "London",
"state": "Greater London",
"countryCode": "GB"
}
}
}
}
An object that contains all the information related to your payout request.
An object that contains identification and further details of the merchant.
First line of text that appears on your customer's statement.
Second line of text that appears on your customer's statement.
An object that contains your customer's payout type.
Your customer's payout card number.
The expiry date of your customer's card. Must be a date in the future.
The name on your customer's card. This is not a mandatory field 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.
An object containing the billing address information. We recommend you provide billingAddress
fields for all Payout requests.
An object that contains payout amount and currency.
The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.
The three character currency code. See list of supported currencies.
An object that contains information about the merchant.
Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.
A unique reference generated by you, used to identify a payout throughout its lifecycle.
The full request schemas are available in the API reference.
Access Worldpay returns a WP-CorrelationId
in the headers of service responses. We highly recommend you log this. The WP-CorrelationId
is used by us to examine individual service requests.
In our response we return:
- The
outcome
, which could be:requested
- We have received your Fast Access disbursement.pending
- We have sent your Fast Access disbursement request to Visa Direct/Mastercard Send. If there are no updates within 48 hours then this moves to anerror
outcome.approved
- Visa/Mastercard has approved your request and the funds are allocated within 30 minutes if the issuer is Fast Access enabled. If not, standard timescales apply.disbursed
- The transaction is reconciled with Visa/Mastercard’s daily reporting.refused
- Your Fast Access disbursement request is refused. Possible refusal reasons:- The card issuer declines the disbursement
- Visa/Mastercard declines your request because the issuing bank is not responding
- Disbursements are not allowed in the requested country
error
- There is no response from Visa/Mastercard within 48 hours or Visa/Mastercard returns an error confirming the request has failed.requestReceived
– We have received your Fast Access disbursement request, but the card does not support Fast Access.
- A timestamp
receivedAt
- The location of the payout resource
{
"outcome": "requested",
"receivedAt": "2023-09-06T12:29:39.625884Z",
"_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
}]
}
}
Send a GET
request to the payouts:payout
action link, to retrieve the outcome of your payout request. When an update to the outcome is available the payouts:update
action link will appear in this response.
Example:
GET
https://try.access.worldpay.com/payouts/{resource}
Example responses:
{
"outcome": "requested",
"receivedAt": "2023-09-06T12:29:39.625884Z",
"_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
}]
}
}
Send a GET
request to the payouts:update
action link to find out the update to the outcome.
If no update is available, you will get an error. You can get further information in our error reference.
Send a GET
to the resource of the payouts:payout
action link, returned in the response of the initial basicDisbursement
or fastAccess
request.
GET
https://try.access.worldpay.com/payouts/{resource}
Replace {resource}
in the link above with the location given in your initial response.
You can only get the location from the initial response.
If the location of an existing payout is lost, the result can still be recovered using the payouts:query
endpoint.
To do this you must have the entity
and transactionReference
of the original request.
Send a GET
to the resource of payouts:query
action link.
GET
https://try.access.worldpay.com/payouts/query?transactionReference={transactionReference}&entity={entity}
Replace {transactionReference}
and {entity}
in the link above with the transactionReference
and entity
of the original payout.