Open-banking consent, authentication, API, payment-initiation, callback, and status architecture

Customer and merchant experience

Captures the order and displays the bank-account payment option without collecting the customer's bank credentials.

Kind

channel

Owner

Merchant product owner

Responsibilities

• Create a stable order and payment intent
• Explain redirect, decoupled, pending, and failed states

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Amount and payee integrity
• No bank credential capture
• Accessible return journey

Failure modes

• Customer abandons authentication
• Merchant creates a second payment intent

Recovery

• Resume the original payment by stable reference
• Allow a deliberate new attempt only after showing the first state

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Payment-initiation service provider

Creates consent, selects the account provider, submits the authorised instruction, and retrieves status.

Kind

gateway

Owner

Payment-initiation service provider

Responsibilities

• Bind consent to payment details
• Keep consent, authorisation, payment, and merchant references distinct

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Client identity
• Consent scope
• Request signing
• Idempotency

Failure modes

• Consent reused outside scope
• Payment submitted twice
• Status callback lost

Recovery

• Reject invalid consent
• Query the original payment before resubmission

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Directory, trust, and discovery

Publishes trusted participant identity, endpoint, certificate, and capability information.

Kind

security

Owner

Open-banking ecosystem or bilateral trust owner

Responsibilities

• Resolve the correct account-provider endpoint
• Validate participant and certificate status

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Certificate chain
• Participant role
• Endpoint and profile version

Failure modes

• Stale directory
• Revoked participant still accepted
• Wrong endpoint

Recovery

• Fail closed for new initiation
• Refresh signed trust material and record the incident

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Account-provider API gateway

Authenticates the payment-initiation service provider, validates the request, and protects the bank boundary.

Kind

gateway

Owner

Account-servicing payment-service provider

Responsibilities

• Validate transport and application identity
• Apply schema, consent, rate, replay, and idempotency controls

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Mutual authentication
• Request integrity
• Replay prevention
• Rate and size limits

Failure modes

• Invalid signature
• Rate limit
• Unavailable API

Recovery

• Return a precise error without exposing bank internals
• Recover using the tested service path

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Bank authentication and consent service

Authenticates the customer and confirms the payment details and account under the bank's applicable rules.

Kind

control

Owner

Account provider identity and channel team

Responsibilities

• Authenticate without disclosing credentials to the PISP
• Bind the customer's approval to amount, currency, payee, and account

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Strong-customer-authentication policy
• Dynamic transaction binding
• Consent expiry

Failure modes

• Customer authenticates but payment details change
• Consent expires
• Decoupled journey times out

Recovery

• Reject changed details
• Return a distinct expired or abandoned state

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Bank payment engine and controls

Validates account, funds, limits, fraud, sanctions, routing, and rail rules before accepting the instruction.

Kind

application

Owner

Account-provider payments team

Responsibilities

• Create one bank payment from the authorised request
• Return a bank payment identifier and honest state

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Account authority
• Funds and limits
• Fraud and sanctions
• Rail eligibility

Failure modes

• Accepted API request but rejected rail instruction
• Bank payment duplicated
• Screening hold

Recovery

• Preserve the last confirmed state
• Repair or reject through the bank's normal payment process

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Status, callback, and event service

Publishes state changes and supports explicit retrieval when a callback is late, duplicated, or lost.

Kind

service

Owner

Account provider and PISP platform teams

Responsibilities

• Expose monotonic business status
• Sign and correlate callbacks
• Support status polling within policy

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Authenticated callback
• Event deduplication
• No backward state transition without reason

Failure modes

• Callback delivered twice
• Callback lost
• Status arrives out of order

Recovery

• Deduplicate by event identifier
• Retrieve the authoritative payment state

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Merchant order, refund, and reconciliation

Matches merchant order, bank payment, rail outcome, settlement or credit evidence, and any refund or return.

Kind

operations

Owner

Merchant finance and payment operations

Responsibilities

• Fulfil under an explicit status policy
• Reconcile by stable references rather than customer screenshots

Inputs

• Authorised business instruction and correlated state

Outputs

• Versioned result, status, and audit evidence

Controls

• Order-to-payment match
• Settlement evidence
• Refund and return linkage

Failure modes

• Goods released on a provisional state
• Paid order remains open
• Refund duplicates a bank return

Recovery

• Hold fulfilment when policy requires
• Query the original state and reconcile all value movements

Non-functional requirements

• Durable correlation through stable business and technical identifiers
• Capacity and availability matched to the service-level objective
• Auditable state changes, configuration, and operator actions

Payment intent and consent request

ob-user-merchant → ob-pisp

Carry order, amount, currency, payee, and return context.

