Overview

This section provides APIs to simulate various card transaction events in the Sandbox environment. These simulations transaction flows such as authorization, settlement, reversal, ATM withdrawals, merchant credits, and fee related events.

Attributes

Field	Type	Mandatory/Optional	Description
resourceName	Enum	-	Name of the resource. It will be simulate.
url	Object	-	System generated endpoint which can be used to fetch the transaction.
card	Object	Mandatory	Debit or Prepaid Card issued by the Program Manager.
card.id	String	-	Reference id assigned by program manager.
card.externalId	String	Conditional	External ID assigned by program manager for the card.
customer	Object	Mandatory	Details of Customer to whom a card is issued.
customer.id	String	-	Reference id assigned by program manager.
customer.externalId	String	Conditional	External ID assigned by program manager for the customer.
eventType	String	Mandatory	Type of simulation event to be triggered. Possible values: AUTHORIZATION, SETTLEMENT, REVERSAL, ATM, MERCHANT_CREDIT, FEE, FEE_REVERSAL
authId	String	Conditional	Authorization ID generated from a prior authorization event. Required for settlement and reversal events.
eventDetails	Object	Optional	Additional details required for the transaction event.
eventDetails.amount	String	Optional	Amount is supported for evenType "FEE_REVERSAL" and for other fee events following are the amounts that are explicitily set : FOREIGN_TRANSACTION_FEE - 1.50 dollar ATM_WITHDRAWAL_FEE_DOMESTIC - 3.50 dollar OVER_THE_COUNTER_WITHDRAWAL_FEE_DOMESTIC - 2.50 dollar REPLACE_CARD_FEE - 10.00 dollar EXPRESS_MAIL_FEE - 40.0dollar POS_DECLINE_INTERNATIONAL_FEE - 1.00 dollar
eventDetails.mcc	String	Optional	Merchant Category Code. Validated against Card Program configuration if provided.
eventDetails.mid	String	Optional	Merchant Identifier. Validated against Card Program configuration if provided.
eventDetails.feeType	Enum	Mandatory (for fee and fee reversal)	Type of fee. Possible values: POS_DECLINE_INTERNATIONAL_FEE, FOREIGN_TRANSACTION_FEE, ATM_WITHDRAWAL_FEE_DOMESTIC, OVER_THE_COUNTER_WITHDRAWAL_FEE_DOMESTIC, REPLACE_CARD_FEE, EXPRESS_MAIL_FEE

Error Codes & Messages

Error Code	Error Message	Condition
EC-VA-0005	{<br>"errorCode": "EC-VA-0005",<br>"errorMessage": "Validation failed.",<br>"errors": [<br>  {<br>  "field": "<field-name>",<br>  "message": "Is required."<br>  }<br>]<br>}	Card identification details are missing. Either `card.id` or `card.externalId` must be provided.
EC-VA-0005	{<br>"errorCode": "EC-VA-0005",<br>"errorMessage": "Validation failed.",<br>"errors": [<br>  {<br>  "field": "customer",<br>  "message": "id or externalId is required."<br>  }<br>]<br>}	Customer identification details are missing. Either `customer.id` or `customer.externalId` must be provided.
EC-VA-0005	{<br>"errorCode": "EC-VA-0005",<br>"errorMessage": "Validation failed.",<br>"errors": [<br>  {<br>  "field": "eventDetails.amount",<br>  "message": "Should be between 0.01 and 99999999.99 and supports upto 2 decimals."<br>  }<br>]<br>}	Invalid amount value passed. Amount must be within the supported range and format.
EC-BL-0020	{<br>"errorCode": "EC-BL-0020",<br>"errorMessage": "Card with id: 3912 does not exist."<br>}	The provided `card.id` does not exist in the system.
EC-VA-0001	{<br>"errorCode": "EC-VA-0001",<br>"errorMessage": "Validation Failed.",<br>"errors": [<br>  {<br>  "field": "eventType",<br>  "message": "Invalid Value AUTHORIZATIONs for field eventType."<br>  }<br>]<br>}	Invalid value provided for `eventType`. Supported values must be used.

Card Transactions

Usecase 1: Authorization

