Testing Cards

Testing in Sandbox

The sandbox environment contains a simulations feature, which allows you to imitate the functionality of an issued card. The fields of the Card Simulation request body can be configured to allow for the testing of various scenarios which might be encountered in your production card program.

Card Simulation Types

Simulation type	Card event message type	Explanation
card_event.auth_capture	auth-capture	Notification that a previous authorization has been captured (related holds are released and funds moved as a result of this request).
card_event.auth_clear_request	auth-clear-request	Request to authorize and capture funds in one message (funds are moved immediately).
card_event.auth_request	auth-request	Request to authorize spending with card (if approved, this places a hold on funds). Note that this simulation will have any applicable card controls run against the auth request.
card_event.auth_reversal	auth-reversal	Notification that a previous authorization has been reversed.
card_event.refund	refund	Refunds a previously completed transaction

Authorization Request and Capture

A typical flow for a card simulation is creating a mock swipe for an issued card at a specific merchant. The following calls outline simulating a purchase at a grocery store.

Create an auth request simulating the initial swipe of the card at the point of sale system. This auth request will be routed through the mocked card network and verified against any card controls that have been set up.

$ curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/simulation \
    -H 'Content-Type: application/json' \
    -d '{"type": "card_event.auth_request",
         "simulation": {
             "card_id": "card_104",
             "amount": "25.10",
             "merchant": {
                 "mcc": "5411",
                 "mid": "4445025949032",
                 "name": "KROGER #10626",
                 "address": {"city": "LAS VEGAS",
                            "state": "NV",
                            "country": "USA",
                            "postal_code": "88901"}}}}'

A hold will have been created for the amount of the requested purchase.

To capture and approve this auth request, the trace_id for the auth_request is required. You can retrieve this from either the card_event generated upon receipt of the auth request or the transaction endpoint.

Here it is located via the account transaction endpoint via this request.

curl -u "$API_KEY_ID:$API_KEY_VALUE" https://api.treasuryprime.com/account/acct_1029384756/transaction \

Here’s the response we would expect where the hold generated in response to the auth request is the most recent transaction.

{
  "data": [
    {
      "check_id": null,
      "billpay_payment_id": null,
      "ach_id": null,
      "amount": "25.10",
      "balance": "256147.27",
      "book_id": null,
      "check_id": null,
      "check_number": null,
      "date": "2021-10-26",
      "extended_timestamp": "2021-10-26T12:02:03Z",
      "extended_timestamp_precise": "2021-10-26T12:02:03.329Z",
      "desc": "KROGER #10626 4445025949032 - AUTHORIZATION REQUEST",
      "fingerprint": "ttx_11gqg7am69g1s9",
      "id": "ttx_11gqg7am69g1s9",
      "summary": null,
      "type": "hold",
      "trace_id": '23f2b0e82c684638a5993f53e920cdab',
      "wire": null,
      "wire_id": null,
      "related_transfer_ids": []
    },
    ...
  ]
}

Now that the trace_id has been found, an auth capture request can be created, simulating the verification of the auth request. The trace_id is supplied as the external_id for our simulation call. The external_id links the initial auth request and the subsequent auth capture. The auth capture will release the hold and debit the funds from the account.

curl -u $API_KEY_ID:$API_KEY_VALUE https://api.treasuryprime.com/simulation \
    -H 'Content-Type: application/json' \
    -d '{"type": "card_event.auth_capture",
         "simulation": {
             "external_id": "23f2b0e82c684638a5993f53e920cdab"
             "card_id": "card_104",
             "amount": "25.10",
             "merchant": {
                 "mcc": "5411",
                 "mid": "4445025949032",
                 "name": "KROGER #10626",
                 "address": {"city": "LAS VEGAS",
                            "state": "NV",
                            "country": "USA",
                            "postal_code": "88901"}}}}'

Card Controls

If utilizing Card Controls to block specific merchant category codes, you can utilize the mcc value of the Merchant sub-object in the Card Simulation request body to verify that the specified categories are, in-fact, blocked.

Example

curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/simulation \
    -H 'Content-Type: application/json' \
    -d '{
            "type": "card_event.auth_request",
            "simulation": {
                "card_id": "card_104",
                "amount": "25.10",
                "merchant": {
                    "mcc": "5411",
                    "mid": "4445025949032",
                    "name": "KROGER #10626",
                    "address": {
                        "city": "LAS VEGAS",
                        "state": "NV",
                        "country": "USA",
                        "postal_code": "88901"
                   }
                }
            }
        }'

Sandbox Test Scenarios

While you can perform the majority of your initial card testing in the sandbox environment, including issuing cards, it should be noted that no physical cards will be sent. The steps below represent generally recommended testing scenarios, but additional testing will likely be required based on your specific use cases and program requirements.

The steps below represent common scenarios. It is best practice to test thoroughly test these in the sandbox before launching your card program in a production environment.

Issue a physical card (Card object will be created, but a physical card will not be produced)
Issue a virtual card
- Validate the presentation of card details in your UI
Use card simulations to create test cases that mimic those you expect to encounter in production
Take note of the Transactions which are created on the account in response to various card events and ensure proper coverage within your application logic
If utilizing card controls to restrict spending by merchant category code, create card simulations that use the mcc property of the Merchant sub-object to mimic transactions at merchants in these categories
If utilizing card controls to restrict spending velocity, create auth-request card simulations that fall within and surpass these limitations
If using the Card Auth Loop Endpoint to decision card authorizations, test this functionality by
- Implementing the Card Auth Loop Endpoint and applying your decisioning logic
- Creating auth-request simulations to trigger the Card Auth Loop Endpoint
- Validating your logic for expected outcomes
Test common error scenarios
- Create auth-request card simulations on an unactivated, terminated, and suspended card
- Create auth-request card simulations with an amount greater than the available_balance on the account to simulate non-sufficient funds (NSF)

Testing in Production

Testing in production involves issuing real cards (virtual, physical, or both) and initiating transactions that mimic the most common scenarios you expect your users to take. The below recommendations may or may not apply based on your use cases and which features you are using, and are meant to serve as general guidelines, likely not representing a complete test coverage for your specific implementation.

Issue a physical card
- Verify receipt of card
- Verify the correct design of the card
Issue a virtual card
- Validate the presentation of card details in your UI
Initiate payments using your card at several different merchants covering different scenarios, including
- swipe
- dip (insert card)
- PIN debit
- online transaction
- mail or phone
If utilizing card controls to restrict spending by merchant category code, perform transactions at merchants using these codes and confirm the expected behavior
If utilizing card controls to restrict spending velocity, perform transactions within the limits applied and confirm the expected behavior
Verify withdrawal of funds from the linked account (note card transactions often take several days to clear and funds to be withdrawn)
If using the Card Auth Loop Endpoint to decision card authorizations, test this functionality by
- Implementing the Card Auth Loop Endpoint and applying your decisioning logic
- Initiate a card payment to trigger the Card Auth Loop Endpoint
- Validating your logic for expected outcomes
Test common error scenarios
- Initiate payment on an unactivated, terminated, and suspended card
- Initiate payment with an amount greater than the available_balance on the account
- Attempt an ATM withdrawal for an amount greater than the available_balance on the account
- Attempt an ATM withdrawal or PIN debit payment using an incorrect PIN number
- Initiate a transaction at an Automated Fuel Dispenser (AFD) and assess related card events and transactions.
  - Note: AFDs often initially issue an auth-request for a low value (such as $1) and then later submit an auth-capture for a much higher amount (the total fuel cost). This can lead to overdraft scenarios and is something you should consider if anticipating spend at these types of merchants.

Documentation

Accounts

Cards

Payments

Testing in Sandbox

Card Simulation Types

Authorization Request and Capture

Card Controls

Example

Sandbox Test Scenarios

Testing in Production

Documentation

Accounts

Cards

Payments

​Testing in Sandbox

​Card Simulation Types

​Authorization Request and Capture

​Card Controls

Example

​Sandbox Test Scenarios

​Testing in Production

Testing in Sandbox

Card Simulation Types

Authorization Request and Capture

Card Controls

Sandbox Test Scenarios

Testing in Production