In this guide, we’ll build a working mock of the Mastercard Send API. This can give you some ideas for how you can simulate financial APIs with WireMock,  and the advantages of using stateful mocking to increase the realism of your simulations.

Note: the mock endpoint is publicly available at https://wm-mastercard-send-payment.wiremockapi.cloud. It’s free to use (no WireMock account required), but you can of course use WireMock Cloud if you want to follow the steps yourself and customize it further.

Why mock the Mastercard API?

Mastercard’s APIs are amongst the most widely used financial APIs in the world. If you’re developing a product that moves money, you could use a simulated version of these APIs to simplify testing and development.  

For example, you might want to simulate specific payment scenarios and see how they interact with other parts of your application, in ways which the provided sandbox does not enable you to do. Or you might want to validate your integration code, test error scenarios, and run end-to-end tests without the overhead and risk of connecting to the production API.

Step 1: Discovery

First we need to  figure out how to discover this API’s structure, ideally from a source we consider reliable.

Mastercard has a richly-featured developer portal at https://developer.mastercard.com/ where each of its 80-something APIs are documented and sandbox keys can be acquired. Luckily for us this documentation includes OpenAPI descriptions, so we downloaded the one for the Send Person-to-Person API.

Getting real request data

At this point we could have just imported the OpenAPI into WireMock Cloud, which would have generated a mock API conforming to this. However, OpenAPI docs aren’t always completely accurate or up to date - we’ll probably get a more accurate result if we use the OpenAPI document as a guide when making some requests to the sandbox.

(Note that we would normally be using WireMock’s recording features for this purpose. However, due to the unfortunate fact that this API is using OAuth 1.0a for authentication (rather than the normally-ubiquitous OAuth 2), and some other hurdles around the way it uses request signing, we ended up using Postman instead.)

You can find the Postman collection we created during this process here. We used this to create a series of test requests, saving the responses as examples.

Step 2: Creating the static mock

After attaching response examples to each of our requests we imported the Postman collection into WireMock Cloud, generating a basic but usable mock of the API.

We import this definition into WireMock Cloud:

‍Okay, now we've got a mock going! At this point we can successfully:

• make a POST request to the mock ‘create payment transfer’ endpoint

• make GET requests to retrieve a single transfer by ID and query transfers by a surrogate ID.

In both cases the mock responses will bestatic and taken directly from the response examples we captured while testing the API.

Step 3: Going stateful

For many use cases it might be perfectly acceptable to stop at this point, but we wanted to make this mock more realistic and simulate the stateful behaviour of the API. A stateful mock better simulates the real-world behavior of a payment API, where a request to create a transfer results in the creation of a stored transfer record that can be retrieved or further manipulated later. This is essential if we want to test multi-step workflows that operate on the transfer data after the initial creation step.

Setting up stateful mocking in WireMock Cloud will take a few additional steps in this case, although you could typically use the automated wizard to expedite this process significantly:

Firstly, we needed to edit the POST stub to make it do two things:

1. Capture the payment request data sent by the client
2. Enrich this with generated fields (following the behaviour of the real API)
3. Store the resulting data for later retrieval

This is achieved by creating an ID for the transfer - in this case a 32 character random string:

Then we create a state variable storing the request data plus the additional synthetic fields:

Note how this is achieved by merging the request JSON with a JSON document containing the synthesized data via the {{jsonMerge … }} helper.

Step 4: Validation against the original spec

Although we created the mock from captured traffic from the sandbox to ensure its accuracy, it’s still useful to be able to confirm that the mock API behavior complies with the OpenAPI description downloaded from Mastercard’s portal, especially since we may have inadvertently deviated from this when adding statefulness.

To achieve this we imported the OpenAPI spec into the mock and enabled soft validation (which means report violations but don’t return errors).

This showed no validation errors in the request log during testing, so our mock and the OpenAPI were in agreement:

The validator also checks that incoming requests are correct, which is very useful when creating and debugging client code. The request log is annotated with a warning triangle icon when either the request or response does not conform to the spec:

‍

And when clicked on, the request detail page shows which part of the OpenAPI spec was violated:

‍

Step 5: Testing the stateful mock

Having added the stateful behaviour to the mock API we were able to interact with it as we would the real API.

First making a POST request to create a new transfer:

Then after making a note of the transfer ID, making a GET request to retrieve it and receiving the same data we posted in the previous step:

Closing

You’ve now seen how a real-world API can be analysed and mocked, and how that mock can be enhanced to reproduce realistic stateful behaviour in a few steps.

We’ve also seen how it’s possible to capture and utilize real API traffic despite the presence of a tricky authentication scheme via the Postman import feature.

If you want to try it yourself the finished product is hosted here: https://wm-mastercard-send-payment.wiremockapi.cloud

You can find the Postman collection we created during this process here: https://www.postman.com/wiremock-cloud/workspace/wiremock-demos/collection/3504886-c123e79b-614f-4b1b-ad3a-7d65afa3ffdb?action=share&creator=3504886&active-environment=3504886-a88b6fa7-322e-4247-9d3f-1ec82ac5b6ad

‍