Simulate Authorizations and Refunds
Simulation card data
To test your payments integration, you can use test Primary Account Numbers (PANs), addresses, and CVCs to simulate various scenarios, including specific card brands, error code responses, and successful payments.
We currently support simulation card data for the following brands:
| Card Network | PAN | CVV/CVC | Expiration | Address |
|---|---|---|---|---|
| Visa | 4000 0000 0000 0002 | 111 | Any future date | 1234 Visa St, Visa, CA 12345 |
| Mastercard | 5555 5555 5555 4444 | 222 | Any future date | 2134 Mastercard St, Mastercard, CA 21345 |
Simulate authorizations
To simulate a successful authorization, use the simulation card data above with any amount that is not in the decline amounts table and is not a reserved amount.
Authorization approvals
A successful authorization returns an AuthorizationEvent with a responseCode of APPROVED, along with verification response codes:
| Field | Description |
|---|---|
responseCode | APPROVED for a successful authorization |
avsResponseCode | Result of AVS address verification |
postalCodeResponseCode | Result of postal code verification |
cvvResponseCode | Result of CVV (security code) verification |
Authorization response code declines
The simulator emits only real network response codes. It never invents one. When a network has no distinct code for a given decline, the simulator emits the closest real code and the platform decodes it to a coarser outcome.
Six amounts return a different processorResponseCode on Visa than on Mastercard for this reason. Others return the same code from a different raw code. Read the column for the network you are testing before you assert on a response code.
For example, $44.44 returns RE_ENTER_TRANSACTION (19) on Visa and DO_NOT_HONOR (63) on Mastercard.
Three values an earlier version of this table published are not returned on either network: SUSPENDED_CARD ($8.88), TERMINATED_CARD ($9.99), and SPECIAL_CONDITION_NO_PICK_UP ($66.66). They remain valid processorResponseCode values, but no Visa or Mastercard response code decodes to them. Update any test that asserts one of the three.
To simulate a decline by response code, use one of the following transaction amounts. Set the card network using the simulation card data listed above. The parenthetical is the raw network response code the simulator emits.
| Amount | Visa returns | Mastercard returns | Retries Allowed |
|---|---|---|---|
| $1.11 | DO_NOT_HONOR (05) | DO_NOT_HONOR (05) |  |
| $2.22 | INVALID_CARD_NUMBER (14) | INVALID_CARD_NUMBER (14) |  |
| $3.33 | INSUFFICIENT_FUNDS (51) | INSUFFICIENT_FUNDS (51) | |
| $4.44 | EXPIRED_CARD (54) | EXPIRED_CARD (54) | |
| $6.67 | BAD_CVV2 (N7) | DO_NOT_HONOR (63) | Visa Mastercard |
| $7.77 | UNACTIVATED_CARD (78) | UNACTIVATED_CARD (72) | |
| $8.88 | UNACTIVATED_CARD (78) | RESTRICTED_LOCATION (62) | |
| $9.99 | CLOSED_ACCOUNT (46) | CLOSED_ACCOUNT (46) | |
| $11.11 | EXPIRED_CARD (54) | INVALID_AUTHORIZATION_EXPIRATION (84) | |
| $22.22 | BLOCKED_CARD (9G) | RESTRICTED_LOCATION (62) | |
| $33.33 | TRANSACTION_NOT_PERMITTED (57) | TRANSACTION_NOT_PERMITTED (57) | |
| $44.44 | RE_ENTER_TRANSACTION (19) | DO_NOT_HONOR (63) | |
| $55.55 | CLOSED_ACCOUNT (46) | CLOSED_ACCOUNT (46) | |
| $66.66 | UNACTIVATED_CARD (78) | TRANSACTION_NOT_PERMITTED (57) | Visa Mastercard |
| $77.77 | INVALID_MERCHANT (03) | INVALID_MERCHANT (03) | |
| $88.88 | INVALID_TRANSACTION (12) | INVALID_TRANSACTION (12) | |
| $99.99 | EXCEEDS_APPROVAL_AMOUNT_LIMIT (61) | EXCEEDS_APPROVAL_AMOUNT_LIMIT (61) | |
| $111.11 | EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT (65) | EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT (65, card-present only) | |
| $222.22 | RESTRICTED_LOCATION (62) | RESTRICTED_LOCATION (62) | |
| $333.33 | AUTHENTICATION_REQUIRED (1A) | AUTHENTICATION_REQUIRED (65, card-not-present only) | |
Retry guidance follows the response code actually returned, so it can differ by network on the same amount.
Card data checks run before the amount lookup. If you combine a decline amount with an incorrect CVV, postal code, or expiration date, the response reflects the card data failure, not the amount. See Authorization card data declines.
$111.11 and $333.33 both emit response code 65On Mastercard, the platform resolves 65 by card presence, not by amount:
- Card-present decodes to
EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT. - Card-not-present decodes to
AUTHENTICATION_REQUIRED.
A transaction is card-present only when it carries track 1, track 2, or ICC data, or a device-read PAN entry mode (magnetic stripe, chip, contactless, or chip fallback). Keyed and e-commerce transactions are card-not-present, so a typical API call returns AUTHENTICATION_REQUIRED for both amounts. To reach EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT, send $111.11 with card-present data.
Visa uses two distinct codes (65 and 1A), so both Visa amounts return the code shown regardless of card presence.
The Visa and Mastercard simulators produce only the response codes listed above.
Reserved amounts
Highnote reserves amounts made of one repeated digit, such as $444.44 or $555.55, for current and future simulations. The repeated-digit amounts in the table above, such as $1.11 and $22.22, return the documented responses. Any other repeated-digit amount can return an undocumented decline or behave differently by card network or payment type, and that behavior can change as simulations are added. Do not use one to test an approval or to assert a specific response.
Authorization card data declines
AVS declines always return DO_NOT_HONOR with result codes populated in separate response fields. RE_ENTER_TRANSACTION is not returned for AVS failures.
To simulate a decline by incorrect card data, send a past-dated expiration date, the wrong CVV, or the wrong postal code (for AVS declines) with the test PANs above. The platform response depends on the card network and transaction (txn) type.
Visa
| Scenario | Response Code | Details |
|---|---|---|
| Past-dated expiration date | DO_NOT_HONOR | Returns the 05 response code. Visa does not return EXPIRED_CARD for a card whose expiration date has passed. |
| Omitted expiration date | APPROVED | Visa accepts a missing expiration date and moves on to the CVV, postal code, and amount checks. |
| Incorrect CVV | BAD_CVV2 | Returns the N7 response code. |
| Incorrect postal code (non-verification) | DO_NOT_HONOR | Returns the 05 response code with postalCode set to NOT_MATCHED. |
| Incorrect street, correct postal code | APPROVED | Returns addressCode set to NOT_MATCHED. A street mismatch alone does not trigger a decline. Visa compares only the first five digits in the street line. |
| Incorrect postal code (verification txn) | APPROVED | AVS result codes are still returned, but an incorrect postal code does not trigger a decline. |
Mastercard
| Scenario | Response Code | Details |
|---|---|---|
| Past-dated expiration date | EXPIRED_CARD | Returns the 54 response code. |
| Omitted expiration date | EXPIRED_CARD | Returns the 54 response code. Mastercard requires the expiration date and declines when it is absent. |
| Incorrect CVV | DO_NOT_HONOR | Returns the 05 response code with securityCode set to NOT_MATCHED. |
| Incorrect postal code | DO_NOT_HONOR | Returns the 05 response code with postalCode set to NOT_MATCHED. Applies to verification transactions too. |
| Incorrect street, correct postal code | APPROVED | Returns addressCode set to NOT_MATCHED. A street mismatch alone does not trigger a decline, on any transaction type. |
EXPIRED_CARD on VisaTwo expiration-date behaviors differ from what the rest of this page would lead you to expect:
- A past-dated card returns
DO_NOT_HONORon Visa, notEXPIRED_CARD. The$4.44decline amount does returnEXPIRED_CARDon Visa, so the two ways of simulating an expired card produce different response codes on the same network. Mastercard returnsEXPIRED_CARDfor both. - Omitting the expiration date approves on Visa and declines on Mastercard. Send the field on both networks.
Expiration-date checks run before the CVV and postal code checks, and all three run before the amount lookup. On a $0 verification, the street-number lookup runs after them.
Visa returns APPROVED for a verification transaction with an incorrect postal code, while Mastercard returns DO_NOT_HONOR. Both networks approve a verification when only the street is wrong. Test both networks to ensure your integration handles both responses.
Verification declines
A verification (verify a payment card or verify a payment method token) is a $0 transaction, so the decline amounts cannot steer it.
To simulate a declined verification, send a billing street address of the form <number> Decline Street.
The simulator looks up the number in the decline amounts table as if it were the amount in cents: 444 Decline Street returns the same response as $4.44.
| Billing street address | Same as amount | Visa returns | Mastercard returns |
|---|---|---|---|
111 Decline Street | $1.11 | DO_NOT_HONOR (05) | DO_NOT_HONOR (05) |
222 Decline Street | $2.22 | INVALID_CARD_NUMBER (14) | INVALID_CARD_NUMBER (14) |
333 Decline Street | $3.33 | INSUFFICIENT_FUNDS (51) | INSUFFICIENT_FUNDS (51) |
444 Decline Street | $4.44 | EXPIRED_CARD (54) | EXPIRED_CARD (54) |
667 Decline Street | $6.67 | BAD_CVV2 (N7) | DO_NOT_HONOR (63) |
777 Decline Street | $7.77 | UNACTIVATED_CARD (78) | UNACTIVATED_CARD (72) |
888 Decline Street | $8.88 | UNACTIVATED_CARD (78) | RESTRICTED_LOCATION (62) |
999 Decline Street | $9.99 | CLOSED_ACCOUNT (46) | CLOSED_ACCOUNT (46) |
1111 Decline Street | $11.11 | EXPIRED_CARD (54) | INVALID_AUTHORIZATION_EXPIRATION (84) |
2222 Decline Street | $22.22 | BLOCKED_CARD (9G) | RESTRICTED_LOCATION (62) |
3333 Decline Street | $33.33 | TRANSACTION_NOT_PERMITTED (57) | TRANSACTION_NOT_PERMITTED (57) |
4444 Decline Street | $44.44 | RE_ENTER_TRANSACTION (19) | DO_NOT_HONOR (63) |
5555 Decline Street | $55.55 | CLOSED_ACCOUNT (46) | CLOSED_ACCOUNT (46) |
6666 Decline Street | $66.66 | UNACTIVATED_CARD (78) | TRANSACTION_NOT_PERMITTED (57) |
7777 Decline Street | $77.77 | INVALID_MERCHANT (03) | INVALID_MERCHANT (03) |
8888 Decline Street | $88.88 | INVALID_TRANSACTION (12) | INVALID_TRANSACTION (12) |
9999 Decline Street | $99.99 | EXCEEDS_APPROVAL_AMOUNT_LIMIT (61) | EXCEEDS_APPROVAL_AMOUNT_LIMIT (61) |
11111 Decline Street | $111.11 | EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT (65) | AUTHENTICATION_REQUIRED (65) |
22222 Decline Street | $222.22 | RESTRICTED_LOCATION (62) | RESTRICTED_LOCATION (62) |
33333 Decline Street | $333.33 | AUTHENTICATION_REQUIRED (1A) | AUTHENTICATION_REQUIRED (65) |
A verification sent through the API is card-not-present, so Mastercard's 65 decodes to AUTHENTICATION_REQUIRED for both 11111 Decline Street and 33333 Decline Street.
Follow these rules:
- Only a $0 verification reads the street number. An authorization, charge, or refund follows its amount and ignores the address.
- Send the test card's real postal code and security code. A wrong security code declines before the street number is read, on both networks. On Mastercard, a wrong postal code also declines first, as
DO_NOT_HONOR. - Match the format exactly. The address must be a number followed by
Decline Street, in any case.444 Decline St,444 Decline Street North,444B Decline Street, andDecline Street 444do not trigger a decline. - Use a number from the table. A number not in the table, such as
12 Decline Street, approves. - Any other street approves. An address that is not on Decline Street never triggers a verification decline.
Mastercard limits the street line to 20 characters. 33333 Decline Street is exactly 20 characters.
Simulate refunds
Refunds are submitted against the original payment transaction (the first authorization), not against individual captures. The total captured amount is the refund limit, regardless of how many captures were made. Multiple partial refunds are supported as long as the total refunded amount does not exceed the total captured amount.
Use the refundPaymentTransaction mutation with the original paymentTransactionId to issue a refund. The response returns a PaymentCreditTransaction with an originatedPaymentTransactionId that references the original payment.
There are no dedicated refund event types. Instead, refund outcomes use authorization events:
| Refund outcome | Event |
|---|---|
| Approved | CardPaymentAuthorizedEvent |
| Declined | CardPaymentAuthorizationDeclinedEvent |
Refund approvals
To simulate an approved refund, use any amount that is not in the authorization declines table, is not a reserved amount, and does not exceed the captured amount of the original transaction.
Refund declines
To simulate a declined refund, use one of the decline amounts from the authorization declines table. For example, a refund amount of $1.11 triggers a DO_NOT_HONOR decline.
To simulate the issuer accepting an acquiring dispute, see Simulate Disputes.