Approve and acknowledge the payment
Your options once we've received a payment request:
-
Approve the payment request we've received
Approve the payment request
When we receive a payToBankAccountV3 request, we put it into the Merchant Administration System (MAS) approval queue. You can then check and approve it before we instruct our bank to settle the payment. Your account isn't debited until you approve the payment.
If you have an internal procedure that vets payments before your system interacts with Worldpay, you can instruct our systems to automatically approve and begin processing payment requests triggered by the API calls. Contact us to do this.
By default, we only check that fields such as accountNumber or IBAN have data in them. Formal validation does not happen yet - you can do your own validation based on the parameters in the paymentTemplate object. Errors are found after payments are submitted to Worldpay systems and may be rejected if data is missing or incorrect.
Payment success
The Payout Success Notification service lets you know that the payment has been successfully submitted. This means the payment has successfully passed our validation checks and you have been debited the funds needed to complete the transfer. The Payout Success Notification service does not confirm that funds have been settled to the beneficiary bank account.
We can send a SOAP RPC call with the PaymentOutNotification API method to your website as an HTTPS post to notify you of successful Push to Accounts. When receiving a PaymentOutNotification, you must respond with a PaymentOutNotificationResponse or we will repost the same notification.
You can also receive notifications by email.
If you want to use this service, contact us with your email address and your notification endpoint for SOAP based notifications.
PaymentOutNotification
Worldpay notifications always come from IP 213.129.74.111 or IP 93.91.29.197 or 149.5.102.77 or IP Ranges 195.35.90.0/27 or 195.35.91.0/27.
PaymentOutNotification schema
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutNotification xmlns="http://apilistener.envoyservices.com">
<paymentDetails>
<originalPaymentInfo>
<countryCode>string</countryCode>
<payee>string</payee>
<merchantReference>string</merchantReference>
<merchantPaymentReference>string</merchantPaymentReference>
<sourceCurrency>string</sourceCurrency>
<sourceAmount>double</sourceAmount>
<targetCurrency>string</targetCurrency>
<targetAmount>double</targetAmount>
<sourceOrTarget>string</sourceOrTarget>
<fastPayment>string</fastPayment>
<additionalInfo1>string</additionalInfo1>
<additionalInfo2>string</additionalInfo2>
<additionalInfo3>string</additionalInfo3>
</originalPaymentInfo>
<paymentResult>
<envoyMerchantAccountNumber>string</envoyMerchantAccountNumber>
<itemNumber>string</itemNumber>
<statementId>string</statementId>
<epacsReference>string</epacsReference>
<executionDate>string</executionDate>
<appliedCurrency>string</appliedCurrency>
<appliedAmount>double</appliedAmount>
</paymentResult>
</paymentDetails>
</PaymentOutNotification>
</soap:Body>
</soap:Envelope>
PaymentOutNotification elements
|
Lvl |
Element |
Description |
Values / Limitations |
|---|---|---|---|
|
1 |
paymentDetails |
Contains elements related to the payment being notified. |
Complex Type Mandatory |
|
2 |
originalPaymentInfo |
Contains elements related to the original payment. |
Complex Type Mandatory |
|
3 |
countryCode |
Destination country of the Push to Account. |
String 2 characters ISO 3166-1 English country code standard Mandatory |
|
3 |
payee |
Beneficiary account name. |
String up to 50 characters Optional |
|
3 |
merchantReference |
Statement narrative you provide in the Push to Account instruction. |
String up to 50 characters Optional |
|
3 |
merchantPaymentReference |
Unique reference you generate to identify the Push to Account instruction. |
String up to 50 characters Optional |
|
3 |
sourceCurrency |
WPAP account currency specified in the Push to Account. |
String 3 characters ISO 4217 currency code standard Mandatory |
|
3 |
sourceAmount |
WPAP account debit amount specified in the Push to Account. |
Decimal Mandatory |
|
3 |
targetCurrency |
Currency that was instructed by WPAP through the WPAP banking partner. |
String 3 characters ISO 4217 currency code standard. Mandatory |
|
3 |
targetAmount |
Amount that was instructed by through the WPAP banking partner. |
Decimal Mandatory |
|
3 |
sourceOrTarget |
Whether the beneficiary should be paid the source (S) or target (T) amount. See PaymentOutNotification for further details. |
String, 1 character Mandatory |
|
3 |
fastPayment |
Indicates if the payment should go through a fast or normal payment route.
|
String, 1 character Mandatory |
|
3 |
additionalInfo1 |
Additional information you provide when requesting the Push to Account. |
String, up to 50 characters Optional |
|
3 |
additionalInfo2 |
Additional information you provide when requesting the Push to Account. |
String, up to 50 characters Optional |
|
3 |
additionalInfo3 |
Additional information you provide when requesting the Push to Account. |
String, up to 50 characters Optional |
|
2 |
paymentResult |
Contains elements related to the status of the payment. |
Complex Type Mandatory |
|
3 |
envoyMerchantAccountNumber |
Your WPAP account that was debited by the Push to Account instruction. |
String, 16 characters exactly Mandatory |
|
3 |
itemNumber |
Account statement number that increments with every item applied to the account. |
Integer Mandatory |
|
3 |
statementId |
Unique statement item id, unique across the WPAP platform. |
GUID format Mandatory |
|
3 |
epacsReference |
Unique reference for the Push to Account. |
GUID format Mandatory |
|
3 |
executionDate |
Timestamp of when WPAP debited your account. |
YYYY-MM-DDThh:mm:ss.nn (the ‘T’ remains in the string and does not get replaced by a value. ‘nn’ represents hundredths of a second) Mandatory |
|
3 |
appliedCurrency |
Currency debited from your WPAP account. |
String 3 characters ISO 4217 currency code standard Mandatory |
|
3 |
appliedAmount |
Amount debited from your WPAP account. |
Decimal Mandatory |
PaymentOutNotificationResponse schema
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutNotificationResponse xmlns="http://apilistener.envoyservices.com">
<PaymentOutNotificationResult>string</PaymentOutNotificationResult>
</PaymentOutNotificationResponse>
</soap:Body>
</soap:Envelope>
PaymentOutNotificationResponse elements
|
Lvl |
Element |
Description |
Values / Limitations |
|---|---|---|---|
|
1 |
PaymentOutNotificationResult |
Use this element to respond to the PaymentOutNotification you receive. |
String up to 7 characters Mandatory Set to SUCCESS or ERROR |
Example notification and response
Notification:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutNotification xmlns="http://apilistener.envoyservices.com">
<paymentDetails>
<originalPaymentInfo>
<countryCode>GB</countryCode>
<payee>Test Payee</payee>
<merchantReference>Test Merchant Narrative</merchantReference>
<merchantPaymentReference>8447801</merchantPaymentReference>
<sourceCurrency>GBP</sourceCurrency>
<sourceAmount>0.00</sourceAmount>
<targetCurrency>GBP</targetCurrency>
<targetAmount>15.00</targetAmount>
<sourceOrTarget>T</sourceOrTarget>
<fastPayment>N</fastPayment>
<additionalInfo1 />
<additionalInfo2 />
<additionalInfo3 />
</originalPaymentInfo>
<paymentResult>
<envoyMerchantAccountNumber>0001230000000002</envoyMerchantAccountNumber>
<itemNumber>160216</itemNumber>
<statementId>f0352060-3417-e311-9f75-0050568a2d55</statementId>
<epacsReference>e9352060-3417-e311-9f75-0050w68a2f55</epacsReference>
<executionDate>2013-09-06T20:39:16</executionDate>
<appliedCurrency>GBP</appliedCurrency>
<appliedAmount>15.00</appliedAmount>
</paymentResult>
</paymentDetails>
</PaymentOutNotification>
</soap:Body>
</soap:Envelope>
Your response:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutNotificationResponse xmlns="http://apilistener.envoyservices.com">
<PaymentOutNotificationResult>SUCCESS</PaymentOutNotificationResult>
</PaymentOutNotificationResponse>
</soap:Body>
</soap:Envelope>
Payment failure
It is possible for a payment to fail for a number of reasons outside of our control. There are two types of failure.
REVERSAL
The payout was rejected by:
-
The Worldpay AP payment system due to an issue with routing the payment via one of our banks (for example, invalid bank data, no route available)
-
Our partner bank (for example, invalid bank data)
RETURN
The payout was accepted by the Worldpay payment system and our partner bank, but was rejected by the beneficiary bank (for example, account doesn’t exist, account closed). The PAYOUT_RETURN is typically processed as far as the beneficiary bank where it fails, and is subsequently returned by same settlement route, which means it can be returned many days later.
Both of these failures result in your Worldpay AP account being credited. We can also send a notification (email and/or SOAP) to you, detailing the failure and the returned item.
The notification endpoint and notification email address are defined in the merchant configuration. If you want to use this service, let us know and we’ll set it up for your account: Contacting Worldpay . You’ll need to give us your email address and your notification endpoint for SOAP based notifications.
PaymentOutReversalNotification
Worldpay notifications always come from IP 213.129.74.111 or IP 93.91.29.197 or 149.5.102.77 or IP Ranges 195.35.90.0/27 or 195.35.91.0/27.
PaymentOutReversalNotification schema
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutReversalNotification xmlns="http://apilistener.envoyservices.com">
<reversalInfo>
<originalPaymentInfo>
<countryCode>string</countryCode>
<payee>string</payee>
<merchantReference>string</merchantReference>
<merchantPaymentReference>string</merchantPaymentReference>
<sourceCurrency>string</sourceCurrency>
<sourceAmount>double</sourceAmount>
<targetCurrency>string</targetCurrency>
<targetAmount>double</targetAmount>
<sourceOrTarget>string</sourceOrTarget>
<fastPayment>string</fastPayment>
<additionalInfo1>string</additionalInfo1>
<additionalInfo2>string</additionalInfo2>
<additionalInfo3>string</additionalInfo3>
</originalPaymentInfo>
<credit>
<envoyMerchantAccountNumber>string</envoyMerchantAccountNumber>
<itemNumber>string</itemNumber>
<statementId>string</statementId>
<epacsReference>string</epacsReference>
<postingDate>string</postingDate>
<creditCurrency>string</creditCurrency>
<creditAmount>double</creditAmount>
<reversalReason>string</reversalReason>
</credit>
<debit>
<envoyMerchantAccountNumber>string</envoyMerchantAccountNumber>
<itemNumber>string</itemNumber>
<statementId>string</statementId>
<epacsReference>string</epacsReference>
<postingDate>string</postingDate>
<debitCurrency>string</debitCurrency>
<debitAmount>double</debitAmount>
</debit>
</reversalInfo>
</PaymentOutReversalNotification>
</soap:Body>
</soap:Envelope>
PaymentOutReversalNotification elements
|
Lvl |
Element |
Description |
Values / Limitations |
|---|---|---|---|
|
1 |
reversalInfo |
Contains elements related to the reversal. |
Complex Type Mandatory |
|
2 |
originalPaymentInfo |
Contains elements related to the original payment. |
Complex Type Mandatory |
|
3 |
countryCode |
Destination country that the Push to Account. |
String 2 characters ISO 3166-1 English country code standard Mandatory |
|
3 |
Payee |
Beneficiary account name. |
String up to 50 characters Optional |
|
3 |
merchantReference |
Statement narrative you provide in the original Push to Account instruction. |
String up to 50 characters Optional |
|
3 |
merchantPaymentReference |
Unique reference you generate to identify the original Push to Account instruction. |
String up to 50 characters Optional |
|
3 |
sourceCurrency |
WPAP account currency specified in the original Push to Account. |
String 3 characters ISO 4217 currency code standard Mandatory |
|
3 |
sourceAmount |
WPAP account debit amount specified in the original Push to Account. |
Decimal Mandatory |
|
3 |
targetCurrency |
Currency that was instructed by WPAP for the WPAP banking partner. |
String 3 characters ISO 4217 currency code standard. Mandatory |
|
3 |
targetAmount |
Amount that was instructed by WPAP for the WPAP banking partner. |
Decimal Mandatory |
|
3 |
sourceOrTarget |
Whether the beneficiary should be paid the source (S) or target (T) amount. See PaymentOutReversalNotification for further details. |
String, 1 character Mandatory |
|
3 |
fastPayment |
Indicates if the payment should go through a fast or normal payment route. |
String, 1 character Mandatory |
|
3 |
additionalInfo1 |
Additional information you provide when requesting the Push to Account. |
String up to 50 characters Optional |
|
3 |
additionalInfo2 |
Additional information you provide when requesting the Push to Account. |
String up to 50 characters Optional |
|
3 |
additionalInfo3 |
Additional information you provide when requesting the Push to Account. |
String up to 50 characters Optional |
|
2 |
Credit |
Contains elements related to reversal statement entry. |
Complex Type |
|
3 |
envoyMerchantAccountNumber |
Your Worldpay AP account that was credited with the reversal. |
String, 16 characters exactly Mandatory |
|
3 |
itemNumber |
Account statement number that increments with every item applied to the account. |
Integer Mandatory |
|
3 |
statementId |
Unique statement item id, unique across the WPAP platform. |
GUID format Mandatory |
|
3 |
epacsReference |
Unique reference for the credit. |
GUID format Mandatory |
|
3 |
postingDate |
Timestamp of when WPAP credited the account. |
YYYY-MM-DDThh:mm:ss.nn (the ‘T’ remains in the string and does not get replaced by a value. ‘nn’ represents hundredths of a second) Mandatory |
|
3 |
creditCurrency |
Currency credited to your WPAP account. |
String 3 characters ISO 4217 currency code standard Mandatory |
|
3 |
creditAmount |
Amount credited to your WPAP account. |
Decimal Mandatory |
|
3 |
reversalReason |
Narrative describing the reason that the Push to Account reversal failed. |
String up to 50 characters Optional |
|
2 |
Debit |
Contains elements related to Push to Account statement entry. |
Complex Type Mandatory |
|
3 |
envoyMerchantAccountNumber |
Your WPAP account that was debited by the original Push to Account instruction. |
String, 16 characters exactly Mandatory |
|
3 |
itemNumber |
Account statement number that increments with every item applied to the account. |
Integer Mandatory |
|
3 |
statementId |
Unique statement item id, unique across the WPAP platform. |
GUID format Mandatory |
|
3 |
epacsReference |
Unique reference for the Push to Account. |
GUID format Mandatory |
|
3 |
postingDate |
Timestamp of when WPAP your account. |
YYYY-MM-DDThh:mm:ss.nn (the ‘T’ remains in the string and does not get replaced by a value. ‘nn’ represents hundredths of a second) Mandatory |
|
3 |
debitCurrency |
Currency debited from your WPAP account. |
String 3 characters ISO 4217 currency code standard Mandatory |
|
3 |
debitAmount |
Amount debited from your WPAP account. |
Decimal Mandatory |
PaymentOutReversalNotificationResponse schema
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutReversalNotificationResponse xmlns="http://apilistener.envoyservices.com">
<PaymentOutReversalNotificationResult>string</PaymentOutReversalNotificationResult>
</PaymentOutReversalNotificationResponse>
</soap:Body>
</soap:Envelope>
PaymentOutReversalNotificationResponse
|
Lvl |
Element |
Description |
Values / Limitations |
|---|---|---|---|
|
1 |
PaymentOutReversalNotificationResult |
Use this element to respond to the PaymentOutReversalNotification you receive. |
String up to 7 characters Mandatory Set to SUCCESS or ERROR. |
Example notification and response
Notification:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutReversalNotification xmlns="http://apilistener.envoyservices.com">
<reversalInfo>
<originalPaymentInfo>
<countryCode>GB</countryCode>
<payee>Test Payee</payee>
<merchantReference>Test Merchant 123</merchantReference>
<merchantPaymentReference>8447801</merchantPaymentReference>
<sourceCurrency>GBP</sourceCurrency>
<sourceAmount>0.00</sourceAmount>
<targetCurrency>GBP</targetCurrency>
<targetAmount>15.00</targetAmount>
<sourceOrTarget>T</sourceOrTarget>
<fastPayment>N</fastPayment>
<additionalInfo1 />
<additionalInfo2 />
<additionalInfo3 />
</originalPaymentInfo>
<credit>
<envoyMerchantAccountNumber>0003450000000002</envoyMerchantAccountNumber>
<itemNumber>164154</itemNumber>
<statementId>989cef79-511c-e311-9f75-0050568a2f55</statementId>
<epacsReference>859cef79-511c-e311-9f75-0050568a2f55</epacsReference>
<postingDate>2013-09-13T08:50:03</postingDate>
<creditCurrency>GBP</creditCurrency>
<creditAmount>15.00</creditAmount>
<reversalReason>Invalid Bank Code Returned by Beneficiary Bank</reversalReason>
</credit>
<debit>
<envoyMerchantAccountNumber>0003450000000002</envoyMerchantAccountNumber>
<itemNumber>160216</itemNumber>
<statementId>f0352060-3417-e311-9f75-0050568a2f55</statementId>
<epacsReference>e9352060-3417-e311-9f75-0050568a2f55</epacsReference>
<postingDate>2013-09-06T20:39:16</postingDate>
<debitCurrency>GBP</debitCurrency>
<debitAmount>15.00</debitAmount>
</debit>
</reversalInfo>
</PaymentOutReversalNotification>
</soap:Body>
</soap:Envelope>
Your response:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<PaymentOutReversalNotificationResponse xmlns="http://apilistener.envoyservices.com">
<PaymentOutReversalNotificationResult>SUCCESS</PaymentOutReversalNotificationResult>
</PaymentOutReversalNotificationResponse>
</soap:Body>
</soap:Envelope>