Sandbox Simulation Data	Result
Step 1: Create Authorization Make a request to POST /v1/simulate/issuance with eventType as AUTHORIZATION. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "AUTHORIZATION", "eventDetails": { "amount": "11.5" } }	Hold ledger is created. Unique authId is generated. Ledger webhook is triggered, if configured by the Program Manager. For prepaid cards, transaction activity is recorded. Example Response: { "response_code": "00", "status": "AUTHORIZED", "statusReason": "Approved. The transaction has been successfully authorized.", "authId": "100000025", "ledger": [ { "type": "DEBIT", "amount": "15.40", "ledgerType": "HOLD", "narration": "Pending To *3443 - EXXON PRATTVILLE COOSA PRATTVILLE AL" } ] }

Sandbox Simulation Data

Result

Step 1: Create Authorization

Make a request to POST /v1/simulate/issuance with eventType as AUTHORIZATION.

Example Request:

{
    "card": {
        "id": "688"
    },
    "customer": {
        "id": "4007187"
    },
    "eventType": "AUTHORIZATION",
    "eventDetails": {
        "amount": "11.5"
    }
}

Hold ledger is created.
Unique authId is generated.
Ledger webhook is triggered, if configured by the Program Manager.
For prepaid cards, transaction activity is recorded.

Example Response:

{
    "response_code": "00",
    "status": "AUTHORIZED",
    "statusReason": "Approved. The transaction has been successfully authorized.",
    "authId": "100000025",
    "ledger": [
        {
            "type": "DEBIT",
            "amount": "15.40",
            "ledgerType": "HOLD",
            "narration": "Pending To *3443 - EXXON PRATTVILLE COOSA PRATTVILLE AL"
        }
    ]
}

Usecase 2: Settlement

Sandbox Simulation Data	Result
Step 1: Create Authorization Create an authorization event to generate an authId. Step 2: Create Settlement Make a request to POST /v1/simulate/issuance with eventType as SETTLEMENT. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "SETTLEMENT", "eventDetails": { "authId": "100000025" } }	Step 1: For Authorization Hold ledger is created. Unique authId is generated. Ledger webhook is triggered, if configured by the Program Manager. Step 2: For Settlement Hold ledger is released. Final debit ledger is created. Ledger webhook is triggered, if configured by the Program Manager. For prepaid cards, transaction activity is updated. Example Response: { "response_code": "0", "status": "SETTLED", "statusReason": "Settled. The transaction has been successfully settled.", "authId": "100000025", "ledger": [ { "type": "DEBIT", "amount": "15.40", "ledgerType": "HOLD", "narration": "Pending To 3443 - EXXON PRATTVILLE COOSA PRATTVILLE AL" }, { "type": "CREDIT", "amount": "15.40", "ledgerType": "RELEASE", "narration": "Released 3443 - Widgets Incorporated NEW YORK, NY" }, { "type": "DEBIT", "amount": "15.40", "ledgerType": "SETTLE", "narration": "*3443 - Widgets Incorporated NEW YORK, NY" } ] }

Sandbox Simulation Data

Result

Step 1: Create Authorization

Create an authorization event to generate an authId.

Step 2: Create Settlement

Make a request to POST /v1/simulate/issuance with eventType as SETTLEMENT.

Example Request:

{
    "card": {
        "id": "688"
    },
    "customer": {
        "id": "4007187"
    },
    "eventType": "SETTLEMENT",
    "eventDetails": {
        "authId": "100000025"
    }
}

Step 1: For Authorization

Hold ledger is created.
Unique authId is generated.
Ledger webhook is triggered, if configured by the Program Manager.

Step 2: For Settlement

Hold ledger is released.
Final debit ledger is created.
Ledger webhook is triggered, if configured by the Program Manager.
For prepaid cards, transaction activity is updated.

Example Response:

{
    "response_code": "0",
    "status": "SETTLED",
    "statusReason": "Settled. The transaction has been successfully settled.",
    "authId": "100000025",
    "ledger": [
        {
            "type": "DEBIT",
            "amount": "15.40",
            "ledgerType": "HOLD",
            "narration": "Pending To *3443 - EXXON PRATTVILLE COOSA PRATTVILLE AL"
        },
        {
            "type": "CREDIT",
            "amount": "15.40",
            "ledgerType": "RELEASE",
            "narration": "Released *3443 - Widgets Incorporated NEW YORK, NY"
        },
        {
            "type": "DEBIT",
            "amount": "15.40",
            "ledgerType": "SETTLE",
            "narration": "*3443 - Widgets Incorporated NEW YORK, NY"
        }
    ]
}

