Payments Training Hub
Start with the scenario PAYMENT OPERATIONS STARTED LIVE 01 Start with the scenario - constraints, because they decide which ACTIVE 02 Draw the integration map next - showing every system QUEUED 03 Choose the pattern - write down why you chose it. QUEUED 04 Contract - Define the contract for each interface QUEUED 05 Contract - leaves the error codes undefined will cause QUEUED 06 Certification plan - Add a certification plan with at least ten QUEUED Start with the scenario and the constraints, because they decide which patterns are possible. Step 1 of 6 Start with the scenario STARTED Start with the scenario constraints, because they decide which ACTIVE Draw the integration map next showing every system QUEUED Choose the pattern write down why you chose it. QUEUED Contract Define the contract for each interface QUEUED Contract leaves the error codes undefined will cause QUEUED Certification plan Add a certification plan with at least ten QUEUED Start with the scenario and the constraints, because they decide which patterns are possible.
Draw the integration map next PAYMENT OPERATIONS IN PROGRESS LIVE 01 Start with the scenario - constraints, because they decide which DONE 02 Draw the integration map next - showing every system ACTIVE 03 Choose the pattern - write down why you chose it. QUEUED 04 Contract - Define the contract for each interface QUEUED 05 Contract - leaves the error codes undefined will cause QUEUED 06 Certification plan - Add a certification plan with at least ten QUEUED Draw the integration map next, showing every system, every connection, and the direction of each flow. Step 2 of 6 Draw the integration map next IN PROGRESS Start with the scenario constraints, because they decide which DONE Draw the integration map next showing every system ACTIVE Choose the pattern write down why you chose it. QUEUED Contract Define the contract for each interface QUEUED Contract leaves the error codes undefined will cause QUEUED Certification plan Add a certification plan with at least ten QUEUED Draw the integration map next, showing every system, every connection, and the direction of each flow.
Choose the pattern for each connection PAYMENT OPERATIONS IN PROGRESS LIVE 01 Start with the scenario - constraints, because they decide which DONE 02 Draw the integration map next - showing every system DONE 03 Choose the pattern - write down why you chose it. ACTIVE 04 Contract - Define the contract for each interface QUEUED 05 Contract - leaves the error codes undefined will cause QUEUED 06 Certification plan - Add a certification plan with at least ten QUEUED Choose the pattern for each connection and write down why you chose it. Step 3 of 6 Choose the pattern for each connection IN PROGRESS Start with the scenario constraints, because they decide which DONE Draw the integration map next showing every system DONE Choose the pattern write down why you chose it. ACTIVE Contract Define the contract for each interface QUEUED Contract leaves the error codes undefined will cause QUEUED Certification plan Add a certification plan with at least ten QUEUED Choose the pattern for each connection and write down why you chose it.
Contract for each interface PAYMENT OPERATIONS IN PROGRESS LIVE 01 Start with the scenario - constraints, because they decide which DONE 02 Draw the integration map next - showing every system DONE 03 Choose the pattern - write down why you chose it. DONE 04 Contract - Define the contract for each interface ACTIVE 05 Contract - leaves the error codes undefined will cause QUEUED 06 Certification plan - Add a certification plan with at least ten QUEUED Define the contract for each interface, with enough detail for a developer to build it without guessing. Step 4 of 6 Contract for each interface IN PROGRESS Start with the scenario constraints, because they decide which DONE Draw the integration map next showing every system DONE Choose the pattern write down why you chose it. DONE Contract Define the contract for each interface ACTIVE Contract leaves the error codes undefined will cause QUEUED Certification plan Add a certification plan with at least ten QUEUED Define the contract for each interface, with enough detail for a developer to build it without guessing.
Contract: too late to fix PAYMENT OPERATIONS IN PROGRESS LIVE 01 Start with the scenario - constraints, because they decide which DONE 02 Draw the integration map next - showing every system DONE 03 Choose the pattern - write down why you chose it. DONE 04 Contract - Define the contract for each interface DONE 05 Contract - leaves the error codes undefined will cause ACTIVE 06 Certification plan - Add a certification plan with at least ten QUEUED A contract that leaves the error codes undefined will cause arguments during testing, when it is too late to fix them cheaply. Step 5 of 6 Contract: too late to fix IN PROGRESS Start with the scenario constraints, because they decide which DONE Draw the integration map next showing every system DONE Choose the pattern write down why you chose it. DONE Contract Define the contract for each interface DONE Contract leaves the error codes undefined will cause ACTIVE Certification plan Add a certification plan with at least ten QUEUED A contract that leaves the error codes undefined will cause arguments during testing, when it is too late to fix them cheaply.
Certification plan PAYMENT OPERATIONS COMPLETE LIVE 01 Start with the scenario - constraints, because they decide which DONE 02 Draw the integration map next - showing every system DONE 03 Choose the pattern - write down why you chose it. DONE 04 Contract - Define the contract for each interface DONE 05 Contract - leaves the error codes undefined will cause DONE 06 Certification plan - Add a certification plan with at least ten ACTIVE Add a certification plan with at least ten test cases, a limited go-live with ten payments of EUR 50, and a rollback trigger. Step 6 of 6 Certification plan COMPLETE Start with the scenario constraints, because they decide which DONE Draw the integration map next showing every system DONE Choose the pattern write down why you chose it. DONE Contract Define the contract for each interface DONE Contract leaves the error codes undefined will cause DONE Certification plan Add a certification plan with at least ten ACTIVE Add a certification plan with at least ten test cases, a limited go-live with ten payments of EUR 50, and a rollback trigger.

