Payment lifecycle

How payments move through Mercury. GBP Faster Payments and EUR SEPA Credit Transfers, from submission to settlement.

GBP Faster Payments

Faster Payments (FPS) is the UK's near-instant payment scheme. Payments are available 24/7 including weekends and bank holidays.

GBP payment status flow

Every outbound GBP payment follows this sequence. Your integration should handle each status via webhooks.

Pending

API response

→

Approved

Compliance passed

→

Settled

Funds delivered

Rejected

Scheme or compliance

Held

Manual review

Validation Failed

Scheme-level

Assessment Failed

Sanctions/compliance

Status	Meaning	Webhook	Action
Pending	Payment accepted, processing started	Synchronous (API response)	Store PaymentId, await webhooks
Approved	Passed compliance checks, submitted to FPS scheme	PaymentStatusChanged	Update internal status
Settled	Funds confirmed delivered to creditor	TransactionSettled	Mark complete, notify user
Rejected	Rejected by scheme or compliance controls	TransactionRejected	Log reason code, alert ops
Held	Flagged for manual review before scheme submission	OutboundTransactionHeld	Await resolution, do not retry
Validation Failed	Failed scheme-level validation after submission	PaymentValidationFailed	Check reason, fix and resubmit
Assessment Failed	Failed sanctions or compliance assessment	PaymentAssesmentFailed	Escalate to compliance team

Submit a GBP payment

Send an outbound GBP payment via Faster Payments.

POST/api/v1/payments

{
  "reference": "CLIENT-001",
  "endToEndIdentifier": "E2E-20260413-001",
  "debtor": {
    "iban": "GB71CLRB04082700001159",
    "paymentAmount": {
      "currencyCode": "GBP",
      "amount": 500
    },
    "paymentReference": "Invoice 2026-001"
  },
  "creditor": {
    "accountName": "John Smith",
    "accountNumber": "55779911",
    "sortCode": "200000"
  }
}

{
  "Payment": {
    "PaymentId": "764b7d22-9fa0-43bb-920e-326e8634b0f8",
    "Reference": "CLIENT-001",
    "Debtor": {
      "Iban": "GB71CLRB04082700001159",
      "PaymentAmount": {
        "CurrencyCode": "GBP",
        "Amount": 500
      },
      "PaymentReference": "Invoice 2026-001",
      "Name": "Acme Ltd"
    },
    "Creditor": {
      "AccountName": "John Smith",
      "AccountNumber": "55779911",
      "SortCode": "200000",
      "Iban": "GB60BARC20000055779911"
    },
    "Status": "Pending",
    "Message": "Payment has been successfully requested and is now being processed"
  }
}

Max Amount1,000,000 GBP per payment

Availability24/7 including weekends and holidays

Creditor OptionsIBAN or Account Number + Sort Code

End-to-End IDMust be unique, never previously submitted

GBP request fields

Field	Required	Description
reference	Yes	Mercury-assigned client reference (from POST /api/v1/client)
endToEndIdentifier	Yes	Unique payment identifier. Must never have been previously submitted.
debtor.iban	Yes	Active GBP virtual IBAN belonging to the client
debtor.paymentAmount	Yes	Object with currencyCode ("GBP") and amount (max 1,000,000)
debtor.paymentReference	Yes	Reference shown on the payee's bank statement
creditor.accountName	Yes	Full legal name of the account holder
creditor.iban	Either	Destination IBAN. Provide this OR accountNumber + sortCode.
creditor.accountNumber	Either	UK account number. Must be paired with sortCode.
creditor.sortCode	Either	6-digit UK sort code (e.g. "040004"). Must be paired with accountNumber.
confirmationOfPayeeCheckId	No	Link to a previous CoP check on the client's record
creditor.emailAddress	No	Creditor email. Must be valid format if provided.

EUR SEPA Credit Transfer

SEPA Credit Transfers (SCT) allow EUR payments across the Single Euro Payments Area. Unlike Faster Payments, SEPA operates within specific hours and observes TARGET2 holidays.

Operating hours

Monday to Friday, 06:00 to 14:25 UK time only. Payments submitted outside this window or on TARGET2 holidays (1 January, 1 May, 25-26 December) will be rejected.

EUR payment status flow

EUR payments use a separate set of webhook events prefixed with Mccy (multi-currency).

Pending

API response

→

Complete

Settled by SEPA

Failed

Rejected by scheme

Status	Meaning	Webhook	Action
Pending	Payment accepted, submitted to SEPA scheme	Synchronous (API response)	Store PaymentId
Complete	Accepted and settled by SEPA scheme	MccyOutboundPaymentComplete	Mark complete
Failed	Rejected or failed after submission	MccyOutboundPaymentFailed	Log, alert ops

Submit a EUR payment

Send an outbound EUR payment via SEPA Credit Transfer.

POST/api/v1/euro/payments/sepa-ct

