# 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](/products/account-payouts/openapi) 2. Account APIs ([Balances API](/products/balance/openapi), [Statements API](/products/statements/openapi), [Account Transfers API](/products/transfers/openapi)) 3. [Parties API](/products/parties/openapi) (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): br `GET` `https://try.access.worldpay-bsh.securedataplatform.com/accountPayouts/{payoutRequestId}` br 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" } ``` br 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](/products/balance/openapi) to verify available funds. 2. Transfer funds: If needed, use the [Account Transfers API](/products/transfers/openapi) to move funds between your accounts. Test balance If the balance is insufficient, use the Transfers 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`](/products/parties/payout-instruments)/[`partyReference`](/products/parties) 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](/products/account-payouts/openapi/single-payout) or [batch](/products/account-payouts/openapi/batch-payout) 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](/products/account-payouts/openapi/single-payout) or [batch](/products/account-payouts/openapi/batch-payout) payout try endpoint. #### Example payload Account Payout customers Marketplaces #### Invalid bank details - coming soon Use our [batch endpoint](/products/account-payouts/openapi/batch-payout) to simulate a payout failure due to invalid bank details. Include "-invalidBankDetails" as part of the value in the `transactionReference` field. Important To test an invalid payout within a batch, you must include one valid payment to stop internal batch blocking. 1. Monitor the status: Use the [item search endpoint](/products/account-payouts/openapi/get-payouts) 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:" 1. Reconciliation: [Query your statement](/products/statements/openapi) to verify the transaction and test your reconciliation process. Additional information 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 Account Payout customers { "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" } ] } Marketplaces { "merchant": { "entity": "default" }, "payouts": [ { "instruction": { "value": { "sourceCurrency": "GBP", "sourceAmount": 199.99, "targetAmount": 0 }, "countryCode": "US", "fastPayment": false, "beneficiaryBankDetails": { "payoutInstrumentReference": "BeneficiaryBankGBP" } }, "transactionReference": "ABC123456" }, { "instruction": { "value": { "sourceCurrency": "GBP", "sourceAmount": 199.99, "targetAmount": 0 }, "countryCode": "US", "fastPayment": false, "beneficiaryBankDetails": { "payoutInstrumentReference": "BeneficiaryBankGBP_2" } }, "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](/products/marketplaces/coverage/bank/additionalinfo#payment-service-provider-psp-and-money-service-business-msb-merchants). ##### 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.