Simulation Use Cases

International card transactions and currency conversion

With Simulations 2.0, you can simulate international card transactions based on currency and location.

Authorization events with currency conversion

You can add currency conversion when simulating an authorization-type transaction by including the currency_conversion object and related details in a POST request to the /simulations/cardtransactions/authorization endpoint. For information about the /simulations/cardtransactions/authorization endpoint, see Simulate authorization.

Note In the request, currency_conversion.original_currency_code accepts an alpha-3 code, such as GBP. In the response, it is returned as a numeric ISO 4217 currency code, such as 826, in the same format as in production webhooks and Transactions API responses. The top-level currency_code is always alpha-3, such as USD.

The following example shows an authorization-type transaction, with currency conversion, for a United States card transacting in the United Kingdom.

Sample request body

JSON

{
  "card_token": "**CARD_TOKEN**",
  "amount": 37.50,
  "card_acceptor": {
    "mid": "11111"
  },
  "network": "VISA",
  "currency_conversion": {
    "original_amount": 30.00,
    "conversion_rate": 1.25,
    "original_currency_code": "GBP"
  }
}

For the response fields, see Card Transaction Simulation Response Object.

Sample response body

JSON

{
  "transaction": {
    "type": "authorization",
    "state": "PENDING",
    "token": "**CURRENCY_AUTHORIZATION_TRANSACTION_TOKEN**",
    "user_token": "**USER_TOKEN**",
    "card_token": "**CARD_TOKEN**",
    "response": {
      "code": 0,
      "memo": "Approved or completed successfully"
    },
    "created_time": "2022-12-06T21:39:43.000Z",
    "user_transaction_time": "2022-12-06T21:39:43.000Z",
    "settlement_date": "2022-12-06T00:00:00.000Z",
    "amount": 37.50,
    "gpa": {
      "ledger_balance": 250.00,
      "available_balance": 212.25,
      "impacted_amount": -37.50
    },
    "currency_code": "USD",
    "currency_conversion": {
      "original_amount": 30.00,
      "conversion_rate": 1.25,
      "original_currency_code": "826"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "card_acceptor": {
      "mid": "000000000011111",
      "mcc": "6411",
      "name": "Marqeta Storefront",
      "city": "St. Petersburg",
      "state": "FL"
    }
  }
}

Clearing events with currency conversion

You can add currency conversion when simulating an authorization.clearing-type transaction by including the currency_conversion object and related details in a POST request to the /simulations/cardtransactions/authorization.clearing endpoint. For more information about the /simulations/cardtransactions/authorization.clearing endpoint, see Simulate authorization clearing.

The following example shows an authorization.clearing-type transaction, with currency conversion, for a United States card in the United Kingdom.

Sample request body

JSON

{
  "preceding_related_transaction_token": "**AUTHORIZATION_TRANSACTION_TOKEN**",
  "amount": 37.50,
  "currency_conversion": {
    "original_amount": 30.00,
    "conversion_rate": 1.25,
    "original_currency_code": "GBP"
  }
}

For the response fields, see Card Transaction Simulation Response Object.

Sample response body

JSON

{
  "transaction": {
    "type": "authorization.clearing",
    "state": "COMPLETION",
    "token": "**AUTHORIZATION_CLEARING_TRANSACTION_TOKEN**",
    "user_token": "**USER_TOKEN**",
    "card_token": "**CARD_TOKEN**",
    "response": {
      "code": 0,
      "memo": "Approved or completed successfully"
    },
    "created_time": "2022-12-06T21:41:48Z",
    "user_transaction_time": "2022-12-06T21:39:43Z",
    "settlement_date": "2022-12-06T00:00:00Z",
    "amount": 37.50,
    "gpa": {
      "ledger_balance": 212.25,
      "available_balance": 212.25,
      "impacted_amount": -37.50
    },
    "currency_code": "USD",
    "currency_conversion": {
      "original_amount": 30.00,
      "conversion_rate": 1.25,
      "original_currency_code": "826"
    },
    "preceding_related_transaction_token": "**AUTHORIZATION_TRANSACTION_TOKEN**",
    "network": "VISA",
    "subnetwork": "VISANET",
    "card_acceptor": {
      "mid": "000000000011111",
      "mcc": "6411",
      "name": "Card Acceptor Name",
      "city": "Seattle",
      "state": "WA",
      "country_code": "USA"
    }
  }
}

Transactions with Account Name Inquiry

Account Name Inquiry (ANI) is an account verification feature that is supported by both the Mastercard and Visa card networks. You can simulate the ANI feature with Simulations 2.0. For more information about ANI, see About Account Name Inquiry. You can add account name verification when simulating an authorization transaction by including the account_name_verification object and related details in a POST request to the /simulations/cardtransactions/authorization endpoint. For information about the /simulations/cardtransactions/authorization endpoint, see Simulate authorization.

ANI for Visa

The following example shows an authorization transaction, with account name verification, for the Visa network.

Sample request body

JSON

{
    "card_token": "**CARD_TOKEN**",
    "amount": "0",
    "card_acceptor": {
        "mid": "11111"
    },
    "network": "VISA",
    "account_name_verification": {
        "request": {
            "first_name": "first",
            "middle_name": "middle",
            "last_name": "last"
        }
    }
}

For the response fields, see Card Transaction Simulation Response Object.

Sample response body

JSON

{
    "transaction": {
        "type": "authorization",
        "state": "CLEARED",
        "token": "53f14f73-f830-4086-9ec6-f84ca5a30da9",
        "user_token": "89d9f7fb-f373-49a1-b28c-85539b1d0ca3",
        "card_token": "5ab74159-6346-4100-9959-c691c14b2e02",
        "response": {
            "code": "1830",
            "memo": "Card account verification success"
        },
        "created_time": "2024-02-12T20:04:25Z",
        "user_transaction_time": "2024-02-12T20:04:25Z",
        "settlement_date": "2024-02-12T00:00:00Z",
        "amount": "0.00",
        "request_amount": "0.00",
        "gpa": {
            "ledger_balance": "100.00",
            "available_balance": "100.00"
        },
        "currency_code": "USD",
        "currency_conversion": {
            "original_amount": "0.00",
            "conversion_rate": 1.0,
            "original_currency_code": "840"
        },
        "network": "VISA",
        "subnetwork": "VISANET",
        "acquirer_fee_amount": "0",
        "fraud": {
            "network": {
                "transaction_risk_score": 29,
                "account_risk_score": "3"
            }
        },
        "card_acceptor": {
            "mid": "000000000011111",
            "poi": {
                "tid": "TR100000",
                "partial_approval_capable": "0",
                "cardholder_presence": "0",
                "card_presence": "0",
                "channel": "OTHER",
                "processing_type": "MAGSTRIPE",
                "pin_present": "false"
            }
        },
        "original_credit": {},
        "account_name_verification": {
            "on_file": {
                "first_name": "First",
                "last_name": "Last",
                "middle_name": "Middle"
            },
            "request": {
                "first_name": "first",
                "last_name": "last",
                "middle_name": "middle"
            },
            "response": {
                "code": "3333",
                "memo": "First name match; Middle name match; Last name match; Full name match"
            }
        }
    }
}

ANI for Mastercard

The following example shows an authorization transaction, with account name verification, for the Mastercard network.

Sample request body

JSON

{
    "card_token": "**CARD_TOKEN**",
    "amount": "0",
    "card_acceptor": {
        "mid": "11111"
    },
    "network": "MASTERCARD",
    "account_name_verification": {
        "request": {
            "first_name": "first",
            "middle_name": "middle",
            "last_name": "last"
        },
        "request_type": "SENDER"
    }
}

For the response fields, see Card Transaction Simulation Response Object.

Sample response body

JSON

{
    "transaction": {
        "type": "authorization",
        "state": "CLEARED",
        "token": "044b9543-b7a0-4195-abf8-357f3b67444e",
        "user_token": "89d9f7fb-f373-49a1-b28c-85539b1d0ca3",
        "card_token": "5ab74159-6346-4100-9959-c691c14b2e02",
        "response": {
            "code": "1830",
            "memo": "Card account verification success"
        },
        "created_time": "2024-02-12T20:06:48Z",
        "user_transaction_time": "2024-02-12T20:06:48Z",
        "settlement_date": "2024-02-12T00:00:00Z",
        "amount": "0.00",
        "request_amount": "0.00",
        "gpa": {
            "ledger_balance": "100.00",
            "available_balance": "100.00"
        },
        "currency_code": "USD",
        "currency_conversion": {
            "original_amount": "0.00",
            "conversion_rate": 1.0,
            "original_currency_code": "840"
        },
        "network": "MASTERCARD",
        "acquirer_fee_amount": "0",
        "fraud": {
            "network": {
                "transaction_risk_score": 1,
                "transaction_risk_score_reason_code": "14",
                "transaction_risk_score_reason_description": "Suspicious grocery store activity"
            }
        },
        "card_acceptor": {
            "mid": "000000000011111",
            "poi": {
                "tid": "TR100000",
                "partial_approval_capable": "0",
                "cardholder_presence": "0",
                "card_presence": "1",
                "channel": "OTHER",
                "processing_type": "MAGSTRIPE",
                "pin_present": "false"
            }
        },
        "original_credit": {},
        "account_name_verification": {
            "on_file": {
                "first_name": "First",
                "last_name": "Last",
                "middle_name": "Middle"
            },
            "request": {
                "first_name": "first",
                "last_name": "last",
                "middle_name": "middle"
            },
            "response": {
                "code": "0003",
                "memo": "Full name match"
            }
        }
    }
}

Transactions with Address Verification

The Address Verification System (AVS) compares purchaser-provided address data against cardholder address data held on file by the Marqeta platform and makes a match determination. You can simulate the AVS feature with Simulations 2.0. For more information about AVS, see About Address Verification. You can add address verification when simulating an authorization transaction by including the address_verification object and related details in a POST request to the /simulations/cardtransactions/authorization endpoint. For information about the /simulations/cardtransactions/authorization endpoint, see Simulate authorization.

AVS for Visa

The following example shows an authorization transaction, with address verification, for the Visa network.

Sample request body

JSON

{
    "card_token": "**CARD_TOKEN**",
    "amount": "0",
    "card_acceptor": {
        "mid": "11111"
    },
    "network": "VISA",
    "address_verification": {
        "street_address": "180 Grand Ave"
    }
}

For the response fields, see Card Transaction Simulation Response Object.

Sample response body

JSON

{
    "transaction": {
        "type": "authorization",
        "state": "CLEARED",
        "token": "3529ccc4-8866-4123-8236-54b2bd3d03dc",
        "user_token": "096a61a9-560e-464d-96f9-7ed4606259d4",
        "card_token": "bff15211-2aee-4228-95b4-e01038135f00",
        "response": {
            "code": "1830",
            "memo": "Card account verification success"
        },
        "created_time": "2025-12-05T22:42:31Z",
        "user_transaction_time": "2025-12-05T22:42:31Z",
        "settlement_date": "2025-12-05T00:00:00Z",
        "amount": "0.00",
        "request_amount": "0.00",
        "gpa": {
            "ledger_balance": "0.00",
            "available_balance": "0.00"
        },
        "currency_code": "USD",
        "currency_conversion": {
            "original_amount": "0.00",
            "conversion_rate": 1.0,
            "original_currency_code": "840"
        },
        "network": "VISA",
        "subnetwork": "VISANET",
        "acquirer_fee_amount": "0",
        "fraud": {
            "network": {
                "transaction_risk_score": 23,
                "account_risk_score": "3"
            }
        },
        "card_acceptor": {
            "mid": "000000000011111",
            "poi": {
                "tid": "TR100000",
                "partial_approval_capable": "0",
                "cardholder_presence": "0",
                "card_presence": "0",
                "channel": "OTHER",
                "processing_type": "MANUAL",
                "pin_present": "false"
            }
        },
        "original_credit": {},
        "address_verification": {
            "on_file": {
                "postal_code": "94612",
                "street_address": "180 Grand Ave"
            },
            "request": {
                "postal_code": "",
                "street_address": "180 Grand Ave"
            },
            "response": {
                "code": "0002",
                "memo": "Address match, zip code not present"
            }
        }
    }
}

Transactions with Mastercard One Credential

The Mastercard One Credential (M1C) feature allows cardholders to use a single card across multiple product types, such as secured credit or loan, when you approve that transaction from your Just-in-Time funding gateway. By integrating M1C in your program, a single card product can dynamically switch between funding sources at the time of authorization, enabling flexible credit experiences like dynamic secured credit on a single Mastercard credential.

M1C simulation support must be enabled for your program before use. Please contact your Marqeta representative to configure.

You can simulate M1C transactions for authorization, authorization.reversal, authorization.incremental, and refund.authorization by including the flex object and related details in a POST request to the following endpoints:

/simulations/cardtransactions/authorization
/simulations/cardtransactions/authorization.reversal
/simulations/cardtransactions/authorization.incremental
/simulations/cardtransactions/refund.authorization

For information about the /simulations/cardtransactions/* endpoints, see Simulate authorization.

Authorization transaction with Mastercard One Credential

The following example shows an authorization transaction with M1C for the Mastercard network.

Sample request body

JSON

{
  "card_token": "<card_token>",
  "amount": 10,
  "card_acceptor": {
    "mid": "11111"
  },
  "network": "MASTERCARD",
  "flex": {
    "eligible": true,
    "eligible_products": [
      "LOAN",
      "SECURED_CREDIT"
    ]
  }
}

Sample response body

JSON

{
  "transaction": {
    "type": "authorization",
    "state": "PENDING",
    "token": "<transaction_token>",
    "user_token": "<user_token>",
    "card_token": "<card_token>",
    "response": {
      "code": "0000",
      "memo": "Approved or completed successfully"
    },
    "created_time": "2026-10-08T21:58:44Z",
    "user_transaction_time": "2026-10-08T21:58:44Z",
    "settlement_date": "2026-10-08T00:00:00Z",
    "amount": "10.00",
    "request_amount": "10.00",
    "gpa": {
      "ledger_balance": "29687.38",
      "available_balance": "502.00",
      "impacted_amount": "-10.00"
    },
    "currency_code": "USD",
    "currency_conversion": {
      "original_amount": "10.00",
      "conversion_rate": 1.0,
      "original_currency_code": "840"
    },
    "network": "MASTERCARD",
    "acquirer_fee_amount": "0",
    "flex": {
      "eligible": "true",
      "selected_product": "SECURED_CREDIT"
    },
    "fraud": {
      "network": {
        "transaction_risk_score": 48,
        "transaction_risk_score_reason_code": "15",
        "transaction_risk_score_reason_description": "High risk country"
      }
    },
    "card_acceptor": {
      "mid": "000000000011111",
      "poi": {
        "tid": "TR100000",
        "partial_approval_capable": "0",
        "cardholder_presence": "0",
        "card_presence": "0",
        "channel": "OTHER",
        "processing_type": "MAGSTRIPE",
        "pin_present": "false"
      }
    },
    "gpa_order": {
      "amount": "10.00",
      "created_time": "2026-10-08T21:58:45Z",
      "currency_code": "USD",
      "funding": {
        "amount": "10.00",
        "gateway_log": {
          "duration": 69,
          "message": "Approved or completed successfully",
          "order_number": "<order_number>",
          "timed_out": false,
          "transaction_id": "<gateway_transaction_id>"
        },
        "source": {
          "active": true,
          "created_time": "2025-08-05T17:15:25Z",
          "is_default_account": false,
          "last_modified_time": "2025-08-05T17:15:25Z",
          "token": "<funding_source_token>",
          "type": "programgateway"
        }
      },
      "funding_source_token": "<funding_source_token>",
      "jit_funding": {
        "amount": "10.00",
        "balances": {},
        "method": "pgfs.authorization",
        "token": "<jit_funding_token>",
        "user_token": "<user_token>"
      },
      "last_modified_time": "2026-10-08T21:58:45Z",
      "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
      },
      "state": "PENDING",
      "token": "<gpa_order_token>",
      "transaction_token": "<gpa_order_transaction_token>",
      "user_token": "<user_token>"
    },
    "original_credit": {}
  }
}

For more information about how to incorporate Mastercard One Credential support in your program, contact your Marqeta representative.

Getting Started

Testing

Card Issuing

Card Processing

Accounts & Money Movement

Risk, Fraud, and Disputes

Cardholder User Experience

International card transactions and currency conversion

Authorization events with currency conversion

Sample request body

Sample response body

Clearing events with currency conversion

Sample request body

Sample response body

Transactions with Account Name Inquiry

ANI for Visa

Sample request body

Sample response body

ANI for Mastercard

Sample request body

Sample response body

Transactions with Address Verification

AVS for Visa

Sample request body

Sample response body

Transactions with Mastercard One Credential

Authorization transaction with Mastercard One Credential

Sample request body

Sample response body

​International card transactions and currency conversion

​Authorization events with currency conversion

​Sample request body

​Sample response body

​Clearing events with currency conversion

​Sample request body

​Sample response body

​Transactions with Account Name Inquiry

​ANI for Visa

​Sample request body

​Sample response body

​ANI for Mastercard

​Sample request body

​Sample response body

​Transactions with Address Verification

​AVS for Visa

​Sample request body

​Sample response body

​Transactions with Mastercard One Credential

​Authorization transaction with Mastercard One Credential

​Sample request body

​Sample response body

International card transactions and currency conversion

Authorization events with currency conversion

Sample request body

Sample response body

Clearing events with currency conversion

Sample request body

Sample response body

Transactions with Account Name Inquiry

ANI for Visa

Sample request body

Sample response body

ANI for Mastercard

Sample request body

Sample response body

Transactions with Address Verification

AVS for Visa

Sample request body

Sample response body

Transactions with Mastercard One Credential

Authorization transaction with Mastercard One Credential

Sample request body

Sample response body