Simulations

Overview

The simulate endpoints within Card Management allow you to simulate most of the transaction scenarios you would experience in a live environment.

Simulate Authorization

This endpoint is used to simulate a merchant authorization that affects the available balance on the deposit account.

POST /cardmanagement/v1/simulate/authorization
{  
  "cardId": "00000000-0000-0000-0000-000000000000",
  "amount": 100,
  "merchantCountryCode": "US",
  "merchantName": "ACME CO",
  "merchantStreet": "123 Main Street",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantPostalCode": "10025"
}

When the authorization is made, a memo post reflects the account and impacts the available balance. However, the memo post remains until the clearing endpoint is called. Calling the clearing endpoint replaces the memo post with a core transaction to post the activity record to the account. The transaction does not post on the account until the simulate/clearing endpoint is called using the retrievalReferenceNumber and cardId returned in your simulate/authorization endpoint response.

{
  "retrievalReferenceNumber": "string",
  "cardId": "00000000-0000-0000-0000-000000000000"
}

Simulate Clearing

This endpoint finalizes simulated authorizations by using the retrievalReferenceNumber returned in the authorization endpoint. This completes the authorization process and posts the transaction to the deposit account.

POST /cardmanagement/v1/simulate/clearing
{
  "cardId": "00000000-0000-0000-0000-000000000000",
  "retrievalReferenceNumber": 123
}

Simulate Reversal

This endpoint is used to reverse an existing authorization using the retrievalReferenceNumber returned in the authorization endpoint. This reverses the original authorization placed on the account and removes it from the deposit account activity. The amount in this request can be any value and does not have to be the same amount as the original clearing transaction, which allows for a partial amount reversal.

POST / cardmanagement /v1/simulate/reversal
{
  "cardId": "00000000-0000-0000-0000-000000000000",
  "retrievalReferenceNumber": 123,
  "amount": 123
}

Simulate Incremental

This endpoint, used with the retrievalReferenceNumber returned by the authorization endpoint, creates an incremental transaction reflected in the deposit account activity. An example of an incremental transaction is when a hotel adds an additional charge for an item charged to your room.

POST / cardmanagement /v1/simulate/incremental
{
  "cardId": "00000000-0000-0000-0000-000000000000",
  "retrievalReferenceNumber": 123,
  "amount": 123
}

Simulate Single Message Clearing

A single message is a message type that uses real-time verification and requires the cardholder to enter their PIN to authorize and clear their transaction. An example of a transaction that uses a single message is an ATM withdrawal.

POST /cardmanagement/v1/simulate/single-message-clearing
{  
  "cardId": "00000000-0000-0000-0000-000000000000",
  "amount": 100,
  "merchantCountryCode": "US",
  "merchantName": "ACME CO",
  "merchantStreet": "123 Main Street",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantPostalCode": "10025"
}

Simulate Single Message Reversal

This endpoint allows you to create a reversal transaction to a single message clearing transaction. For example, use the single-message-clearing endpoint to simulate a purchase and then simulate a return with the single-message-reversal.

POST /cardmanagement/v1/simulate/single-message-reversal
{  
  "cardId": "00000000-0000-0000-0000-000000000000",
  "amount": 100,
  "merchantCountryCode": "US",
  "merchantName": "ACME CO",
  "merchantStreet": "123 Main Street",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantPostalCode": "10025"
}

Simulate Financial Advice

Financial Advice is a message sent about a transaction that has already taken place. It is often used when a “stand-in” is used if a system is unavailable. Financial Advice messages force-post to the account and can cause the account to go negative.

POST /cardmanagement/v1/simulate/financial-advice
{  
  "cardId": "00000000-0000-0000-0000-000000000000",
  "amount": 100,
  "merchantCountryCode": "US",
  "merchantName": "ACME CO",
  "merchantStreet": "123 Main Street",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantPostalCode": "10025"
}