How to simulate card management
In this tutorial, you'll learn how to
Register the relevant webhooks
Simulate these card management actions:
Clearing
Reversal
Incremental transaction
Single message clearing
Single message reversal
If you are new to card issuing we recommend you read the card issuing management documentation 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 the API overview page.
The tutorial uses these API endpoints:
API |
Description |
---|---|
POST /v1/simulate/authorization |
Simulates merchant authorization |
POST /v1/simulate/clearing |
Simulates replacement of a memo post with a core transaction |
POST /v1/simulate/reversal |
Simulates reversal of an authorization |
POST /v1/simulate/incremental |
Simulates an incremental transaction reflected in the deposit account activity |
POST /v1/simulate/single-message-clearing |
Simulations the message type for cardholder verification to authorize and clear a transaction |
POST /v1/simulate/single-message-reversal |
Simulates a single message clearing transaction for which you can create a reversal transaction |
Before you begin
Make sure you have:
-
Client ID
1. Register the relevant webhook events
To receive the webhook events for this tutorial both partner accounts need to register 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.
2. 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.
a. To simulate authorization
Call POST /v1/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"
}
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.
Simulate authorization response
{
"retrievalReferenceNumber": "string",
"cardId": "00000000-0000-0000-0000-000000000000"
}
b. 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 A message attached to an account to indicate that funds will be withdrawn or deposited, but the transaction is not yet complete. 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. 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
.
Simulate clearing request
POST / cardmanagement /v1/simulate/reversal
{
"cardId": "00000000-0000-0000-0000-000000000000",
"retrievalReferenceNumber": "123",
"amount": 123
}
c. To simulate reversal
This endpoint is used to reverse an existing authorization using the retrievalReferenceNumber
returned in the response to 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
}
d. To simulate a incremental transaction
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.
Simulate incremental request
POST / cardmanagement /v1/simulate/incremental
{
"cardId": "00000000-0000-0000-0000-000000000000",
"retrievalReferenceNumber": 123,
"amount": 123
}
e. 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 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"
}
f. To 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"
}