Contract

api · synchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Do not create another intent when the response is uncertain.

Participant and endpoint lookup

ob-pisp → ob-directory

Resolve trusted identity, endpoint, and supported profile.

Contract

api · synchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Fail closed when current trust evidence is unavailable.

Consent and payment API

ob-pisp → ob-aspsp-api

Create consent and submit an authorised payment under the agreed profile.

Contract

api · synchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Return rejected, pending, accepted, and uncertain states distinctly.

Customer authentication hand-off

ob-aspsp-api → ob-auth-consent

Move authentication to the bank while preserving the payment context.

Contract

api · synchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Reject any mismatch between approved and submitted payment details.

Authorised payment instruction

ob-auth-consent → ob-payment-engine

Release only the customer-approved payment to bank controls.

Contract

control · asynchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Keep expired, abandoned, or changed consent outside payment processing.

Payment state event

ob-payment-engine → ob-status-events

Publish bank and rail state with stable identifiers.

Contract

event · asynchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Store for redelivery and preserve event order.

Callback or status response

ob-status-events → ob-pisp

Return authenticated payment state to the PISP.

Contract

api · asynchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Deduplicate callbacks and query the authoritative state after gaps.

Merchant return and status

ob-pisp → ob-user-merchant

Show the customer and merchant an honest outcome.

Contract

api · asynchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Do not turn a missing callback into a failure or a success.

Settlement and reporting evidence

ob-payment-engine → ob-merchant-recon

Provide payment, credit, return, and reporting references for reconciliation.

Contract

message · asynchronous

Controls

• Authentication and authorisation
• Integrity and replay protection
• Correlation and audit evidence

Failure treatment

Open a case when merchant and bank states disagree.

Consent to merchant status

Follow a payment initiation without exposing bank credentials to the PISP or merchant.

1. Choose account payment — Merchant intent created. The merchant fixes order, amount, currency, and payee.
2. Create consent — Consent requested. The PISP creates a scoped request under the bank's supported profile.
3. Protect the bank boundary — PISP authenticated. The bank validates the PISP, request, and consent context.
4. Authenticate and approve — Customer authorised. The customer authenticates with the bank and approves the bound payment details.
5. Process the payment — Bank payment accepted or rejected. Normal account, fraud, sanctions, funds, limit, and rail controls apply.
6. Publish the state — Authoritative status available. The bank emits a correlated status and supports retrieval if delivery fails.
7. Reconcile the order — Order and payment aligned. The merchant combines status with settlement or credit evidence before close.

Customer abandons authentication

The user closes the bank journey before a confirmed outcome.

Last confirmed state

Consent exists; customer authorisation is not confirmed.

Settlement

No settlement has occurred.

Funds and entries

No payment debit is confirmed.

Next owner

PISP customer operations

Safe action

Show pending or abandoned accurately and query before offering a new attempt.

Evidence required

• Consent ID
• Bank authentication state
• Payment ID if created

Recovery

• Expire or resume under the bank rules
• Keep a later attempt distinct

Callback is lost

The bank payment advances but the PISP receives no callback.

Last confirmed state

The bank payment has an authoritative state.

Settlement

Settlement depends on that state and the underlying rail.

Funds and entries

Funds may have moved even though the merchant page is pending.

Next owner

PISP platform operations

Safe action

Retrieve status by the original payment identifier; never submit another payment to discover the first outcome.

Evidence required

• Payment ID
• Event log
• Status response
• Merchant reference

Recovery

• Recover the authoritative status
• Redeliver or update the merchant once
• Reconcile settlement evidence

Payment later returns

The merchant saw an accepted state but the bank payment returns.

Last confirmed state

The payment was accepted and later returned.

Settlement

Any earlier settlement must be considered separately from the return.

Funds and entries

The return is a new linked value movement.

Next owner

Merchant payment operations

Safe action

Update order and finance state from the linked return; do not rewrite the original accepted state.

Evidence required

• Original payment ID
• Return reference
• Credit or debit advice

Recovery

• Record the return
• Apply customer and order policy
• Reconcile both movements

Which payment state may trigger merchant fulfilment?

• Settlement or credit evidenced — Reduces false fulfilment but can delay delivery.
• Earlier accepted state — Can improve customer experience but requires explicit risk, value, and return policy.

Publish the fulfilment policy separately from the API status model and test late, returned, and contradictory outcomes.

Are callbacks the source of truth?

• Callback as notification — The receiver can retrieve authoritative state after gaps or duplicates.
• Callback as sole state — Creates uncertainty when delivery is lost or arrives out of order.

Treat callbacks as delivery; treat the bank payment record as authoritative.