HomeDocumentationAPI Reference
Documentation

Stash

Suggest Edits

The Reach Stash allows the temporary storage of client data for use in subsequent Checkout API requests.

Stash typically stores cardholder data sent from the customer's browser. It allows other Checkout API requests to originate from your store's servers without passing through cardholder data.

For more information, see Card Details and the Order API Guide.

Stash workflow

The following image shows the Stash workflow.

Stash workflow

Stash workflow

StashId

Developers can streamline the transaction process by utilizing the Stash ID. This unique identifier can represent merchant-specific data points such as cart ID, order ID, or session ID. The Stash workflow not only enhances security by keeping sensitive data off the merchant's servers but also adheres to best practices and regulatory standards for data protection.:

https://stash.rch.how/{MerchantId}/{StashId}

i.e. https://stash.rch.how/2a144a21-066a-42fe-a553-736a777e39e2/RccAl5JE6D3a1RLJdrJ5XbbJJNfXSldV2K2CXPCSBtRnuC0bRLNO65Lp

https://stash.gointerpay.net/{MerchantId}/{StashId}

Sample Stash request

Valid request with no warnings

When making a valid request with no warnings using the Stash API, you ensure that the card data provided is correctly formatted and adheres to the expected criteria set by the API.

Here's a breakdown of how this request works:

Endpoint and method:

    • You use a POST request to a specific endpoint, including your MerchantId and a StashId.
    • The endpoint looks something like this: https://stash.rch.how/{MerchantId}/{StashId}, where https://stash.rch.how/ is the base URL for the API.

  2. Payload:

    • The data you send in the request must contain:
      • DeviceFingerprint: A unique identifier for the devices used during checkout (for fraud detection).
      • Card Information: This includes:
        • Name: The cardholder's name.
        • Number: The card number (must pass validation).
        • VerificationCode: This is the CVV.
        • Expiry: This includes the expiry year and month.
    • The payload in your example is prepared with a URL-encoded format, which looks like this:
    $ curl -d "DeviceFingerprint=4e0298ed-e139-4325-b5b5-258abe470eba&card=%7B%22Name%22%3A%22Clark%20Kent2%22%2C%22Number%22%3A%224242424242424242%22%2C%22VerificationCode%22%3A%22281%22%2C%22Expiry%22%3A%7B%22Year%22%3A%222030%22%2C%22Month%22%3A%2203%22%7D%7D"

  3. Expected response:

    • When the request is valid and successfully processed, you will receive a JSON response with the following keys:
      • StashId: This confirms the identifier you used to store the card information.
      • Last4: The last four digits of the card (this confirms that the card number was valid).
      • Warnings: In a successful case with valid data, this array will be empty, indicating no issues.

Here's a sample response:

{"StashId":"RccAl5JE6D3a1RLJdrJ5XbbJJNfXSldV2K2CXPCSBtRnuC0bRLNO65Lp","Last4":"4242","Warnings":[]}

In summary, a valid request with no warnings is a successful call in which all the card details provided are correct and match the expected formats. It allows you to temporarily store sensitive card data in compliance with security standards, enabling future transactions without unnecessary risk by keeping cardholder data off your servers. Always ensure that sensitive data is protected and handled according to best practices and regulations.

Valid request with invalid card number

In this scenario, you make a valid request to the Stash API but encounter an invalid card number. It’s important to understand how the API processes the data and the implications of such a request.

Let's break it down:

  1. Endpoint and method:

    • You’re still using a POST request directed to the Stash API, formatted similarly to:
    https://stash.rch.how/{MerchantId}/{StashId}
    • Ensure that https://stash.rch.how/, MerchantId, and StashId are correctly specified.

  2. Payload:

    • The request payload contains the necessary fields like DeviceFingerprint and card information.
    • Here’s how a request with an invalid card number might look in URL-encoded format:
    "DeviceFingerprint=4e0298ed-e139-4325-b5b5-258abe470eba&card=%7B%22Name%22%3A%22Clark%20Kent2%22%2C%22Number%22%3A%224242424242424243%22%2C%22VerificationCode%22%3A%22281%22%2C%22Expiry%22%3A%7B%22Year%22%3A%222030%22%2C%22Month%22%3A%2203%22%7D%7D"
    • Here, 224242424242424243 is meant to represent an invalid card number—this could mean it's incorrectly formatted, too short, or simply a number that does not correspond to any existing card.

  3. Expected response:

    • When the API processes this request, it performs validation checks on the card number. Since the card number is invalid, you will receive a response indicating this issue.
    • A typical JSON response for a request with an invalid card number looks like this:
    {
  "StashId": "RccAl5JE6D3a1RLJdrJ5XbbJJNfXSldV2K2CXPCSBtRnuC0bRLNO65Lp",
  "Last4": "4243",
  "Warnings": ["CardNumberInvalid"]
}