{
  "clientReference": "CLIENT-001",
  "endToEndIdentifier": "E2E-EUR-20260413-001",
  "debtor": {
    "iban": "GB85CLRB04274893940059",
    "paymentAmount": {
      "currencyCode": "EUR",
      "amount": 1000
    },
    "paymentReference": "Invoice EUR-2026-001"
  },
  "creditor": {
    "accountName": "Sender GmbH",
    "iban": "FR7630006000011234567890189"
  }
}

{
  "Payment": {
    "PaymentId": "085440ed-1326-41f4-b4a6-6188dbd42409",
    "Reference": "CLIENT-001",
    "Debtor": {
      "Iban": "GB85CLRB04274893940059",
      "PaymentAmount": {
        "CurrencyCode": "EUR",
        "Amount": 1000
      },
      "PaymentReference": "Invoice EUR-2026-001",
      "Name": "Acme Ltd"
    },
    "Creditor": {
      "AccountName": "Sender GmbH",
      "Iban": "FR7630006000011234567890189"
    },
    "Status": "Pending",
    "Message": "Payment has been successfully requested and is now being processed"
  }
}

Max Amount999,999,999.99 EUR per payment

HoursMon-Fri 06:00-14:25 UK time

CreditorIBAN required (or SWIFT code as fallback)

HolidaysTARGET2: 1 Jan, 1 May, 25-26 Dec

EUR request fields

Field	Required	Description
clientReference	Yes	Mercury-assigned client reference
endToEndIdentifier	Yes	Unique payment identifier. Must never have been previously submitted.
debtor.iban	Yes	Active EUR virtual IBAN belonging to the client
debtor.paymentAmount	Yes	Object with currencyCode ("EUR") and amount (max 999,999,999.99)
debtor.paymentReference	Yes	Reference shown on the payee's bank statement
creditor.accountName	Yes	Full legal name of the account holder
creditor.iban	Yes	Destination IBAN. Must pass mod-97 checksum validation.
creditor.swiftCode	Fallback	SWIFT/BIC code. Required when no IBAN provided. Format: 6 alpha + 2 alphanum + optional 3 alphanum.

GBP vs EUR: key differences

The two payment rails differ in naming, availability, and webhook events. Here is a side-by-side comparison.

	GBP Faster Payments	EUR SEPA CT
Endpoint	/api/v1/payments	/api/v1/euro/payments/sepa-ct
Client ref field	reference	clientReference
Availability	24/7	Mon-Fri 06:00-14:25 UK
Max amount	1,000,000	999,999,999.99
Creditor routing	IBAN or Acc+Sort	IBAN (or SWIFT fallback)
Success webhook	TransactionSettled	MccyOutboundPaymentComplete
Failure webhook	TransactionRejected	MccyOutboundPaymentFailed

Inbound payments

When funds arrive at a client's virtual account, Mercury fires a webhook to notify your system. No API call is needed to receive payments.

GBP inbound

Fired when an inbound FPS payment is credited to the virtual account.

Payments.InboundTransaction

EUR inbound

Fired when an inbound SEPA payment is credited to the virtual account.

Payments.MccyInboundPaymentComplete

Inbound GBP webhook payload

Includes sender details, amount, and the destination account IBAN. Use PaymentId and EndToEndTransactionId for reconciliation.

{
  "Type": "PaymentInboundTransaction",
  "Payload": {
    "TransactionTimestamp": "2026-04-13T10:00:00Z",
    "PaymentId": "TXN-1234",
    "EndToEndTransactionId": "E2E-20260413-001",
    "AccountId": "GB29NWBK60161331926819",
    "Debtor": {
      "AccountName": "John Smith",
      "Iban": "GB60BARC20000055779911",
      "AccountNumber": "55779911",
      "SortCode": "200000",
      "InstitutionName": "Barclays Bank"
    },
    "Creditor": {
      "Iban": "GB29NWBK60161331926819",
      "Amount": 500,
      "Currency": "GBP",
      "Reference": "Invoice payment"
    }
  },
  "Nonce": "XrNcCDMvPN3KvfcU4f+U9Q=="
}

Held payments

Both inbound and outbound payments can be held for manual review. You will receive an InboundTransactionHeld or OutboundTransactionHeld webhook. Do not retry held payments. They will proceed or be rejected after review.

Returning a GBP payment

If you receive a GBP Faster Payment that needs to be sent back (e.g. duplicate payment, incorrect amount), use the return endpoint.

POST/api/v1/payments/return-payment

{
  "transactionId": "TXN-1234",
  "returnReason": "DuplicatePayment"
}

{
  "Message": "Return payment successfully submitted."
}

transactionIdMust be a valid inbound FPS transaction that has not already been returned

returnReasonMust be a valid reason code. Contact Mercury for accepted codes.

Webhook event reference

Complete list of payment webhook events. Subscribe to these to track payment lifecycle in real time.

GBP payment events

