> ## Documentation Index
> Fetch the complete documentation index at: https://docs.treasuryprime.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
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](/reference/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](/reference/card-event) endpoint.
## Create a Card Simulation
Initiate a card simulation
```bash bash theme={null}
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](/reference/get_transaction) endpoint as the `trace_id` for the `hold` transaction related to the auth request or as the trace\_id on the [card event](/reference/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
```bash bash theme={null}
$ 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
```bash bash theme={null}
{
"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](/reference/card-controls) that have been setup.
```bash bash theme={null}
$ 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](/reference/card-event) generated upon receipt of the auth request or the [transaction](/reference/get_transaction) endpoint.
Here it is located via the account transaction endpoint via this request.
```bash bash theme={null}
$ 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.
```bash bash theme={null}
{
"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.
```bash bash theme={null}
$ 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"
}
}
}
}'
```