Card Simulations

There are currently seven simulation types for cards as described below.

Simulation type	Card event message type	Explanation
card_event.auth_capture	auth-capture	Notification that a previous authorization has been captured (related holds are released and funds moved as a result of this request).
card_event.auth_clear_request	auth-clear-request	Request to authorize and capture funds in one message (funds are moved immediately).
card_event.auth_request	auth-request	Request 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_reversal	auth-reversal	Notification that a previous authorization has been reversed.
card_event.force_capture	force-capture	Notification that funds have been captured.
card_event.original_credit_auth_clear_request	original-credit-auth-clear-request	Request to credit funds for OCT.
card_event.refund	refund	Refunds a previously completed transaction.
card_event.refund_auth	refund-auth-request	Request 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

Parameter	Type	Required?	Description
card_id	string	Required	ID of the card to use as the source for simulated transactions.
amount	string	Required	Amount of money related to the event, with two decimal precision. For example, "10.00" would indicate $10.00.
merchant	object	Required	Object representing the merchant where the card event occurred.

Auth Clear Request

Parameter	Type	Required?	Description
card_id	string	Required	ID of the card to use as the source for simulated transactions.
amount	string	Required	Amount of money related to the event, with two decimal precision. For example, "10.00" would indicate $10.00.
atm	object	Optional	Object representing ATM data for the card event.
merchant	object	Required	Object representing the merchant where the card event occurred.

Auth Capture, Auth Reversal, and Refund

Parameter	Type	Required?	Description
card_id	string	Required	ID of the card to use as the source for simulated transactions.
amount	string	Required	Amount 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.
merchant	object	Required	Object representing the merchant where the card event occurred.
external_id	string	Required	The 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

Parameter	Type	Description
network	string	Network ATM transaction took place on.
network_fee	string	ATM 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

Parameter	Type	Description
name	string	Name of the merchant.
mid	string	Merchant ID.
mcc	string	Merchant category code.
address	object	Object containing `city`, `state`, `postal_code`, and `country` as strings.

Address Sub-Object

Parameter	Type	Description
city	string	Merchant city.
state	string	Two-character state abbreviation.
postal_code	string	Five-digit postal code.
country	string	Three-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"
              }
            }
          }
        }'