Key points in the response:

  • StashId: The identifier you used remains constant, which helps in tracking the request lifecycle.
  • Last4: This field will typically return the last four digits of the card number you provided, even if the number itself was invalid.
  • Warnings: The Warnings array will include a message detailing the reason for failure. In this case, it states "CardNumberInvalid", signaling that the card number provided does not meet the criteria established by the API.

In summary, validating card numbers before sending them to the API is essential. Such validation can include checking the format and length, and using algorithms to ensure basic validity. It helps reduce unnecessary API calls and provides immediate feedback on card errors. Always ensure you have robust error handling to address such issues gracefully..

Valid request with invalid card number, invalid expiry month, and invalid validation code / CVV

In this scenario, you make a valid request to the Stash API but encounter an invalid card number. It’s important to understand how the API processes the data and what the implications of such a request are. Let's break it down:

  1. Endpoint and method:

    • You’re still using a POST request directed to the Stash API, formatted similarly to: 
      https://stash.rch.how/{MerchantId}/{StashId}
    • Ensure that https://stash.rch.how/, MerchantId, and StashId are correctly specified.

  2. Payload:

    • The request payload contains the necessary fields like DeviceFingerprint and card information.
    • Here’s how a request with an invalid card number might look in URL-encoded format:
    "DeviceFingerprint=4e0298ed-e139-4325-b5b5-258abe470eba&card=%7B%22Name%22%3A%22Clark%20Kent2%22%2C%22Number%22%3A%224242424242424243%22%2C%22VerificationCode%22%3A%22281%22%2C%22Expiry%22%3A%7B%22Year%22%3A%222030%22%2C%22Month%22%3A%2203%22%7D%7D"
    • Here, 224242424242424243 is meant to represent an invalid card number—this could mean it's incorrectly formatted, too short, or simply a number that does not correspond to any existing card.

  3. Expected response:

    • When the API processes this request, it performs validation checks on the card number. Since the card number is invalid, you will receive a response indicating this issue.
    • A typical JSON response for a request with an invalid card number looks like this:
    {
  "StashId": "RccAl5JE6D3a1RLJdrJ5XbbJJNfXSldV2K2CXPCSBtRnuC0bRLNO65Lp",
  "Last4": "4243",
  "Warnings": ["CardNumberInvalid"]
}

Key points in the response:

  • StashId: The identifier you used remains constant, which helps in tracking the request lifecycle.
  • Last4: This field will typically return the last four digits of the card number you provided, even if the number itself was invalid.
  • Warnings: The Warnings array will include a message detailing the reason for failure. In this case, it states "CardNumberInvalid", signaling that the card number provided does not meet the criteria established by the API.

In summary, if a developer encounters a valid request with an invalid card number, validating card numbers before sending them to the API is essential. Such validation can include checking the format and length, and possibly using algorithms like Luhn's algorithm to ensure basic validity. It helps reduce unnecessary API calls and enhances the overall user experience by providing immediate feedback on card errors. Always ensure you have robust error handling to address such issues gracefully.

$ curl -d "DeviceFingerprint=4e0298ed-e139-4325-b5b5-258abe470eba&card=%7B%22Name%22%3A%22Clark%20Kent2%22%2C%22Number%22%3A%224242424242424243%22%2C%22VerificationCode%22%3A%22281x%22%2C%22Expiry%22%3A%7B%22Year%22%3A%222020%22%2C%22Month%22%3A%2214%22%7D%7D" https://stash.rch.how/2a144a21-066a-42fe-a553-736a777e39e2/RccAl5JE6D3a1RLJdrJ5XbbJJNfXSldV2K2CXPCSBtRnuC0bRLNO65Lp
 
{"StashId":"RccAl5JE6D3a1RLJdrJ5XbbJJNfXSldV2K2CXPCSBtRnuC0bRLNO65Lp","Last4":"4243","Warnings":["CardMonthInvalid","CardNumberInvalid","CardVerificationCodeInvalid"]}

Updated 9 days ago