API Simulator

clock 6-minute read calender Rel. 4.0.0 | updated Nov. 12, 2024

Test and move your code in a mock environment

This guide explains how to use the Embedded Banking (EB) API simulator. Whether you are testing your application or practicing your API call, with the simulator you can interact with a mock environment without affecting any live systems.

API simulator high-level flow diagram

You can test APIs right in a production-like environment to get a real sense of how these endpoints operate. It is not a 100% reflection of the production environment, but a close mimic for API data controls and transmission activity. The API simulator is data-driven by the information you provide. You pass values in the request and verify the response returns the same information in data points like account number or name.

Since it is data-driven, this means that the more data you enter, the more scenarios you can test and interpret. The response data is smart and matches the critical data points from the different endpoint requests. You can simulate a series of related API calls that use the data from the previous requests.

Features

  • Simulate API calls
    Make API requests without hitting real servers. This is useful for testing.
  • Test different scenarios
    Simulate different responses, like successful calls, errors, and timeouts.
  • Log and analyze responses
    View the data sent and received during API interactions.
  • Customize requests
    Change parameters, headers, and body content of requests to simulate different conditions.

01

Download the simulator API specifications

Before you begin, you will need the latest version of the simulator API specifications. The YAML file tells you what the API does, how to make request, what information you need to send, and what you'll get back.

Download the simulator YAML file for one of these products:

02

Select an endpoint

We embedded the word “simulator” is embedded into each API simulator endpoint. Make sure that when you download the YAML file, you include the word 'simulator' in its correct location on the path. Or simply copy an endpoint from the table below.

Simulator endpoints

APIDescriptionMethodSimulator endpoint
Account ValidationVerify an accountpost/accounts/validations/v2/simulator/verifyAccount
ACH OriginationCheck the status of addenda recordspost/ach/payments/v1/simulator/status/addenda
Send or collect a paymentpost/ach/payments/v1/simulator/ccd
Make or collect payments to or from a corporate account with attached recordspost/ach/payments/v1/simulator/ctx
Make deposits and withdrawals to or from consumer accountspost/ach/payments/v1/simulator/ppd
Send a payment over the phonepost/ach/payments/v1/simulator/tel
Send an online paymentpost/ach/payments/v1/simulator/web
Undo a payment requestpost/ach/payments/v1/simulator/undo
Send additional addenda informationpost/ach/payments/v1/simulator/addenda
ACH InquirySearch for ACH transactionsGET/accounts/transactions/v1/simulator/ach/detail/{parNumber}
Search for ACH transaction detailspost/accounts/transactions/v1/simulator/ach/list
RTP InquirySearch real-time payment transactionspost/rtp/v1/transactions/simulator/list
View the details of a RTP transaction by its IDGET/rtp/v1/transactions/simulator/detail/{transactionId}

03

Customize your request

In each request, you can change details in the header and body. We recommend beginning with a simple copy and paste of the request body code from the YAML to get familiar with the API. Then, get creative and try some scenarios that are common for you and your clients.

04

Send request and view response

Once you hit send, the simulator returns a response. The response will have the standard HTTP response codes like 200 (success) or 404 (not found). Review the status codes and response body returned. If you get an error response, check for things like typos in the endpoint, missing headers, or incorrect data in the body. Check your logs to see a record of all system interactions.

Best practices

  • Understand the basics of APIs. While the simulator helps, the basic API knowledge is important. Know the different between GET and POST and how headers and body content work. 
  • Use the logs for debugging. Always check the logs to see if your request was formatted correctly. If the response isn’t what you expect, the logs can help pinpoint errors. 
  • Test different scenarios. Use the simulator to test both success and failures cases, includes edge cases (like testing with missing or incorrect data).
  • Stay organized. Label and document your simulated API tests to keep track of different test cases.

Requirements

  • You need to be a verified API consumer with the correct credentials, following KeyBank's onboarding requirements as described in our Getting Started Guide. If you are an existing API consumer of an endpoint that is also active in the simulator environment, you should have access to the API simulator. If not, reach out to your Payments Advisor/Technical Account Manager.
  • At KeyBank, we require a separate set of API keys for API simulator and production environments. You cannot use API keys for one environment to access the API in another environment. You need unique application credentials for the simulator environment.
  • There is a unique consumer key for the API simulator to avoid cross-pollinating the environments. You get a unique consumer_id and consumer_secret for the API simulator. You can use the same client credentials (client_id and client_key). All keys are securely provided to you by KeyBank.
  • When you submit a request for an access token, you should see API Simulator listed in the api_product_list_json. This field lists what API products and service you have permission to access.

Restrictions

  • You cannot access the API simulator unless you are a verified API consumer partnering with KeyBank. To learn more, go to the Getting Started Guide. 
  • ACH data transmission goes to a simulated ACH batch that runs at 6:00 p.m. daily. After the daily batch run, you can inquire about the status of an ACH transaction. 
  • Not all endpoints are currently available in the API simulator for each API product. KeyBank is working to expand simulated experiences for all of our API products.