Last Updated: 14 May 2025 | Change Log

Notifications

Receive asynchronous notifications advising you of the payment status.

Prerequisite

To enable notifications please contact your Implementation Manager. You must give us your notification endpoint.

How does it work?

After you have submitted the payment and the status is "Accepted", the payment is sent to the respective downstream bank. The time required to complete this process is dependent on the payout partner and the route chosen. Due to this, the final response is an asynchronous notification.

We can send a call to your website as an HTTPS POST. This is to notify you of successful, reversed or returned account, as well as successful credits to your account.

You must respond to the notification with a call that has a 'success' message. (see example in "Your Response" sections) or we will repost the same notification.

Important

You must ensure the following IP addresses are whitelisted to receive our notifications:
Try environment

195.35.90.128/25 (195.35.90.129 to 195.35.90.253)
195.35.91.128/25 (195.35.91.129 to 195.35.91.253)

Live environment

195.35.90.0/25 (195.35.90.1 to 195.35.90.126)
195.35.91.0/25 (195.35.91.1 to 195.35.91.126)

Payout Success:

This notification is sent when we have sent the payout successfully to the downstream payout partner and they are now processing the request. This means the payment has successfully passed our validation checks and you have been debited the funds needed to complete the transfer.

This notification doesn't confirm that funds have been settled to the beneficiary bank account.

Field Name	Description	Data Type/Format
`originalPaymentInfo.ubr`	Unique reference associated with a payout.	AN
`originalPaymentInfo.entity`	Unique ID given to you during the onboarding process. This is the entity the funds are debited from.	AN
`originalPaymentInfo.apiRequestReference`	Unique reference for the request.	String
`originalPaymentInfo.transactionReference`	Merchant's unique reference for the payout request.	AN
`originalPaymentInfo.narrative`	Reference that may appear on the payee statement.	String
`originalPaymentInfo.countryCode`	Country of the payout destination.	A
`originalPaymentInfo.sourceCurrency`	Currency for the remitter account.	A
`originalPaymentInfo.sourceAmount`	Amount being sent by the remitter.	N
`originalPaymentInfo.targetCurrency`	Currency for the payee's account.	A
`originalPaymentInfo.targetAmount`	Amount being received by the payee.	N
`paymentResult.beneficiaryData.beneficiaryAccountNumber`	Payee bank account number. Either account number or IBAN must be provided.	String
`paymentResult.beneficiaryData.iban`	Payee IBAN. Either account number or IBAN must be provided.	AN
`paymentResult.beneficiaryData.payee`	Name of the payee.	AN
`paymentResult.statementData.accountNumber`	Payee account number.	String
`paymentResult.statementData.transferType`	Type of the transaction used to filter out statement's entries.	String
`paymentResult.statementData.postingDate`	Posting date of the specific statement item.	DateTime in UTC format
`paymentResult.statementData.fxRate`	Rate applied for FX conversion.	Number (Decimal)
`paymentResult.statementData.statementNumber`	Statement number.	Number (Integer)
`paymentResult.estimatedSettlementDate`	The estimated date for which the beneficiary should expect to receive their funds.	Date (YYYY-MM-DD)

Example Notification Success:

{
  "PaymentOutNotification": {
    "paymentDetails": {
      "originalPaymentInfo": {
        "ubr": "PO00SKZZ",
        "entity": "001812",
        "apiRequestReference": "Notification Test Stage 09/11/2023 07:34:32",
        "transactionReference": "Notification Test Stage 09/11/2023 07:34:32",
        "narrative": "",
        "countryCode": "US",
        "sourceCurrency": "USD",
        "sourceAmount": "1.07",
        "targetCurrency": "USD",
        "targetAmount": "0.00"
      },
      "paymentResult": {
        "beneficiaryData": {
          "beneficiaryAccountNumber": "12345678",
          "iban": "",
          "payee": "Notification Test Stage"
        },
        "statementData": {
          "accountNumber": "0018120000001001",
          "transferType": "PAYOUT",
          "postingDate": "2023-11-09T07:39:02",
          "fxRate": "",
          "statementNumber": "347"
        },
        "estimatedSettlementDate": "2023-11-13"
      }
    }
  }
}

Important

Please note that the transferType value might be different depending on your country location. To get more information please contact your Relationship Manager.

Your Response

Field Name	Description	Data Type/Format
`PaymentOutNotificationResult`	String up to 7 characters. Mandatory. Set to SUCCESS or ERROR.	String

{
	"PaymentOutNotificationResponse": {
		"PaymentOutNotificationResult":"SUCCESS"
	}	
}

