Menu

Important: We have released a new version. Documentation for our latest version can be foundhere.

Payout

API v1

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 yourquery the payout root resourcerequest.

POST https://try.access.worldpay.com/payouts/basicDisbursement

Payout request body:

Copied!
{
    "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:

ParameterRequiredDescription
instructionAn object that contains all the information related to your payout request.
instruction.payoutInstrumentAn object that contains your customer's payout details.
payoutInstrument.typeAn object that contains your customer's payout type.
Possible values:
  • card/plain
  • card/tokenized
payoutInstrument.hrefAn object that contains your link to anAccess Token.
Mandatory for all "type": "card/tokenized" requests.
value.amountThe 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 ourcurrency table.
value.currencyThe 3 digit currency code.
See list ofsupported currencies.
instruction.narrativeThe text that appears on your customer's statement. Used to identify the merchant.
Seenarrative formatfor more details and best practices.
merchantAn object that contains information about the merchant.
merchant.entityThis is mandatory forauthenticationandqueries. Contact your Implementation Manager for more information.
transactionReferenceA unique reference generated by you, used to identify a payout throughout its lifecycle. Seetransaction reference formatfor more details and best practices.

The full request schemas are available in theAPI reference.

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.
    • queryRequired- Due to a downstream issue, the outcome of your request could not be determined at this time.
  • A timestamp of receivedAt

  • The location of the payout resource

Example responses:

Copied!
{
    "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}

Copied!
{
    "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.

Copied!
{
   "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 yourquery the payout root resourcerequest.

If your customers card is not Fast Access enabled, astandard payoutis automatically performed.

POST https://try.access.worldpay.com/payouts/fastAccess

Fast Access payout request body:

Copied!
{
    "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">

ParameterRequiredDescription
instructionAn object that contains all the information related to your payout request.
payoutInstrumentAn object that contains your customer's payout details.
payoutInstrument.typeAn object that contains your customer's payout type.
Possible values:
  • card/plain
  • card/tokenized
payoutInstrument.hrefAn object that contains your link to anAccess Token.
Mandatory for all "type": "card/tokenized" requests.
value.amountThe 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 ourcurrency table.
value.currencyThe 3 digit currency code.
See list ofsupported currencies.
instruction.narrativeThe text that appears on your customer's statement. Used to identify the merchant.
Seenarrative formatfor more details and best practices.
merchantAn object that contains information about the merchant.
merchant.entityThis is mandatory forauthenticationandqueries. Contact your Implementation Manager for more information.
transactionReferenceA unique reference generated by you, used to identify a payout throughout its lifecycle. Seetransaction reference format, for more details and best practices.

The full request schemas are available in theAPI reference.

Fast Access payout response

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. If there are no updates within 48 hours then this moves to an error outcome.
    • approved- 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.
    • 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
    • queryRequired- Due to a downstream issue, the outcome of your request could not be determined at this time.
  • A timestamp receivedAt
  • The location of the payout resource
Copied!
{
    "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:

Copied!
{
    "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.

Copied!
{
   "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.