Learn how to simulate various card payment scenarios in our staging environment. This guide covers how to test different outcomes, such as approved transactions and reversals.
Note: The set of endpoints below is only available and enabled in the staging environment. These endpoints will allow you to simulate card authorizations and reversals before the live environment.
Prerequisites
For programs with standard accounts, the user account should be enough balance to cover the simulated transaction amounts.
For programs with mJIT accounts, the must meet the following requirements:
a. The Pre Authorization webhook for Shared Authorization must be subscribed.
b. The Pre Authorization partner response must be sent within the alloted time.
c. The program prefund must have enough balance to cover the intended simulated transaction amounts.
Debugging
For simulation failures, you can go to the AdminNet dashboard > Cards > Purchase History. Then on Filters > select Status > where status is Failed to reveal your simulated transaction and its reason for failure.
Figure: Adminnet dashboard - Card Transactions
Simulate Card Authorizations
The following mock payload is required to initiate a card transaction authorization request. Partners will need to follow the payload field definitions stated below. Refer to the simulated card authorization API call on the right.
Payload Definition
Field
Description
network
Network defines the network for transaction, e.g. MASTER, VISA
channel
Channel defines the channel for transaction, e.g. POS, ECOM, ATM
card_hash_id
Card ID of the card to be used for transaction
card_currency_code
Currency code of the card (Use ISO4217 value of currency), e.g. SGD, USD, PHP
card_amount
Card transaction amount in local currency
transaction_currency_code
Currency code of the transaction (use ISO4217 value of currency), e.g. SGD, USD, PHP
transaction_amount
Transaction amount
terminal_id
Terminal ID of the POS used in the transaction. (should be 8 characters in length)
merchant_id
Merchant ID of the merchant in the transaction
merchant_name
Merchant name
merchant_category_code
Merchant category code (MCC)
pos_entry_mode_code
POS Entry Mode Code allowed values:
MANUALLY_KEYED
MAGSTRIPE_READ_GENERAL_TRACK2
MAGSTRIPE_READ_GENERAL_TRACK1
CONTACTLESS_CHIP
MANUALLY_KEYED_ECOM
MAGSTRIPE_FULL_READ
CONTACTLESS_MAGSTRIPE_ORIGIN
card_number
First 10-digit of card number or PAN to be used for transaction
product_code
The partner program code assigned to the program, e.g. sgmmcard
acquiring_country_code
Acquiring country code in ISO3166_alpha3 country code value, e.g. SGP, PHP
transaction_type
[Optional] Transaction type: Only required for simulation of Account Status Inquiry (ASI) transactions.
When the transaction type is passed as account_verification, the card amount & transaction amount will be ignored.
Allowed value: account_verification
risk_details
[Optional] Risk details: Contains additional risk-related data elements received from the network to assist in transaction risk assessment and fraud decisioning.
Security services data (security_services_data): List of security service indicators and their corresponding insights. Eg - (indicator: AQS, insight: 409)
Fraud scoring data (fraud_scoring_data): List of fraud scoring key-value pairs for risk assessment. Eg - (key: FRAUD_SCORE, value: 075)
pos_data
[Optional] POS Data: Contains DE 61 POS data elements. All sub-fields are optional strings.
Call the Simulate Card Transaction Authorizations(POST /v1/card-transactions/authorize/test) passing the required simulation parameters.
Card transaction simulation only
If you only intend to simulate a basic card authorization transaction without evaluating risk data, you can drop the OPTIONAL request parameters, such as
transaction_type
risk_details
pos_data
additional_transaction_data
authentication
These optional fields are mainly used to simulate the evaluation of additional transaction risk data before allowing authorization. See Assisted card transaction risk management section to learn more.
Before the partner can simulate a reversal, a previously successful card authorization will be required. The transaction reference code of the successful transaction is required to run a reversal simulation. Refer to the simulated reversal API call on the right.
Call the Simulate Card Transaction Reversals(POST /v1/card-transactions/reverse/test) passing the required simulation parameters.
Purchase or withdraw more than the wallet/card balance. Set transaction_amount greater than wallet or card balance
OPENLOOP_DECLINED_INSUFFICIENT_BALANCE
Declined - Card Permanently Blocked
First block or delete the card_hash_id or the card ID, then simulate a transaction.
OPENLOOP_DECLINED_CARD_BLOCKED
Declined - Card Temporarily Suspended
First suspend the card_hash_id or the card ID, then simulate a transaction.
OPENLOOP_DECLINED_CARD_SUSPENDED
Declined - Invalid Transaction Type
Try an ATM withdrawal using a virtual card. Set channel: atm and card_hash_id = card ID of a virtual card
OPENLOOP_DECLINED_INVALID_TRANSACTIONTYPE
Declined - Unsupported Merchant
You can blacklist certain merchants or MCC IDs from the program configuration. When blacklisted, you can pass your blacklisted MCCs, or you can also pass the following MCCs, which are blacklisted by default: <7800, 7801, 7802, 7995, 9406> in the merchant_category_code.
OPENLOOP_DECLINED_UNSUPPORTED_PROGRAM_MERCHANTS
Successful - Reversal for a previous successful transaction
Set the transaction_ref_no to the original successful transaction reference number that you want to reverse.
OPENLOOP_TRANSACTION_REVERSAL
Declined - User Temporarily Suspended
First, set the user ID of the user as temporarily locked or suspended via DELETE /users.
OPENLOOP_DECLINED_USER_SUSPENDED
Declined - User Permanently Blocked
First, set the user ID of the user as permanently blocked or deleted via DELETE /users.
OPENLOOP_DECLINED_USER_BLOCKED
Purchase or Withdrawal more than KYC Limit
Set the transaction_amount to be greater than the KYC limit.
Invoke an ASI (Account Status Inquiry) transaction
Set transaction_type: ASI
CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION
Successful - ASI transaction
Set transaction_type: ASI
CARDS.ACCOUNT_VERIFICATION.STATUS
Declined - Card Permanently Blocked
First block or delete the card_hash_id or the card ID, then simulate a transaction.
CARD_BLOCKED
Declined - Card Temporarily Suspended
First suspend the card_hash_id or the card ID, then simulate a transaction.
CARD_SUSPENDED
Declined - User Temporarily Suspended
First, set the user ID of the user as temporarily locked or suspended via DELETE /users.
USER_SUSPENDED
Declined - User Permanently Blocked
First, set the user ID of the user as permanently blocked or deleted via DELETE /users.
USER_BLOCKED
Declined - Invalid Transaction Type
Try an ATM withdrawal using a virtual card. Set channel: atm and card_hash_id = card ID of a virtual card
INVALID_TRANSACTIONTYPE
Declined - Unsupported Merchant
You can blacklist certain merchants or MCC IDs from the program configuration. When blacklisted, you can pass your blacklisted MCCs, or you can also pass the following MCCs, which are blacklisted by default: <7800, 7801, 7802, 7995, 9406> in the merchant_category_code.
UNSUPPORTED_PROGRAM_MERCHANTS
Successful - Reversal for a previous successful transaction
Set the transaction_ref_no to the original successful transaction reference number that you want to reverse.