Important

The only required detail in your response is a 'success' presence.

Payout Reversal:

It's possible for a payment to fail for a number of reasons outside of our control. There are two types of failures. This notification is sent when the downstream payout partner or the validation rules have rejected the payout. This notification also confirms the credit back to your account.

REVERSAL

The payout was rejected by:

Us 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 our 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 the same settlement route, which means it can be returned many days later.

Both of these failures result in your Worldpay account being credited.

Field Name	Description	Data Type/Format
`originalPaymentInfo.ubr`	Unique reference associated with a payout.	AN
`originalPaymentInfo.entity`	Unique `entity` given during the onboarding process. This is the entity the funds are debited from.	AN
`originalPaymentInfo.apiRequestReference`	Unique reference for the request.	String
`originalPaymentInfo.transactionReference`	Merchant's unique reference for the payout request.	AN
`originalPaymentInfo.narrative`	Reference that may appear on the payee statement.	String
`originalPaymentInfo.countryCode`	Country of payout destination	A
`originalPaymentInfo.sourceCurrency`	Currency for the remitter account.	A
`originalPaymentInfo.sourceAmount`	Amount being sent by the remitter.	N
`originalPaymentInfo.targetCurrency`	Currency for the payee's account.	A
`originalPaymentInfo.targetAmount`	Amount being received by the payee.	N
`paymentResult.beneficiaryData.beneficiaryAccountNumber`	Payee bank account number. Either account number or IBAN must be provided.	String
`paymentResult.beneficiaryData.iban`	Payee IBAN. Either account number or IBAN must e provided.	AN
`paymentResult.beneficiaryData.payee`	Name of the payee.	AN
`credit.merchantAccountNumber`	Your account number. The first 6 characters indicate your `entity` (domain ID). The rest determines the specific account number.	String
`credit.itemNumber`	Your statement number.	N
`credit.statementId`	Your statement ID.	String (AN)
`credit.postingDate`	Posting date of the specific statement item.	DateTime in UTC format
`credit.creditCurrency`	Currency for your Credit Account	A
`credit.creditAmount`	Amount to be credited to you.	N
`credit.fxRate`	Rate applied for FX conversion.	Number (Decimal)
`credit.transferType`	Transfer Type.	String
`debit.merchantAccountNumber`	Payee account number. The first 6 characters indicate your `entity` (domain ID). The rest determines the specific account number.	String
`debit.itemNumber`	Payee statement number.	N
`debit.statementId`	Payee statement ID.	String (AN)
`debit.postingDate`	Posting date of the specific statement item.	DateTime in UTC format
`debit.debitCurrency`	Currency for the payee debit account	A
`debit.debitAmount`	Amount to be debited from the payee account.	N
`debit.fxRate`	Rate applied for FX conversion.	Number (Decimal)
`debit.transferType`	Transfer Type.	String

Example Notification Reversal

{
  "PaymentOutReversalNotification": {
    "reversalInfo": {
      "originalPaymentInfo": {
        "ubr": "PO00SK2E",
        "entity": "001812",
        "apiRequestReference": "Notification Test Stage revs 09/11/2023 08:17:41",
        "transactionReference": "Notification Test Stage revs 09/11/2023 08:17:41",
        "narrative": "",
        "countryCode": "US",
        "sourceCurrency": "USD",
        "sourceAmount": "1.03",
        "targetCurrency": "USD",
        "targetAmount": "0.00"
      },
      "beneficiaryData": {
        "beneficiaryAccountNumber": "12345678",
        "iban": "",
        "payee": "Notification Test Stage revs"
      },
      "credit": {
        "merchantAccountNumber": "0018120000001001",
        "itemNumber": "349",
        "statementId": "7b6aa0f4-d87e-ee11-b58d-0050569b3804",
        "postingDate": "2023-11-09T08:21:19",
        "creditCurrency": "USD",
        "creditAmount": "1.03",
        "fxRate": "",
        "transferType": "PAYOUT REVERSAL"
      },
      "debit": {
        "merchantAccountNumber": "0018120000001001",
        "itemNumber": "348",
        "statementId": "b75fd3a5-d87e-ee11-b58d-0050569b3804",
        "postingDate": "2023-11-09T08:19:06",
        "debitCurrency": "USD",
        "debitAmount": "1.03",
        "fxRate": "",
        "transferType": "PAYOUT"
      }
    }
  }
}

Your Response

Field Name	Description	Data Type/Format
`PaymentOutReversalNotificationResult`	String up to 7 characters. Mandatory. Set to SUCCESS or ERROR.	String