Key points of this lesson, in order.

0:00 / 3:35 Step 1 of 6

Exercise: Design the Integration for a New Payment Rail (choose patterns, draw the integration map, define contracts and failure handling)

Banking Integration Patterns, Lesson 7 of 9, Narration 3:35, D10 APIs and integration

Suspense accountReconciliationPayment hub

What you will learn

Your objective. By the end of this lesson, you will be able to explain exercise: design the integration for a new payment rail (choose patterns, draw the integration map, define contracts and failure handling). Start with the scenario and the constraints, because they decide which patterns are possible.

Why it matters. This matters because APIs and integrations are how systems talk to each other. A badly specified API is a failed payment, a duplicate, or a security hole.

Chapter objective: Learner explains banking integration patterns, including file transfer, messaging, APIs, and event streaming, and selects the right pattern for a given payment integration need. Learner demonstrates this skill using realistic banking examples, explaining each step clearly and using correct terminology throughout.

Key learning points

  • Start with the scenario
  • Draw the integration map next
  • Choose the pattern for each connection
  • Contract for each interface
  • Contract: too late to fix
  • Certification plan

Key terms

Suspense account: A temporary account used to hold funds or entries that cannot yet be posted to their final account. Banks use suspense accounts for unidentified receipts, pending investigations and items awaiting...

Reconciliation: The process of comparing records from two sources, such as a bank statement and an internal ledger, to confirm they agree.

Payment hub: A central system in a bank that receives payment instructions from all channels, validates them, applies screening and routing rules, and sends them to the correct clearing system or correspondent.

Banking architecture diagram showing Exercise: Design the Integration for a New Payment Rail (choose patterns, draw the integration map, define contracts and failure handling).

Insights and practice scenarios

Worked insights and practice scenarios for this lesson. Each one is a reusable PaymentForge case, so the same case may appear in more than one lesson.

Practise this lesson

Exercise

Write the request and the expected response for the API call described in this lesson.

Use the API resources, operations and fields named in this lesson.

  1. What to do. Write the JSON request with the required fields, the success response, and one error response with its error code.

Correct result. A correct request has all mandatory fields, a valid idempotency key, and the right resource and operation. The success response confirms acceptance, and the error response names the field or rule that failed.

Why. An API contract is a promise between two systems. If the request is wrong, the API must reject it cleanly, not fail silently.

Check your understanding

Practice question

Which of the following best describes exercise: design the integration for a new payment rail (choose patterns, draw the integration map, define contracts and failure handling)?

Takeaway and next step

What to remember

A good map fits on one page, and a colleague who has never seen the project should be able to trace a EUR 500 payment from start to finish without asking a question.

Call the API described in this lesson with a valid request, then with a missing field, and compare the responses.

Open the API Playground →

Builds on "Partner Onboarding, Certification and Change Management".

Transcript and full text

Show transcript