Usecase 3: ATM Withdrawal

Sandbox Simulation Data	Result
Step 1: Create Authorization for ATM withdrawal to generate authId. Step 2: Create Settlement by calling POST /v1/simulate/issuance with eventType as ATM. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "ATM", "eventDetails": { "authId": "100000030" } }	Step 1: For Authorization Hold ledger is created. Unique authId is generated. Ledger webhook is triggered, if configured by the Program Manager. Step 2: For ATM Withdrawal Settlement Hold ledger is released. Final debit ledger is created. Ledger webhook is triggered, if configured by the Program Manager. ATM fee ledger is created. For prepaid cards, transaction activity is updated. Example Response: { "response_code": "0", "status": "SETTLED", "statusReason": "Settled. The transaction has been successfully settled.", "authId": "100000030", "ledger": [ { "type": "DEBIT", "amount": "7.50", "ledgerType": "HOLD" }, { "type": "CREDIT", "amount": "7.50", "ledgerType": "RELEASE" }, { "type": "DEBIT", "amount": "7.50", "ledgerType": "SETTLE" } ] }

Sandbox Simulation Data

Result

Step 1: Create Authorization for ATM withdrawal to generate authId.

Step 2: Create Settlement by calling POST /v1/simulate/issuance with eventType as ATM.

Example Request:

{
    "card": { "id": "688" },
    "customer": { "id": "4007187" },
    "eventType": "ATM",
    "eventDetails": {
        "authId": "100000030"
    }
}

Step 1: For Authorization

Hold ledger is created.
Unique authId is generated.
Ledger webhook is triggered, if configured by the Program Manager.

Step 2: For ATM Withdrawal Settlement

Hold ledger is released.
Final debit ledger is created.
Ledger webhook is triggered, if configured by the Program Manager.
ATM fee ledger is created.
For prepaid cards, transaction activity is updated.

Example Response:

{
    "response_code": "0",
    "status": "SETTLED",
    "statusReason": "Settled. The transaction has been successfully settled.",
    "authId": "100000030",
    "ledger": [
        {
            "type": "DEBIT",
            "amount": "7.50",
            "ledgerType": "HOLD"
        },
        {
            "type": "CREDIT",
            "amount": "7.50",
            "ledgerType": "RELEASE"
        },
        {
            "type": "DEBIT",
            "amount": "7.50",
            "ledgerType": "SETTLE"
        }
    ]
}

Usecase 4: Reversal (Full Amount)

Sandbox Simulation Data	Result
Step 1: Create Authorization for reversal to generate authId. Step 2: Create Reversal by calling POST /v1/simulate/issuance with eventType as REVERSAL. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "REVERSAL", "eventDetails": { "authId": "100000032", "amount": "20.50" } }	Step 1: For Authorization Hold ledger is created. Unique authId is generated. Ledger webhook is triggered, if configured by the Program Manager. Step 2: For Reversal Hold ledger is released. Release ledger is created for reversed amount. Reversed amount is credited to the account. Ledger webhook is triggered, if configured by the Program Manager. For prepaid cards, transaction activity is updated. Example Response: { "response_code": "0", "status": "SETTLED", "statusReason": "Settled. The transaction has been successfully settled.", "authId": "100000032", "ledger": [ { "type": "DEBIT", "amount": "20.50", "ledgerType": "HOLD" }, { "type": "CREDIT", "amount": "20.50", "ledgerType": "RELEASE" } ] }

Sandbox Simulation Data

Result

Step 1: Create Authorization for reversal to generate authId.

Step 2: Create Reversal by calling POST /v1/simulate/issuance with eventType as REVERSAL.

Example Request:

{
    "card": { "id": "688" },
    "customer": { "id": "4007187" },
    "eventType": "REVERSAL",
    "eventDetails": {
        "authId": "100000032",
        "amount": "20.50"
    }
}

Step 1: For Authorization

Hold ledger is created.
Unique authId is generated.
Ledger webhook is triggered, if configured by the Program Manager.

Step 2: For Reversal

Hold ledger is released.
Release ledger is created for reversed amount.
Reversed amount is credited to the account.
Ledger webhook is triggered, if configured by the Program Manager.
For prepaid cards, transaction activity is updated.

Example Response:

