Payments Training Hub

LAB-04: Specify a Payment Initiation API for a Corporate Channel

API analysis

A corporate banking channel needs an API that lets treasury systems initiate payments directly, without a person typing each instruction into a screen. The API must be easy to integrate, safe against duplicate payments, and clear about what went wrong when a request fails. In this lab you analyse and specify a payment initiation API from the business need down to the contract. You will define the endpoints, the HTTP methods, the request and response schemas, the authentication model, the error codes, and the rules for idempotency, correlation IDs, timeouts and retries. You will also write the OpenAPI contract that the corporate integration team builds against. By the end of the lab you will have an API specification that is complete enough to hand to a developer and a corporate customer without a follow-up meeting.

0 of 5 steps done. Tick each step as you finish it, your progress is saved in this browser.

  1. Interview the corporate channel team and two corporate customers to learn what they need: single payments, bulk payments, payment status, and cancellation. Define the business rules, such as the daily limit of 250,000 dollars per customer, the cutoff times per currency, and the approval workflow for payments above 100,000 dollars. Agree the success criteria, including the target adoption in the first year and the maximum time from request to acceptance. Write the scope so that account information and reporting are clearly out of scope for this first release.

  2. Design the endpoints: a POST to create a payment initiation, a GET to retrieve a payment by its identifier, a GET to list payments with filters, and a POST to cancel a payment that has not yet executed. Choose the HTTP methods and the resource names carefully, keeping them consistent and readable. State the query parameters, the path parameters and the pagination rules for the list endpoint. Review the endpoint design with a developer and a corporate integrator to confirm it matches how treasury systems actually call APIs.

  3. Write the request and response schemas for each endpoint, naming every field, its data type, its length, whether it is mandatory, and its validation rule. Include the debtor account, the creditor name and account, the amount and currency, the execution date and the remittance information. Define the response for success, for validation failure and for a payment that is accepted but not yet executed. Use realistic examples in every schema, with fictional accounts and amounts, so that integrators can copy them into their test code.

  4. Choose the authentication and authorisation model, for example OAuth 2.0 with client credentials for system to system access and scoped permissions per corporate customer. Define the error codes, separating technical errors, such as 400 for a malformed request and 401 for a bad token, from business errors, such as insufficient funds and limit exceeded. State the error response body, with a machine readable code, a human readable message and a correlation ID. Agree the rate limits and the behaviour when a limit is exceeded.

  5. Write the rules that make the API safe: an idempotency key on every POST, so that a retried request never creates a duplicate payment, and a correlation ID that travels through every system so that a failed payment can be traced end to end. Define the timeout for each endpoint, the retry policy for the caller, and the behaviour when the bank system is temporarily unavailable, including a 503 response and a status poll. Record these rules in the specification and test them in the sandbox before sign off.

Templates.

Worked example. Cedarwood Bank, a fictional bank in Toronto, is opening a payment initiation API for its corporate channel so that treasury teams can pay suppliers without logging into internet banking. The API offers a POST endpoint that accepts a single payment initiation with debtor account, creditor name and IBAN, amount and currency, and an optional execution date. A corporate treasury system at a fictional manufacturer, Maple Foods, submits a payment of 120,000 Canadian dollars to a supplier in Chicago. The request carries an idempotency key and a correlation ID, and the bank returns a 202 response with a payment identifier and a status of accepted. When the same request is sent again with the same idempotency key, the bank returns the original response instead of creating a second payment, so the supplier is not paid twice. A second request with an amount above the daily limit of 250,000 dollars is rejected with a 422 error and a clear business error code. The API specification, written in OpenAPI, is reviewed by the corporate integration team, tested in a sandbox with 50 sample payments, and signed off before the first production call.

Deliverables.