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. The final response is therefore 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 payout/debit, as well as successful credits to your account.

You must respond a 'success' message 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:

You receive this when we have sent the payout successfully to the downstream payout partner and they are now processing the request. The payout 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 NameDescriptionData Type/Format
originalPaymentInfo.payoutRequestIDUnique reference associated with a payout.AN
originalPaymentInfo.entityUnique ID given to you during the onboarding process. This is the entity the funds are debited from.AN
originalPaymentInfo.idempotencyKeyUnique reference for the request.String
originalPaymentInfo.transactionReferenceMerchant's unique reference for the payout request.AN
originalPaymentInfo.narrativeReference that may appear on the payee statement.String
originalPaymentInfo.countryCodeCountry of the payout destination.A
originalPaymentInfo.sourceCurrencyCurrency for the remitter account.A
originalPaymentInfo.sourceAmountAmount being sent by the remitter.N
originalPaymentInfo.targetCurrencyCurrency for the payee's account.A
originalPaymentInfo.targetAmountAmount being received by the payee.N
originalPaymentInfo.paymentStateThe current status of the payout.String
paymentResult.beneficiaryData.payoutInstrumentReferenceA reference of the payoutInstrument created by you. This field holds the beneficiary bank details.String
paymentResult.beneficiaryData.accountNumberPayee bank account number. Either account number or IBAN must be provided.String
paymentResult.beneficiaryData.ibanPayee IBAN. Either account number or IBAN must be provided.AN
paymentResult.beneficiaryData.payeeName of the payee.AN
paymentResult.statementData.accountNumberPayee account number.String
paymentResult.statementData.partyReferenceYour reference for this party.String
paymentResult.statementData.transferTypeType of the transaction used to filter out statement's entries.String
paymentResult.statementData.timestampPosting date of the specific statement item.DateTime in UTC format
paymentResult.statementData.rateRate applied for FX conversion.Number (Decimal)
paymentResult.statementData.statementNumberStatement number.Number (Integer)
paymentResult.estimatedSettlementDateThe estimated date for which the beneficiary should expect to receive their funds.Date (YYYY-MM-DD)

Example notification success:

{
  "PaymentOutNotification": {
    "paymentDetails": {
      "originalPaymentInfo": {
        "payoutRequestID": "PZBKQKQT",
        "entity": "Titan",
        "idempotencyKey": "hsKPmmGYuD4QtJx",
        "transactionReference": "Test ref1234",
        "narrative": "Ref:9745",
        "countryCode": "GB",
        "sourceCurrency": "EUR",
        "sourceAmount": "0.00",
        "targetCurrency": "USD",
        "targetAmount": "10.00",
        "paymentState": "COMPLETED"
      },
      "paymentResult": {
        "beneficiaryData": {
          "payoutInstrumentReference": "Valid PI Ref",
          "accountNumber": "",
          "iban": "GB33BUKB20201555555555",
          "payee": "John DoeB"
        },
        "statementData": {
          "accountNumber": "0018120000001001",
          "partyReference": "Driver_Bond",
          "transferType": "BANKOUT",
          "timestamp": "2025-03-25T10:23:03",
          "rate": "1.08708",
          "statementNumber": "14"
        },
        "estimatedSettlementDate": "2025-03-25"
      }
    }
  }
}
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 NameDescriptionData Type/Format
PaymentOutNotificationResultString up to 7 characters. Mandatory. Set to SUCCESS or ERROR.String

Example response

