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:

1. Account Payouts
2. Account APIs (Balances API, Statements API, Account Transfers 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 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.

1. Check balance: Use the Accounts API to verify available funds.
2. Transfer funds: If needed, use the Account Transfers 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

{
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "value": {
      "sourceCurrency": "EUR",
      "sourceAmount": 0,
      "targetCurrency": "EUR",
      "targetAmount": 199.99
    },
    "narrative": {
      "line1": "PushtoAccount with Worldpay"
    },
    "countryCode": "GB",
    "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"
}

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

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

1. iban - Optional if you are sending a payout in BBAN format and have provided an accountNumber.
2. accountNumber - Optional if you are sending a payout in IBAN format and have provided an iban.
3. payoutInstrumentReference or payoutInstrumentId - 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).
4. payoutInstrumentReference or payoutInstrumentId - 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).
5. sourceAmount or targetAmount - Do not include sourceAmount and targetAmount 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

1. 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).

2. personalDetails (beneficiary)

   Conditional properties:

   1. type - Mandatory for beneficiary.
   2. companyName - Mandatory for a company, institution, government and other types.
   3. title, firstName, lastName - Mandatory for person and soleTrader 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:

1. 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).

2. personalDetails.phones

   Conditional properties:

   1. number - If number is given, you must also provide the prefix.
   2. prefix - If prefix is given, you must also provide the number.
      
      

3. personalDetails.identityDocuments

   Conditional properties:

   1. number - Mandatory. You must provide this, if any of other mandatory details of this object are given.
   2. issuingCountry - Mandatory. You must provide this, if any of other mandatory details of this object are given.
   3. type - Mandatory. You must provide this, if any of other mandatory details of this object are given.
   4. validFrom - Optional. Only allowed if you have provided all mandatory details of this object.
   5. validTo - Optional. Only allowed if you have provided all mandatory details of this object.
   6. issuingInstitution - Optional. Only allowed if you have provided all mandatory details of this object.