{
    "response_code": "0",
    "status": "SETTLED",
    "statusReason": "Settled. The transaction has been successfully settled.",
    "authId": "100000032",
    "ledger": [
        {
            "type": "DEBIT",
            "amount": "20.50",
            "ledgerType": "HOLD"
        },
        {
            "type": "CREDIT",
            "amount": "20.50",
            "ledgerType": "RELEASE"
        }
    ]
}

Usecase 5: Reversal (Partial Amount)

Sandbox Simulation Data	Result
Step 1: Create Authorization for reversal to generate authId. Step 2: Create Reversal by calling POST /v1/simulate/issuance with eventType as REVERSAL. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "REVERSAL", "eventDetails": { "authId": "100000034", "amount": "7.50" } }	Step 1: For Authorization Hold ledger is created. Unique authId is generated. Ledger webhook is triggered, if configured by the Program Manager. Step 2: For Reversal Hold ledger is released. Release ledger is created for reversed amount. Reversed amount is credited to the account. In case of partial reversal, the remaining amount is debited. Ledger webhook is triggered, if configured by the Program Manager. For prepaid cards, transaction activity is updated. Example Response: { "response_code": "0", "status": "SETTLED", "statusReason": "Settled. The transaction has been successfully settled.", "authId": "100000034", "ledger": [ { "type": "DEBIT", "amount": "11.50", "ledgerType": "HOLD", "narration": "Pending To 3443 - EXXON PRATTVILLE COOSA PRATTVILLE AL" }, { "type": "CREDIT", "amount": "11.50", "ledgerType": "RELEASE", "narration": "Released 3443 - Widgets Incorporated NEW YORK, NY" }, { "type": "DEBIT", "amount": "4.00", "ledgerType": "SETTLE", "narration": "*3443 - Widgets Incorporated NEW YORK, NY" } ] }

Sandbox Simulation Data

Result

Step 1: Create Authorization for reversal to generate authId.

Step 2: Create Reversal by calling POST /v1/simulate/issuance with eventType as REVERSAL.

Example Request:

{
    "card": {
        "id": "688"
    },
    "customer": {
        "id": "4007187"
    },
    "eventType": "REVERSAL",
    "eventDetails": {
        "authId": "100000034",
        "amount": "7.50"
    }
}

Step 1: For Authorization

Hold ledger is created.
Unique authId is generated.
Ledger webhook is triggered, if configured by the Program Manager.

Step 2: For Reversal

Hold ledger is released.
Release ledger is created for reversed amount.
Reversed amount is credited to the account.
In case of partial reversal, the remaining amount is debited.
Ledger webhook is triggered, if configured by the Program Manager.
For prepaid cards, transaction activity is updated.

Example Response:

{
    "response_code": "0",
    "status": "SETTLED",
    "statusReason": "Settled. The transaction has been successfully settled.",
    "authId": "100000034",
    "ledger": [
        {
            "type": "DEBIT",
            "amount": "11.50",
            "ledgerType": "HOLD",
            "narration": "Pending To *3443 - EXXON PRATTVILLE COOSA PRATTVILLE AL"
        },
        {
            "type": "CREDIT",
            "amount": "11.50",
            "ledgerType": "RELEASE",
            "narration": "Released *3443 - Widgets Incorporated NEW YORK, NY"
        },
        {
            "type": "DEBIT",
            "amount": "4.00",
            "ledgerType": "SETTLE",
            "narration": "*3443 - Widgets Incorporated NEW YORK, NY"
        }
    ]
}

Usecase 6: Merchant Credit

Sandbox Simulation Data	Result
Step 1: Create Merchant Credit by calling POST /v1/simulate/issuance with eventType as MERCHANT_CREDIT. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "MERCHANT_CREDIT", "eventDetails": { "amount": "7.50" } }	Step 1: For Merchant Credit Credit ledger is created. Funds are added to the customer’s balance. Ledger webhooks are triggered. Transaction activity is recorded. Example Response: { "response_code": "00", "status": "AUTHORIZED", "statusReason": "Approved. The transaction has been successfully authorized.", "authId": "100000036" }

Sandbox Simulation Data

Result

Step 1: Create Merchant Credit by calling POST /v1/simulate/issuance with eventType as MERCHANT_CREDIT.

Example Request:

{
    "card": {
        "id": "688"
    },
    "customer": {
        "id": "4007187"
    },
    "eventType": "MERCHANT_CREDIT",
    "eventDetails": {
        "amount": "7.50"
    }
}

Step 1: For Merchant Credit