{
	"PaymentOutReversalNotificationResponse": {
		"PaymentOutReversalNotificationResult":"SUCCESS"
	}	
}

Important

The only required detail in your response is a 'success' presence.

Liquidity:

This notification is sent to advise, you have received the funds.

Field Name	Description	Data Type/Format
`originalPaymentInfo.narrative`	Reference that may appear on the statement.	AN
`originalPaymentInfo.bankCurrency`	Currency of the Pay-In bank account.	AN
`originalPaymentInfo.bankAmount`	Amount debited from the remitter's account.	N
`originalPaymentInfo.targetCurrency`	Currency in which the funds are deposited to.	AN
`originalPaymentInfo.targetAmount`	Amount of the deposited funds.	N
`originalPaymentInfo.countryCode`	Country of the Pay-In destination.	A
`originalPaymentInfo.statementDescription`	Description of the Pay-In item on the statement.	A
`statementData.accountNumber`	Account Number of the deposit account.	String
`statementData.transferType`	Type of the transaction used to filter out statement entries.	String
`statementData.postingDate`	Posting date of the specific statement item.	DateTime in UTC format
`statementData.fxRate`	Rate applied for FX conversion.	Number (Decimal)
`statementData.statementNumber`	Statement number for the deposit.	Number (Integer)

Example Notification Liquidity:

{
  "PaymentNotification": {
    "paymentDetails": {
      "originalPaymentInfo": {
        "narrative": "",
        "bankCurrency": "USD",
        "bankAmount": "0.10",
        "targetCurrency": "GBP",
        "targetAmount": "0.07",
        "countryCode": "GB",
        "statementDescription": "TestData1"
      },
      "statementData": {
        "accountNumber": "0005400000001050",
        "transferType": "LIQUIDITY",
        "postingDate": "2023-11-09T09:01:39",
        "fxRate": "0.68160",
        "statementNumber": "240629"
      }
    }
  }
}

Your Response

Field Name	Description	Data Type/Format
`PaymentNotificationResult`	String up to 7 characters. Mandatory. Set to SUCCESS or ERROR.	String

{
	"PaymentNotificationResponse": {
		"PaymentNotificationResult":"SUCCESS"
	}	
}

Important

The only required detail in your response is a 'success' presence.

Pay-In:

This notification is sent to advise, that you have received the funds from your customer.

Field Name	Description	Data Type/Format
`originalPaymentInfo.narrative`	Reference that may appear on the statement.	AN
`originalPaymentInfo.bankCurrency`	Currency of the Pay-In bank account.	AN
`originalPaymentInfo.bankAmount`	Amount debited from the remitter's account.	N
`originalPaymentInfo.targetCurrency`	Currency in which the funds are deposited to.	AN
`originalPaymentInfo.targetAmount`	Amount of the deposited funds.	N
`originalPaymentInfo.countryCode`	Country of the Pay-In destination.	A
`originalPaymentInfo.statementDescription`	Description of the Pay-In item on the statement.	A
`statementData.accountNumber`	Account Number of the deposit account.	String
`statementData.transferType`	Type of the transaction used to filter out statement entries.	String
`statementData.postingDate`	Posting date of the specific statement item.	DateTime in UTC format
`statementData.fxRate`	Rate applied for FX conversion.	Number (Decimal)
`statementData.statementNumber`	Statement number for the deposit.	Number (Integer)

Example Notification Pay-In:

{
  "PaymentNotification": {
    "paymentDetails": {
      "originalPaymentInfo": {
        "narrative": "",
        "bankCurrency": "USD",
        "bankAmount": "0.10",
        "targetCurrency": "GBP",
        "targetAmount": "0.07",
        "countryCode": "GB",
        "statementDescription": "TestData1"
      },
      "statementData": {
        "accountNumber": "0005400000001050",
        "transferType": "LIQUIDITY",
        "postingDate": "2023-11-09T09:01:39",
        "fxRate": "0.68160",
        "statementNumber": "240629"
      }
    }
  }
}

Your response

Field Name	Description	Data Type/Format
`PaymentNotificationResult`	String up to 7 characters.Mandatory. Set to SUCCESS or ERROR.	String

{
	"PaymentNotificationResponse": {
		"PaymentNotificationResult":"SUCCESS"
	}	
}

Important

The only required detail in your response is a 'success' presence.

Notifications of Change (NOC) US:

NOCs indicate that a beneficiary's bank details have changed, e.g. due to a merger between banks that would update the routing number.

