Testing
Simulate various scenarios using magic values, to ensure your integration is seamless and reliable.
You can test:
SEPA/Faster Payments/US ACH
- successful end-to-end payout flow including banking partner validation and notification (status COMPLETED)
- "-invalid bank details" end-to-end payout flow including banking partner validation and notification (status REVERSED)
All other payouts:
- correctly formatted and successfully routed payouts (status EXECUTED)
- payouts with incorrectly formatted bank details based on country specific requirements (status REVERSED)
Step 1: Check connectivity to required APIs
Ensure you have connectivity to all necessary APIs:
- Account Payouts
- Account APIs (Balance API, Statement API, Transfer API)
- Parties API (if you store beneficiary details)
How to check connectivity:
Your credential set is valid for all Access APIs, therefore you can do a simple test on one of our GET
endpoints to verify whether your credentials are correct:
Do a search by payoutRequestId
and provide an invalid payoutRequestId
(PN00000X):
GET
https://try.access.worldpay.com/accountPayouts/{payoutRequestId}
If your credentials are valid, you should receive the below 403 Forbidden
message confirming that the payoutRequestId
you are querying doesn't belong to your payout:
{
"errorName": "forbidden",
"message": "Forbidden. Unauthorized request"
}
If your credentials are invalid or you have connectivity issues you should receive the below 401 Unauthorized
message:
{
"errorName": "accessDenied",
"message": "Access to the requested resource has been denied"
}
Step 2: Confirm account balance
You must have sufficient funds in your account to make a payout.
- Check balance: Use the Accounts API to verify available funds.
- Transfer funds: If needed, use the Transfer API to move funds between your accounts.
If the balance is insufficient, use the Transfer API or contact your Implementation Manager .
Step 3: End-to-end testing
Full end-to-end testing, which includes full mimicking of our validations as well our banking partner validations, is only available for:
- SEPA
- Faster Payments
- US ACH
When testing these routes you can receive the following status':
- EXECUTED - sent immediately after the payout was processed
- COMPLETED - the final status of a payout with a success notification
- REVERSED - the final status of a payout mimicking a reversal by our banking partners
For all other payouts the final status will either be:
- EXECUTED or
- REVERSED - a simulated reversal by us, this was not validated by the banking partner
Step 4: Prepare payout details
There is two ways to send a payout:
use a
payoutInstrumentReference
/partyReference
for the payout request - Mandatory for Marketplaces customerssubmit full beneficiary bank details directly in the payout request
Step 5: Execute and monitor the payout process
Submit your payout request to either our single or batch payout endpoint.
Successful payout
There is no magic value for a successful payout. To achieve a successful end-to-end test, ensure to include least one valid payout to our single or batch payout try endpoint.
Example payload
{ "payoutRequestId": "PZ000EC4", "idempotencyKey": "idopKey", "entity": "default" }
Invalid bank details - coming soon
Use our batch endpoint to simulate a payout failure due to invalid bank details.
Include "-invalidBankDetails" as part of the value in the transactionReference
field.
To test an invalid payout within a batch, you must include one valid payment to stop internal batch blocking.
- Monitor the status: Use the item search endpoint to query the status of your payout.
- Receive notifications: Await notifications confirming the payout status after validation by us and our banking partners.
- Review bank messages: In case of rejection, check for specific bank messages:
- GBP and EUR Payments: "Other NARR: Narrative:"
- USD Payments: "Other NARR:"
- Reconciliation: Query your statement to verify the transaction and test your reconciliation process.
Simulated payout status timing: It can take up to 10 minutes to receive a final status of PAID after submitting a payout. The REJECTED status will take effect at 4:00pm UTC.
Example payload
{
"merchant": {
"entity": "default"
},
"payouts": [
{
"instruction": {
"value": {
"sourceCurrency": "EUR",
"sourceAmount": 0,
"targetCurrency": "EUR",
"targetAmount": 199.99
},
"narrative": {
"line1": "Testing invalid bank details"
},
"countryCode": "GB",
"fastPayment": false,
"beneficiaryBankDetails": {
"iban": "GB41CITI18500818404062",
"bankName": "Citibank London"
},
"parties": [
{
"partyType": "beneficiary",
"personalDetails": {
"type": "Company",
"companyName": "Worldpay AP Ltd"
},
"address": {
"address1": "25 Walbrook",
"city": "London",
"postalCode": "EC4N 8AF",
"countryCode": "GB"
}
}
]
},
"transactionReference": "ABC123456"
},
{
"instruction": {
"value": {
"sourceCurrency": "EUR",
"sourceAmount": 0,
"targetCurrency": "EUR",
"targetAmount": 199.99
},
"narrative": {
"line1": "Testing invalid bank details"
},
"countryCode": "GB",
"fastPayment": false,
"beneficiaryBankDetails": {
"iban": "GB41CITI18500818401243",
"bankName": "Citibank London"
},
"parties": [
{
"partyType": "beneficiary",
"personalDetails": {
"type": "Company",
"companyName": "Worldpay Ltd"
},
"address": {
"address1": "The Science Park",
"city": "Cambridge",
"postalCode": "CB4 0WE",
"countryCode": "GB"
}
}
]
},
"transactionReference": "ABC123456-invalidBankDetails"
}
]
}
Best practice test cases
Our schema validation is designed to maximize straight-through processing and respond to you synchronously as soon as the payout data in your request is insufficient. We have set several conditions that we recommend you to test, to ensure that you collect the right data and the payout is successfully sent.
Object: beneficiaryBankDetails
(Mandatory, unless you are paying to a PayPal wallet)
Conditional properties
iban
- Optional if you are sending a payout in BBAN format and have provided anaccountNumber
.accountNumber
- Optional if you are sending a payout in IBAN format and have provided aniban
.payoutInstrumentReference
orpayoutInstrumentId
- Mandatory if you have an on-boarded party with us and you're paying out to them as part of the Marketplaces solution (Marketplaces must not input any other bank details in the payload).payoutInstrumentReference
orpayoutInstrumentId
- Optional if you have stored beneficiary and bank details and want to use them to submit a payout request (in this scenario you must not to input any other bank details in the payload).sourceAmount
ortargetAmount
- Do not includesourceAmount
andtargetAmount
in the same request, only send one or the other. The request is rejected if both are supplied.
Object: parties
(beneficiary) - (Mandatory, unless you are using payoutInstrumentReference
or payoutInstrumentId
)
Conditional properties
partyReference
- Use this if you have your beneficiary details stored with us and want to use it with that payout (in this scenario you must not use any other input details for this party).personalDetails
(beneficiary)Conditional properties:
type
- Mandatory forbeneficiary
.companyName
- Mandatory for acompany
,institution
,government
andother
types.title
,firstName
,lastName
- Mandatory forperson
andsoleTrader
types.
Object: parties
(payer) - *Optional, unless you are on-boarded with us as a Payment Service Provider and requesting this payout on behalf of a 3rd party.
We don't validate type
, companyName
or title
, firstName
and lastName
upfront for the payer
(like we do for a beneficiary
). However, your request will be rejected in downstream processing if those are not provided. More details on the payer validation for PSPs.
Conditional properties:
partyReference
- Use this if you have your beneficiary details stored with us and want to use it with that payout (in this scenario you must not use any other input details for this party).personalDetails.phones
Conditional properties:
number
- If number is given, you must also provide theprefix
.prefix
- Ifprefix
is given, you must also provide thenumber
.
personalDetails.identityDocuments
Conditional properties:
number
- Mandatory. You must provide this, if any of other mandatory details of this object are given.issuingCountry
- Mandatory. You must provide this, if any of other mandatory details of this object are given.type
- Mandatory. You must provide this, if any of other mandatory details of this object are given.validFrom
- Optional. Only allowed if you have provided all mandatory details of this object.validTo
- Optional. Only allowed if you have provided all mandatory details of this object.issuingInstitution
- Optional. Only allowed if you have provided all mandatory details of this object.