Credit ledger is created.
Funds are added to the customer’s balance.
Ledger webhooks are triggered.
Transaction activity is recorded.

Example Response:

{
    "response_code": "00",
    "status": "AUTHORIZED",
    "statusReason": "Approved. The transaction has been successfully authorized.",
    "authId": "100000036"
}

Usecase 7: Fee Events

Sandbox Simulation Data	Result
Step 1: Create Fee Event by calling POST /v1/simulate/issuance with eventType as FEE. Note: Refer to the attributes table for supported fee types. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "FEE", "eventDetails": { "feeType": "ATM_WITHDRAWAL_FEE_DOMESTIC" } }	Step 1: For Fee Event Debit ledger is created for the fee amount. Fee webhook is triggered with type fee. Balance is reduced. For prepaid cards, transaction activity is recorded. Example Response: { "response_code": "0", "status": "SETTLED", "statusReason": "Settled. The transaction has been successfully settled.", "feeId": "100000037", "ledger": [ { "type": "DEBIT", "amount": "3.50", "ledgerType": "SETTLE", "narration": "3443-Debit card fees - ATM WITHDRAWAL FEE DOMESTIC" } ] }

Sandbox Simulation Data

Result

Step 1: Create Fee Event by calling POST /v1/simulate/issuance with eventType as FEE.

Note: Refer to the attributes table for supported fee types.

Example Request:

{
    "card": {
        "id": "688"
    },
    "customer": {
        "id": "4007187"
    },
    "eventType": "FEE",
    "eventDetails": {
        "feeType": "ATM_WITHDRAWAL_FEE_DOMESTIC"
    }
}

Step 1: For Fee Event

Debit ledger is created for the fee amount.
Fee webhook is triggered with type fee.
Balance is reduced.
For prepaid cards, transaction activity is recorded.

Example Response:

{
    "response_code": "0",
    "status": "SETTLED",
    "statusReason": "Settled. The transaction has been successfully settled.",
    "feeId": "100000037",
    "ledger": [
        {
            "type": "DEBIT",
            "amount": "3.50",
            "ledgerType": "SETTLE",
            "narration": "3443-Debit card fees - ATM WITHDRAWAL FEE DOMESTIC"
        }
    ]
}

Usecase 8: Fee Reversal

Sandbox Simulation Data	Result
Step 1: Create Fee Reversal Event by calling POST /v1/simulate/issuance with eventType as FEE_REVERSAL. Note: Refer to the attributes table for supported fee types. Example Request: { "card": { "id": "688" }, "customer": { "id": "4007187" }, "eventType": "FEE_REVERSAL", "eventDetails": { "amount": "11.00", "feeType": "ATM_WITHDRAWAL_FEE_DOMESTIC" } }	Step 1: For Fee Reversal Credit ledger is created for the fee reversal. Fee reversal webhook is triggered. Balance is increased. For prepaid cards, transaction activity is recorded. Example Response: { "response_code": "0", "status": "SETTLED", "statusReason": "Settled. The transaction has been successfully settled.", "feeId": "100000041", "ledger": [ { "type": "CREDIT", "amount": "11.00", "ledgerType": "SETTLE", "narration": "3443-Reversal for POS DECLINE INTERNATIONAL FEE" } ] }

Sandbox Simulation Data

Result

Step 1: Create Fee Reversal Event by calling POST /v1/simulate/issuance with eventType as FEE_REVERSAL.

Note: Refer to the attributes table for supported fee types.

Example Request:

{
    "card": {
        "id": "688"
    },
    "customer": {
        "id": "4007187"
    },
    "eventType": "FEE_REVERSAL",
    "eventDetails": {
        "amount": "11.00",
        "feeType": "ATM_WITHDRAWAL_FEE_DOMESTIC"
    }
}

Step 1: For Fee Reversal

Credit ledger is created for the fee reversal.
Fee reversal webhook is triggered.
Balance is increased.
For prepaid cards, transaction activity is recorded.

Example Response:

{
    "response_code": "0",
    "status": "SETTLED",
    "statusReason": "Settled. The transaction has been successfully settled.",
    "feeId": "100000041",
    "ledger": [
        {
            "type": "CREDIT",
            "amount": "11.00",
            "ledgerType": "SETTLE",
            "narration": "3443-Reversal for POS DECLINE INTERNATIONAL FEE"
        }
    ]
}