Start with the scenario and the constraints, because they decide which patterns are possible. Your bank, a mid-sized bank in Spain, is joining a new instant payment rail that settles in euros within ten seconds, twenty-four hours a day. The bank expects 200,000 payments a day, with an average value of EUR 180, and a peak of 40 payments per second at lunchtime. The core banking system is fifteen years old and exposes a synchronous service for balance checks, but only a nightly file interface for bulk posting. The sanctions provider offers a real-time API, and the scheme requires ISO 20022 messages. List every system you must connect, and note the constraint on each one before you draw anything. Draw the integration map next, showing every system, every connection, and the direction of each flow. Place the channels on the left, the payment hub in the centre, the core banking system, the sanctions service, the fraud service, the ledger, and the scheme on the right. Draw the customer payment as a line from the mobile app through the hub to the scheme, and draw the settlement as a line from the scheme back to the ledger. Label each line with its transport, such as API, queue, or file, and with its format, such as JSON or pacs.008. A good map fits on one page, and a colleague who has never seen the project should be able to trace a EUR 500 payment from start to finish without asking a question. Choose the pattern for each connection and write down why you chose it. Use a synchronous API between the channel and the hub, because the customer waits for an answer. Use a synchronous call from the hub to the sanctions API, because screening must complete before the payment proceeds. Use asynchronous messaging between the hub and the core banking system for the debit, with a response queue that returns the result, because the core system cannot always answer in under a second. Use a file interface for the end-of-day ledger summary, because finance needs a complete and auditable record. Use event streaming for status updates, so the mobile app, the notification service, and the warehouse all learn about a settled payment at the same time. Define the contract for each interface, with enough detail for a developer to build it without guessing. For the hub to scheme interface, specify the pacs.008 message, the required fields, the character set, the timeout of five seconds, and the error codes for an invalid account, an amount above the limit, and a duplicate instruction. For the sanctions API, specify the request fields, the response time of under 200 milliseconds, and the behaviour when the service is unavailable. For the core banking queue, specify the message format, the retry policy, and the dead letter queue that holds messages that fail three times. A contract that leaves the error codes undefined will cause arguments during testing, when it is too late to fix them cheaply. Finish with failure handling, certification, and the go-live plan, and test your design against a real failure. Describe what happens if the sanctions service is down for thirty minutes, if the scheme rejects a payment after the core debit has succeeded, and if the ledger file arrives with a total that does not match the hub total. Define the reconciliation job that compares the hub, the core system, and the scheme every fifteen minutes, and the suspense account that holds unmatched items. Add a certification plan with at least ten test cases, a limited go-live with ten payments of EUR 50, and a rollback trigger. Present your map, your contracts, and your failure table, and ask a colleague to find the connection you missed.

Start with the scenario and the constraints, because they decide which patterns are possible. Your bank, a mid-sized bank in Spain, is joining a new instant payment rail that settles in euros within ten seconds, twenty-four hours a day. The bank expects 200,000 payments a day, with an average value of EUR 180, and a peak of 40 payments per second at lunchtime. The core banking system is fifteen years old and exposes a synchronous service for balance checks, but only a nightly file interface for bulk posting. The sanctions provider offers a real-time API, and the scheme requires ISO 20022 messages. List every system you must connect, and note the constraint on each one before you draw anything.

Draw the integration map next, showing every system, every connection, and the direction of each flow. Place the channels on the left, the payment hub in the centre, the core banking system, the sanctions service, the fraud service, the ledger, and the scheme on the right. Draw the customer payment as a line from the mobile app through the hub to the scheme, and draw the settlement as a line from the scheme back to the ledger. Label each line with its transport, such as API, queue, or file, and with its format, such as JSON or pacs.008. A good map fits on one page, and a colleague who has never seen the project should be able to trace a EUR 500 payment from start to finish without asking a question.

Choose the pattern for each connection and write down why you chose it. Use a synchronous API between the channel and the hub, because the customer waits for an answer. Use a synchronous call from the hub to the sanctions API, because screening must complete before the payment proceeds. Use asynchronous messaging between the hub and the core banking system for the debit, with a response queue that returns the result, because the core system cannot always answer in under a second. Use a file interface for the end-of-day ledger summary, because finance needs a complete and auditable record. Use event streaming for status updates, so the mobile app, the notification service, and the warehouse all learn about a settled payment at the same time.

Define the contract for each interface, with enough detail for a developer to build it without guessing. For the hub to scheme interface, specify the pacs.008 message, the required fields, the character set, the timeout of five seconds, and the error codes for an invalid account, an amount above the limit, and a duplicate instruction. For the sanctions API, specify the request fields, the response time of under 200 milliseconds, and the behaviour when the service is unavailable. For the core banking queue, specify the message format, the retry policy, and the dead letter queue that holds messages that fail three times. A contract that leaves the error codes undefined will cause arguments during testing, when it is too late to fix them cheaply.

Finish with failure handling, certification, and the go-live plan, and test your design against a real failure. Describe what happens if the sanctions service is down for thirty minutes, if the scheme rejects a payment after the core debit has succeeded, and if the ledger file arrives with a total that does not match the hub total. Define the reconciliation job that compares the hub, the core system, and the scheme every fifteen minutes, and the suspense account that holds unmatched items. Add a certification plan with at least ten test cases, a limited go-live with ten payments of EUR 50, and a rollback trigger. Present your map, your contracts, and your failure table, and ask a colleague to find the connection you missed.

Full lesson text (all scenes)

Completing a lesson updates your progress dashboard on the homepage.

Scene timestamps are estimated by allocating the narration text proportionally across the real audio length. The audio playback position is the source of truth: pause freezes the visual, seeking restores the correct scene, replay restarts the scene animation.