Important: We have released a new version. Documentation for our latest version can be found
Payout
Send funds to your customer's cards.
Standard payout
Payout request
Pay your customers by sending a request to our payouts:basicDisbursement
action link received in your
POST https://try.access.worldpay.com/payouts/basicDisbursement
Payout request body:
{
"transactionReference": "unique-transactionReference",
"merchant": {
"entity": "default"
},
"instruction": {
"narrative": "STATEMENT",
"value": {
"currency": "GBP",
"amount": 100
},
"payoutInstrument": {
"type": "card/plain",
"cardHolderName": "John Appleseed",
"cardNumber": "4444333322221111",
"cardExpiryDate": {
"month": 5,
"year": 2035
}
}
}
}
{
"transactionReference": "unique-transactionReference",
"merchant": {
"entity": "default"
},
"instruction": {
"narrative": "STATEMENT",
"value": {
"currency": "GBP",
"amount": 100
},
"payoutInstrument": {
"type": "card/tokenized",
"href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiMjZ5OUp3Q2dEeDVjWEZBcjhjSmRlcmZTcE44ZzRoazFMcmNCSzlqaEVWcz0ifQ"
}
}
}
Descriptions of your payout request parameters:
Parameter | Required | Description |
---|---|---|
instruction | An object that contains all the information related to your payout request. | |
instruction.payoutInstrument | An object that contains your customer's payout details. | |
payoutInstrument.type | An object that contains your customer's payout type. Possible values:
| |
payoutInstrument.href | An object that contains your link to an Mandatory for all "type": "card/tokenized" requests. | |
value.amount | The payout amount. This is a whole number with an exponent, e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our | |
value.currency | The 3 digit currency code. See list of | |
instruction.narrative | The text that appears on your customer's statement. Used to identify the merchant. See | |
merchant | An object that contains information about the merchant. | |
merchant.entity | This is mandatory for | |
transactionReference | A unique reference generated by you, used to identify a payout throughout its lifecycle. See |
The full request schemas are available in the
Payout response
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. - Due to a downstream issue, the outcome of your request could not be determined at this time.queryRequired
A timestamp of
receivedAt
- The location of the payout resource
Example responses:
{
"outcome": "requestReceived",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "refused",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "error",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "queryRequired",
"receivedAt": "2020-05-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
}]
}
Standard payout outcome
of queryRequired
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 appears in the queryRequired
response.
Example response:
GET https://try.access.worldpay.com/payouts/{resource}
{
"outcome": "requestReceived",
"receivedAt": "2020-05-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://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.
{
"errorName": "payoutNotFound"
"message": "The payout request you are trying to locate does not exist."
}
{ "errorName": "payoutNotFound" "message": "The payout request you are trying to locate does not exist." }
Fast Access
Use Fast Access to pay your customers within 30 minutes or less.
Prerequisite: You must be enabled for Fast Access before using it. Please contact your Implementation Manager for more information.
Fast Access payout request
Send your payout request to our payouts:fastAccess
action link received in your
If your customers card is not Fast Access enabled, a
POST https://try.access.worldpay.com/payouts/fastAccess
Fast Access payout request body:
{
"transactionReference": "unique-transactionReference",
"merchant": {
"entity": "default"
},
"instruction": {
"narrative": "STATEMENT",
"value": {
"currency": "GBP",
"amount": 100
},
"payoutInstrument": {
"type": "card/plain",
"cardHolderName": "John Appleseed",
"cardNumber": "4444333322221111",
"cardExpiryDate": {
"month": 5,
"year": 2035
}
}
}
}
{
"transactionReference": "unique-transactionReference",
"merchant": {
"entity": "default"
},
"instruction": {
"narrative": "STATEMENT",
"value": {
"currency": "GBP",
"amount": 100
},
"payoutInstrument": {
"type": "card/tokenized",
"href": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiMjZ5OUp3Q2dEeDVjWEZBcjhjSmRlcmZTcE44ZzRoazFMcmNCSzlqaEVWcz0ifQ"
}
}
}
Descriptions of your Fast Access payout request parameters">
Parameter | Required | Description |
---|---|---|
instruction | An object that contains all the information related to your payout request. | |
payoutInstrument | An object that contains your customer's payout details. | |
payoutInstrument.type | An object that contains your customer's payout type. Possible values:
| |
payoutInstrument.href | An object that contains your link to an Mandatory for all "type": "card/tokenized" requests. | |
value.amount | The payout amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our | |
value.currency | The 3 digit currency code. See list of | |
instruction.narrative | The text that appears on your customer's statement. Used to identify the merchant. See | |
merchant | An object that contains information about the merchant. | |
merchant.entity | This is mandatory for | |
transactionReference | A unique reference generated by you, used to identify a payout throughout its lifecycle. See |
The full request schemas are available in the
Fast Access payout response
In our response we return:
- The
outcome
, which could be: - We have received your Fast Access disbursement.requested
- We have sent your Fast Access disbursement request to Visa. If there are no updates within 48 hours then this moves to anpending
error
outcome. - Visa has approved your request and the funds are allocated within 30 minutes if the issuer is Fast Access enabled. If not, standard timescales apply.approved
disbursed
- The transaction is reconciled with Visa’s daily reporting.refused
- Your Fast Access disbursement request is refused. Possible refusal reasons:- The card issuer declines the disbursement
- Visa 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 within 48 hours or Visa returns an error confirming the request has failed - Due to a downstream issue, the outcome of your request could not be determined at this time.queryRequired
- A timestamp
receivedAt
- The location of the payout resource
{
"outcome": "requested",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "pending",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "approved",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "disbursed",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "refused",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "error",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "queryRequired",
"receivedAt": "2020-05-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
}]
}
Fast Access payout outcome
of requested
, pending
, approved
or queryRequired
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 avaliable the payouts:update
action link will appear in this response.
Example:
GET https://try.access.worldpay.com/payouts/{resource}
Example responses:
{
"outcome": "requested",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "pending",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "approved",
"receivedAt": "2020-05-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
}]
}
{
"outcome": "queryRequired",
"receivedAt": "2020-05-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.
{
"errorName": "payoutNotFound"
"message": "The payout request you are trying to locate does not exist."
}
{ "errorName": "payoutNotFound" "message": "The payout request you are trying to locate does not exist." }
Retrieve a payout using the original resource
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.
Query a payout without the original resource
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.