Testing Cards

Testing your card implementation is essential to ensuring the successful rollout of any new card program. While initial testing can be completed in the sandbox environment, it is highly recommended that production testing be performed to ensure that all elements of the card implementation are functioning as expected before launching your program with customers.

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

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.

1. Issue a physical card (Card object will be created, but a physical card will not be produced)
2. Issue a virtual card
   • Validate the presentation of card details in your UI
3. Use card simulations to create test cases that mimic those you expect to encounter in production
4. 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
5. 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
6. If utilizing card controls to restrict spending velocity, create auth-request card simulations that fall within and surpass these limitations
7. 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
8. 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.

1. Issue a physical card
   • Verify receipt of card
   • Verify the correct design of the card
2. Issue a virtual card
   • Validate the presentation of card details in your UI
3. Initiate payments using your card at several different merchants covering different scenarios, including
   • swipe
   • dip (insert card)
   • PIN debit
   • online transaction
   • mail or phone
4. If utilizing card controls to restrict spending by merchant category code, perform transactions at merchants using these codes and confirm the expected behavior
5. If utilizing card controls to restrict spending velocity, perform transactions within the limits applied and confirm the expected behavior
6. Verify withdrawal of funds from the linked account (note card transactions often take several days to clear and funds to be withdrawn)
7. 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
8. 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.