Testing

Simulate various scenarios 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) - coming soon

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:

1. Account Payouts
2. Account APIs (Balance API, Statement API, Transfer API)
3. 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 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"
}

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"
}

Step 2: Confirm account balance

Ensure the account you wish to debit has the necessary balance for the test payout.

1. Check balance: Use the Accounts API to verify available funds.
2. Transfer Funds: If needed, use the Transfer API to move funds between your accounts.

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 customers

• submit 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.

1. Monitor the status: Use the item search endpoint to query the status of your payout.
2. Receive notifications: Await notifications confirming the payout status after validation by us and our banking partners.
3. Review bank messages: In case of rejection, check for specific bank messages:

• GBP and EUR Payments: "Other NARR: Narrative:"
• USD Payments: "Other NARR:"

4. Reconciliation: Query your statement to verify the transaction and test your reconciliation process.

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"
    }
  ]
}