There are currently seven simulation types for cards as described below.
Simulation typeCard event message typeExplanation
card_event.auth_captureauth-captureNotification that a previous authorization has been captured (related holds are released and funds moved as a result of this request).
card_event.auth_clear_requestauth-clear-requestRequest to authorize and capture funds in one message (funds are moved immediately).
card_event.auth_requestauth-requestRequest to authorize spending with card (if approved, this places a hold on funds). Note that this simulation will have any applicable card controls run against the auth request.
card_event.auth_reversalauth-reversalNotification that a previous authorization has been reversed.
card_event.force_captureforce-captureNotification that funds have been captured.
card_event.original_credit_auth_clear_requestoriginal-credit-auth-clear-requestRequest to credit funds for OCT.
card_event.refundrefundRefunds a previously completed transaction.
card_event.refund_authrefund-auth-requestRequest to authorize a refund to a card. Note that this simulation will not create a transaction object.
Each of these simulations ties to a message type from the card events endpoint.

​
Create a Card Simulation

Initiate a card simulation 
POST https://api.sandbox.treasuryprime.com/simulation

​
Card Simulation Request Body

​
Auth Request, Force Capture, Original Credit Auth and Clear, and Refund Auth

ParameterTypeRequired?Description
card_idstringRequiredID of the card to use as the source for simulated transactions.
amountstringRequiredAmount of money related to the event, with two decimal precision. For example, “10.00” would indicate $10.00.
merchantobjectRequiredObject representing the merchant where the card event occurred.

​
Auth Clear Request

ParameterTypeRequired?Description
card_idstringRequiredID of the card to use as the source for simulated transactions.
amountstringRequiredAmount of money related to the event, with two decimal precision. For example, “10.00” would indicate $10.00.
atmobjectOptionalObject representing ATM data for the card event.
merchantobjectRequiredObject representing the merchant where the card event occurred.

​
Auth Capture, Auth Reversal, and Refund

ParameterTypeRequired?Description
card_idstringRequiredID of the card to use as the source for simulated transactions.
amountstringRequiredAmount of money related to the event, with two decimal precision. For example, “10.00” would indicate $10.00. For ATM transaction simulations, the ATM fee will be added to this number.
merchantobjectRequiredObject representing the merchant where the card event occurred.
external_idstringRequiredThe trace_id for the auth request simulation you want to clear, reverse, or refund. {% br /%}This can also be found under the transaction endpoint as the trace_id for the hold transaction related to the auth request or as the trace_id on the card event for the auth request.

​
ATM Sub-Object

ParameterTypeDescription
networkstringNetwork ATM transaction took place on.
network_feestringATM fee related to the event, with two decimal precision. For example, “2.00” would indicate $2.00. This fee will be added to the amount indicated for a simulation.
Note that the merchant and address sub-objects are the same across all card simulations.

​
Merchant Sub-Object

ParameterTypeDescription
namestringName of the merchant.
midstringMerchant ID.
mccstringMerchant category code.
addressobjectObject containing city, state, postal_code, and country as strings.

​
Address Sub-Object

ParameterTypeDescription
citystringMerchant city.
statestringTwo-character state abbreviation.
postal_codestringFive-digit postal code.
countrystringThree-character country abbreviation.

​
Example Request

$ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/simulation \
    -H 'Content-Type: application/json' \
    -d '{
          "type": "card_event.auth_request",
          "simulation": {
            "card_id": "card_104",
            "amount": "25.10",
            "merchant": {
              "mcc": "5411",
              "mid": "4445025949032",
              "name": "KROGER #10626",
              "address": {
                "city": "LAS VEGAS",
                "state": "NV",
                "country": "USA",
                "postal_code": "88901"
              }
            }
          }
        }'

​
Example Response

​
Success

There will be no response body. The response code will be a 202 - accepted

​
Error

{
 "error": "Simulation not implemented for issuer: marqeta, event: card_event.not_implemented_event"
}

​
Example Usage

A common flow for a card simulation is creating a mock swipe for an issued card at a specific merchant. The following calls outline simulating a purchase at a grocery store. Create an auth request simulating the initial swipe of the card at the point of sale system. This auth request will be routed through the mocked card network and verified against any card controls that have been setup. 
$ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/simulation \
    -H 'Content-Type: application/json' \
    -d '{
          "type": "card_event.auth_request",
          "simulation": {
            "card_id": "card_104",
            "amount": "25.10",
            "merchant": {
              "mcc": "5411",
              "mid": "4445025949032",
              "name": "KROGER #10626",
              "address": {
                "city": "LAS VEGAS",
                "state": "NV",
                "country": "USA",
                "postal_code": "88901"
              }
            }
          }
        }'
A hold will have been created for the amount of the requested purchase. To capture and approve this auth request the trace_id for the auth_request is required. This can be retrieved from either the card_event generated upon receipt of the auth request or the transaction endpoint. Here it is located via the account transaction endpoint via this request. 
$ curl https://api.sandbox.treasuryprime.com/account/acct_1029384756/transaction \
    -u "$API_KEY_ID:$API_SECRET_KEY"
Here’s the response we would expect where the hold generated in response to the auth request is the most recent transaction. 
{
  "data": [
    {
      "check_id": null,
      "billpay_payment_id": null,
      "ach_id": null,
      "amount": "25.10",
      "balance": "256147.27",
      "book_id": null,
      "check_id": null,
      "check_number": null,
      "date": "2021-10-26",
      "extended_timestamp": "2021-10-26T12:02:03Z",
      "extended_timestamp_precise": "2021-10-26T12:02:03.329Z",
      "desc": "KROGER #10626 4445025949032 - AUTHORIZATION REQUEST",
      "fingerprint": "ttx_11gqg7am69g1s9",
      "id": "ttx_11gqg7am69g1s9",
      "summary": null,
      "type": "hold",
      "trace_id": "23f2b0e82c684638a5993f53e920cdab",
      "wire": null,
      "wire_id": null,
      "related_transfer_ids": []
    },
    ...
  ]
}
Now that the trace_id has been found, an auth capture request can be created simulating the verification of the auth request. The trace_id is supplied as the external_id for our simulation call. The auth capture will release the hold and debit the funds from the account. 
$ curl -u $API_KEY_ID:$API_SECRET_KEY https://api.sandbox.treasuryprime.com/simulation \
    -H 'Content-Type: application/json' \
    -d '{
          "type": "card_event.auth_capture",
          "simulation": {
            "external_id": "23f2b0e82c684638a5993f53e920cdab",
            "card_id": "card_104",
            "amount": "25.10",
            "merchant": {
              "mcc": "5411",
              "mid": "4445025949032",
              "name": "KROGER #10626",
              "address": {
                "city": "LAS VEGAS",
                "state": "NV",
                "country": "USA",
                "postal_code": "88901"
              }
            }
          }
        }'