Event	Description
TransactionSettled	Outbound FPS payment confirmed as settled
TransactionRejected	Payment rejected by scheme or compliance. Includes CancellationReason and CancellationCode.
PaymentStatusChanged	Status transition during processing (e.g. Pending to Approved)
PaymentValidationFailed	Failed scheme-level validation after submission. Includes failure reasons.
PaymentAssesmentFailed	Failed sanctions or compliance assessment. Includes failure reasons.
OutboundTransactionHeld	Outbound payment held for manual review
InboundTransaction	Inbound FPS payment credited to virtual account
InboundTransactionHeld	Inbound payment held for manual review
InboundInternalTransaction	Internal transfer received (between Mercury accounts)
InternalTransferSettled	Internal transfer confirmed as settled

EUR payment events

Event	Description
MccyOutboundPaymentComplete	Outbound SEPA CT accepted and settled by scheme
MccyOutboundPaymentFailed	Outbound SEPA CT rejected or failed after submission
MccyPaymentStatusChanged	EUR payment status transition during processing
MccyInboundPaymentComplete	Inbound SEPA payment credited to virtual account
MccyInboundInternalTransaction	Internal EUR transfer received
MccyInternalTransferSettled	Internal EUR transfer confirmed as settled

Settlement webhook payloads

The two most important webhooks for payment confirmation. Use these to update your system when a payment reaches its final state.

GBP: TransactionSettled

Confirms an outbound FPS payment has been settled. Includes full debtor/creditor details and timestamps.

{
  "Type": "PaymentTransactionSettled",
  "Payload": {
    "Status": "Settled",
    "Scheme": "FasterPayments",
    "EndToEndTransactionId": "E2E-20260413-001",
    "Amount": 500,
    "TimestampCreated": "2026-04-13T08:38:16.757Z",
    "TimestampSettled": "2026-04-13T08:38:17.997Z",
    "CurrencyCode": "GBP",
    "DebitCreditCode": "Debit",
    "Reference": "Invoice 2026-001",
    "PaymentId": "764b7d22-9fa0-43bb-920e-326e8634b0f8",
    "Account": {
      "IBAN": "GB71CLRB04082700001159",
      "BBAN": "CLRB04082700001159",
      "OwnerName": "Acme Ltd"
    },
    "CounterpartAccount": {
      "IBAN": "GB47MONZ04000423900685",
      "OwnerName": "John Smith",
      "InstitutionName": "Monzo"
    },
    "IsReturn": false
  },
  "Nonce": "j8obouk8aHbZbInEMNVkmg=="
}

GBP: TransactionRejected

Fired when a payment is rejected. Includes CancellationReason and CancellationCode for debugging.

{
  "Type": "PaymentTransactionRejected",
  "Payload": {
    "Status": "Rejected",
    "Scheme": "FasterPayments",
    "EndToEndTransactionId": "E2E-20260413-001",
    "Amount": 1000,
    "CurrencyCode": "GBP",
    "CancellationReason": "InvalidAccount",
    "CancellationCode": "AC03",
    "TimestampModified": "2026-04-13T10:06:00Z",
    "Account": {
      "IBAN": "GB29NWBK60161331926819"
    },
    "CounterpartAccount": {
      "BBAN": "20000055779911",
      "IBANClosed": "GB60BARC20000055779911"
    }
  },
  "Nonce": "XrNcCDMvPN3KvfcU4f+U9Q=="
}

EUR: MccyOutboundPaymentComplete

Confirms a SEPA CT has been settled. Leaner payload than GBP. Match on TransactionId or EndToEndIdentification.

{
  "Type": "MccyOutboundPaymentComplete",
  "Payload": {
    "TransactionId": "085440ed-1326-41f4-b4a6-6188dbd42409",
    "EndToEndIdentification": "E2E-EUR-20260413-001",
    "InstructedCurrency": "EUR",
    "InstructedAmount": 1000,
    "TimestampCreated": "2026-04-13T10:22:06",
    "TimestampSettled": "2026-04-13T10:45:54.512Z"
  },
  "Nonce": "f9ALRB5rLEpVwm6bQckAYg=="
}

Integration checklist

Use this checklist to verify your payment integration handles all scenarios.

Outbound payments

Store PaymentId from API response

Generate unique endToEndIdentifier per payment

Handle Pending status (async, await webhooks)

Process TransactionSettled / MccyOutboundPaymentComplete

Process TransactionRejected / MccyOutboundPaymentFailed

Handle Held status (do not retry)

Log PaymentValidationFailed reasons

Escalate PaymentAssesmentFailed to compliance

Validate EUR payments within operating hours

Inbound payments

Listen for InboundTransaction / MccyInboundPaymentComplete

Reconcile using PaymentId + EndToEndTransactionId

Handle InboundTransactionHeld (await resolution)

Handle InboundInternalTransaction for internal transfers

Implement return-payment flow for rejected inbound payments

Respond with HTTP 200 to all webhook deliveries

Next steps

Set up webhooks to receive real-time payment updates, then test the full payment lifecycle in sandbox.

Webhook Setup Error Handling Authentication