--- title: Simulate card management slug: tutorials/api/cards/simulate-card-management description: Guides simulating authorizations, clearings, reversals, etc., via card simulation APIs. docTags: createdAt: 2024-08-12T07:33:43.219Z --- ## What you will learn ✅ How to simulate these card management actions: - Clearing - Reversal - Incremental transaction - Single message clearing - Single message reversal :::hint{type="info"} If you are new to card issuing we recommend you read the [Cards](docId\:xJUtOOcHA5khMt9uzyS18) concept pages before starting this tutorial. The tutorial assumes you have a knowledge of APIs and how they work. For more information on sending API calls, see [API basics](docId\:pUTTCwQ5SKLzxYzIn5D1b). ::: The tutorial uses these API endpoints: | API | Description | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | [POST /v1/simulate/authorization](docId\:KlhKL7f7udKCkg4lK2vWI) | Simulates merchant authorization | | [POST /v1/simulate/clearing](docId\:JkywJbbJ5vZss_4VYApdu) | Simulates replacement of a memo post with a core transaction | | [POST /v1/simulate/reversal](docId:--Zu5qBy2bYatnKskhGMX) | Simulates reversal of an authorization | | [POST /v1/simulate/incremental](docId\:RTQomduN8IwgfOgeqZpav) | Simulates an incremental transaction reflected in the deposit account activity | | [POST /v1/simulate/single-message-clearing](docId\:fOEhdDYZNvdGf-E2QnxL7) | Simulations the message type for cardholder verification to authorize and clear a transaction | | [POST /v1/simulate/single-message-reversal](docId\:o5jr5Y2sCriIC2hagqXgL) | Simulates a single message clearing transaction for which you can create a reversal transaction | ## Before you begin Make sure you have: - [API credentials](docId\:wmg-1Fqwq3bj-D3c3HFfs) - Client ID ## Register relevant webhook events To receive the webhook events for this tutorial both partner accounts need to [register](docId\:BN5XtgkJogBe-CtwomCbS) each specific webhook event type. Once you are registered, the event objects are sent to the registered URLs. The event object contains a list of resource identifiers used to download details on each event. ## Simulate card management The `simulate` endpoints within Card Management allow you to simulate most of the transaction scenarios you would experience in a live environment. ### To simulate authorization Call [POST /v1/simulate/authorization](docId\:KlhKL7f7udKCkg4lK2vWI). This endpoint simulates a merchant authorization that affects the available balance on the deposit account. :::CodeblockTabs Simulate authorization request ```curl curl --location 'https://sandbox.crbcos.com/cardmanagement/v1/simulate/authorization' \ --data '{ "amount": 1999, "cardId": "8c6a53e0-83ad-4b76-b446-b300006a3e6a", "merchantCountryCode": "US", "merchantName": "StreamFlix", "merchantStreet": "123 Any St", "merchantCity": "Anywhere", "merchantState": "NY", "merchantPostalCode": "10001", "cardNetwork": "Visa", "additionalAmounts": [], "processingCode": "BillPayment" }' ``` ::: The response includes the `retrievalReferenceNumber` and the `cardId`. You need these values to replace the memo post with a core transaction to post the activity record to the account, using the endpoint `POST /v1/simulate/clearing` as explained below. :::CodeblockTabs Simulate authorization response ```json { "retrievalReferenceNumber": "644371423186", "cardId": "8c6a53e0-83ad-4b76-b446-b300006a3e6a" } ``` ::: ### To simulate clearing In a real transaction, when the authorization request 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 [POST /v1/simulate/clearing](docId\:JkywJbbJ5vZss_4VYApdu) endpoint replaces the memo post with a core transaction to post the activity record to the account. In this simulation, authorization is not complete and the transaction does not post on the account until the `simulate/clearing` endpoint is called using the `retrievalReferenceNumber` and `cardId`. :::CodeblockTabs Simulate clearing request ```curl curl --location 'https://sandbox.crbcos.com/cardmanagement/v1/simulate/clearing' \ --data '{ "cardId": "8c6a53e0-83ad-4b76-b446-b300006a3e6a", "retrievalReferenceNumber": "644371423186", "processingCode": "BillPayment" }' ``` ::: ### To simulate reversal This endpoint is used to reverse an existing authorization using the `retrievalReferenceNumber` returned in the response to the [POST /v1/simulate/reversal](docId:--Zu5qBy2bYatnKskhGMX) 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. :::CodeblockTabs Simulate reversal request ```curl curl --location 'https://sandbox.crbcos.com/cardmanagement/v1/simulate/reversal' \ --data '{ "cardId": "8c6a53e0-83ad-4b76-b446-b300006a3e6a", "retrievalReferenceNumber": "654492282074", "amount": "123" }' ``` ::: ### To simulate a incremental transaction This endpoint, used with the `retrievalReferenceNumber` returned by the [POST /v1/simulate/incremental](docId\:RTQomduN8IwgfOgeqZpav) 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. :::CodeblockTabs Simulate incremental request ```curl curl --location 'https://sandbox.crbcos.com/cardmanagement/v1/simulate/incremental' \ --data '{ "cardId": "8c6a53e0-83ad-4b76-b446-b300006a3e6a", "retrievalReferenceNumber": "654492282074", "amount": "123" }' ``` ::: ### To 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 the [POST /v1/simulate/single-message-clearing](docId\:fOEhdDYZNvdGf-E2QnxL7) enpoint is an ATM withdrawal. :::CodeblockTabs Simulate single message clearing request ```curl curl --location 'https://sandbox.crbcos.com/cardmanagement/v1/simulate/single-message-clearing' \ --data '{ "processingCode": "Purchase", "cardId": "8c6a53e0-83ad-4b76-b446-b300006a3e6a", "amount": "22", "merchantCountryCode": "US", "merchantName": "StreamFlix", "merchantStreet": "123 Any St", "merchantCity": "Anywhere", "merchantState": "NY", "merchantPostalCode": "10001", "cardNetwork": "Visa", "additionalAmounts": [ { "amountType": "Unknown", "accountType": "NotSpecified", "amount": "10" } ] } ' ``` ::: ### To simulate single message reversal This endpoint allows you to create a reversal transaction to a single message clearing transaction. For example, use the [POST /v1/simulate/single-message-reversal](docId\:o5jr5Y2sCriIC2hagqXgL) endpoint to simulate a purchase and then simulate a return with the `single-message-reversal`. :::CodeblockTabs Simulate single message reversal request ```curl curl --location 'https://sandbox.crbcos.com/cardmanagement/v1/simulate/single-message-reversal' \ --data '{ "amount": "22", "processingCode": "Purchase", "cardId": "8c6a53e0-83ad-4b76-b446-b300006a3e6a", "merchantCountryCode": "US", "merchantName": "StreamFlix", "merchantStreet": "123 Any St", "merchantCity": "Anywhere", "merchantState": "NY", "merchantPostalCode": "10001", "cardNetwork": "Visa", "additionalAmounts": [ { "amountType": "Unknown", "accountType": "NotSpecified", "amount": "10" } ] } ' ``` :::