Field Name	Description	Data Type/Format
`notificationId`	Unique reference number for the NOC.	GUID
`createdDate`	Creation date of the item.	DateTime in UTC format
`originalData.companyName`	Original company name.	String
`originalData.effectiveDate`	Effective date.	String
`originalData.originalTraceNumber`	Original trace number.	String
`originalData.traceNumber`	Original trace number.	String
`originalData.originalRDFIIdentification`	Original RDFIIdentification.	String
`originalData.individualName`	Original individual name.	String
`originalData.originalAccountNumber`	Original account number.	String
`originalData.originalABARoutingNumber`	Original ABA routing number.	String
`originalData.originalAccountType`	Original account type.	String
`originalData.NOCReasonCode`	NOC reason Code.	String
`originalData.NOCDescription`	NOC description.	String
`newData.newIndividualName`	New individual name.	String
`newData.newAccountNumber`	New account number.	String
`newData.newABARoutingNumber`	New ABA routing number.	String
`newData.newAccountType`	New account type.	String

Example NOC US:

{
    "notificationId": "550e8400-e29b-41d4-a716-446655440000",
    "createdDate": "05/04/2025 14:48:00",
    "originalData": {
        "companyName": "Worldpay",
        "effectiveDate": "04/04/2025 14:48:00",
        "originalTraceNumber": "PO000PVU",
        "traceNumber": "011500120000001",
        "originalRDFIIdentification": "02100008",
        "individualName": "",
        "originalAccountNumber": "65897456321547854",
        "originalABARoutingNumber": "02100008",
        "originalAccountType": "Checking credit",
        "NOCReasonCode": "C01",
        "NOCDescription": "Incorrect DFI Account Number"
    },
    "newData": {
        "newIndividualName": "",
        "newAccountNumber": "30216589784562103",
        "newABARoutingNumber": "02100008",
        "newAccountType": "Checking credit"
    }
}

Your Response

Field Name	Description	Data Type/Format
`NOCNotificationResult`	String up to 7 characters. Mandatory. Set to SUCCESS or ERROR.	String

{
	"NOC_USResponse": {
		"NOCNotificationResult":"SUCCESS"
	}	
}

Important

The only required detail in your response is a 'success' presence.

Notification of Change (NOC) CA :

The NOC CA indicates that a beneficiary's bank details have changed.

Field Name	Description	Data Type/Format
`notificationId`	Unique reference number for the NOC.	GUID
`createdDate`	Creation date of the item.	DateTime in UTC format
`originalData.companyName`	Original company name.	String
`originalData.effectiveDate`	Effective date.	String
`originalData.originalTraceNumber`	Original trace number.	String
`originalData.traceNumber`	Trace number.	String
`originalData.individualName`	Original individual name.	String
`originalData.originalAccountNumber`	Original account number.	String
`originalData.originalTransitNumber`	Original transit number.	String
`originalData.originalInstitutionNumber`	Original institution type.	String
`newData.newAccountNumber`	New account number.	String
`newData.newTransitNumber`	New transit number.	String
`newData.newInstitutionNumber`	New institution number .	String

Example NOC CA:

{
    "notificationId": "550e8400-e29b-41d4-a716-446655440000",
    "createdDate": "05/04/2025 14:48:00",
    "originalData": {
        "companyName": "Worldpay",
        "effectiveDate": "04/04/2025 14:48:00",
        "originalTraceNumber": "PO000PVU",
        "traceNumber": "011500120000001",
        "individualName": "",
        "originalAccountNumber": "65897456321547854",
        "originalTransitNumber": "",
        "originalInstitutionNumber": ""
    },
    "newData": {
        "newAccountNumber": "30216589784562103",
        "newTransitNumber": "",
        "newInstitutionNumber": ""
    }
}

Your Response

Field Name	Description	Data Type/Format
`NOCNotificationResult`	String up to 7 characters. Mandatory. Set to SUCCESS or ERROR.	String

{
	"NOC_CAResponse": {
		"NOCNotificationResult":"SUCCESS"
	}	
}

Important

The only required detail in your response is a 'success' presence.

Notifications

How does it work?

Payout Success:

Example Notification Success:

Your Response

Payout Reversal:

REVERSAL

RETURN

Example Notification Reversal

Your Response

Liquidity:

Example Notification Liquidity:

Your Response

Pay-In:

Example Notification Pay-In:

Your response

Notifications of Change (NOC) US:

Example NOC US:

Your Response

Notification of Change (NOC) CA :

Example NOC CA:

Your Response

Do you like our page?