{
	"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 or 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 or account is closed). The PAYOUT_RETURN is 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 NameDescriptionData Type/Format
originalPaymentInfo.payoutRequestIDUnique reference associated with a payout.AN
originalPaymentInfo.entityUnique entity given during the onboarding process. This is the entity the funds are debited from.AN
originalPaymentInfo.idempotencyKeyUnique reference for the request.String
originalPaymentInfo.transactionReferenceMerchant's unique reference for the payout request.AN
originalPaymentInfo.narrativeReference that may appear on the payee statement.String
originalPaymentInfo.countryCodeCountry of payout destinationA
originalPaymentInfo.sourceCurrencyCurrency for the remitter account.A
originalPaymentInfo.sourceAmountAmount being sent by the remitter.N
originalPaymentInfo.targetCurrencyCurrency for the payee's account.A
originalPaymentInfo.targetAmountAmount being received by the payee.N
originalPaymentInfo.paymentStateThe current status of the payout.String
paymentResult.beneficiaryData.payoutInstrumentReferenceA reference of the payoutInstrument created by you. This field holds the beneficiary bank details.String
paymentResult.beneficiaryData.accountNumberPayee bank account number. Either account number or IBAN must be provided.String
paymentResult.beneficiaryData.ibanPayee IBAN. Either account number or IBAN must e provided.AN
paymentResult.beneficiaryData.payeeName of the payee.AN
credit.merchantAccountNumberYour account number. The first 6 characters indicate your entity (domain ID). The rest determines the specific account number.String
credit.partyReferenceYour reference for this party.String
credit.itemNumberYour statement number.N
credit.statementIdYour statement ID.String (AN)
credit.timestampPosting date of the specific statement item.DateTime in UTC format
credit.creditCurrencyCurrency for your Credit AccountA
credit.creditAmountAmount to be credited to you.N
credit.rateRate applied for FX conversion.Number (Decimal)
credit.transferTypeTransfer Type.String
debit.merchantAccountNumberPayee account number. The first 6 characters indicate your entity (domain ID). The rest determines the specific account number.String
debit.partyReferenceYour reference for this party.String
debit.itemNumberPayee statement number.N
debit.statementIdPayee statement ID.String (AN)
debit.timestampPosting date of the specific statement item.DateTime in UTC format
debit.debitCurrencyCurrency for the payee debit accountA
debit.debitAmountAmount to be debited from the payee account.N
debit.rateRate applied for FX conversion.Number (Decimal)
debit.transferTypeTransfer Type.String

Example notification reversal

{
  "PaymentOutReversalNotification": {
    "reversalInfo": {
      "originalPaymentInfo": {
        "payoutRequestID": "PZBKQKQT",
        "entity": "Titan",
        "idempotencyKey": "hsKPmmGYuD4QtJx",
        "transactionReference": "Test ref1234",
        "narrative": "Ref:9745",
        "countryCode": "GB",
        "sourceCurrency": "EUR",
        "sourceAmount": "0.00",
        "targetCurrency": "USD",
        "targetAmount": "10.00",
        "paymentState": "REVERSED"
      },
      "beneficiaryData": {
        "payoutInstrumentReference": "Valid PI Ref",
        "accountNumber": "",
        "iban": "GB33BUKB20201555555555",
        "payee": "John DoeB"
      },
      "credit": {
        "merchantAccountNumber": "0018120000001001",
        "partyReference": "Driver_Bond",
        "itemNumber": "15",
        "statementId": "7b6aa0f4-d87e-ee11-b58d-0050569b3804",
        "timestamp": "2025-03-25T12:51:40",
        "creditCurrency": "EUR",
        "creditAmount": "9.20",
        "rate": "",
        "transferType": "PAYOUT REVERSAL",
        "reversalReason": "Return of original statement entry #14. PAYOUT RETURNED: Account closed.John DoeB"
      },
      "debit": {
        "merchantAccountNumber": "0018120000001001",
        "partyReference": "Driver_Bond",
        "itemNumber": "14",
        "statementId": "b75fd3a5-d87e-ee11-b58d-0050569b3804",
        "timestamp": "2025-03-25T10:23:03",
        "debitCurrency": "EUR",
        "debitAmount": "10.00",
        "rate": "1.08708",
        "transferType": "BANKOUT"
      }
    }
  }
}

Your response

Field NameDescriptionData Type/Format
PaymentOutReversalNotificationResultString up to 7 characters. Mandatory. Set to SUCCESS or ERROR.String

Example response

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

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

Liquidity

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

Field NameDescriptionData Type/Format
originalPaymentInfo.narrativeReference that may appear on the statement.AN
originalPaymentInfo.bankCurrencyCurrency of the Pay-In bank account.AN
originalPaymentInfo.bankAmountAmount debited from the remitter's account.N
originalPaymentInfo.targetCurrencyCurrency in which the funds are deposited to.AN
originalPaymentInfo.targetAmountAmount of the deposited funds.N
originalPaymentInfo.countryCodeCountry of the Pay-In destination.A
originalPaymentInfo.statementDescriptionDescription of the Pay-In item on the statement.A
statementData.accountNumberAccount Number of the deposit account.String
statementData.transferTypeType of the transaction used to filter out statement entries.String
statementData.timestampPosting date of the specific statement item.DateTime in UTC format
statementData.rateRate applied for FX conversion.Number (Decimal)
statementData.statementNumberStatement number for the deposit.Number (Integer)

Example notification liquidity

{
  "PaymentNotification": {
    "paymentDetails": {
      "originalPaymentInfo": {
        "narrative": "",
        "bankCurrency": "NZD",
        "bankAmount": "2.00",
        "targetCurrency": "GBP",
        "targetAmount": "0.92",
        "countryCode": "NZ",
        "statementDescription": "/EVTGBLIQFUND123576/NZD2,00/MREF/P/R/"
      },
      "statementData": {
        "accountNumber": "0005400000001050",
        "transferType": "LIQUIDITY",
        "timestamp": "2025-03-04T09:01:39",
        "rate": "0.46134",
        "statementNumber": "68288"
      }
    }
  }
}

Your response

Field NameDescriptionData Type/Format
PaymentNotificationResultString up to 7 characters. Mandatory. Set to SUCCESS or ERROR.String

Example response

{
	"PaymentOutNotificationResponse": {
		"PaymentOutNotificationResult":"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 NameDescriptionData Type/Format
originalPaymentInfo.narrativeReference that may appear on the statement.AN
originalPaymentInfo.bankCurrencyCurrency of the Pay-In bank account.AN
originalPaymentInfo.bankAmountAmount debited from the remitter's account.N
originalPaymentInfo.targetCurrencyCurrency in which the funds are deposited to.AN
originalPaymentInfo.targetAmountAmount of the deposited funds.N
originalPaymentInfo.countryCodeCountry of the Pay-In destination.A
originalPaymentInfo.statementDescriptionDescription of the Pay-In item on the statement.A
statementData.accountNumberAccount Number of the deposit account.String
statementData.transferTypeType of the transaction used to filter out statement entries.String
statementData.timestampPosting date of the specific statement item.DateTime in UTC format
statementData.rateRate applied for FX conversion.Number (Decimal)
statementData.statementNumberStatement number for the deposit.Number (Integer)

Example notification Pay-In

{
  "PaymentNotification": {
    "paymentDetails": {
      "originalPaymentInfo": {
        "narrative": "EVTGB1234567",
        "bankCurrency": "NZD",
        "bankAmount": "2.00",
        "targetCurrency": "GBP",
        "targetAmount": "0.92",
        "countryCode": "NZ",
        "statementDescription": "/EVTGB1234567/NZD2,00/MREF/P/R/BI/"
      },
      "statementData": {
        "accountNumber": "0000550000000005",
        "transferType": "PAYIN",
        "timestamp": "2025-02-28T08:50:39",
        "rate": "0.46134",
        "statementNumber": "1980"
      }
    }
  }
}

Your response

Field NameDescriptionData Type/Format
PaymentNotificationResultString up to 7 characters.Mandatory. Set to SUCCESS or ERROR.String

Example response

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

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