Sandbox

Description

The Sandbox environment provides a safe place for users to thoroughly test calls to the Banking API, focusing on the transaction methods. Its main purpose is to allow developers to experiment with the API, simulate real-world scenarios, quickly generate demos and verify their client applications at no cost.

Key Objectives

  1. Testing environment : The sandbox space is designed to be a real-world testing environment that mirrors the real API but avoids scraping the source website, allowing users to validate their integration with the banking API with confidence.
  2. Cost Efficiency : By using the sandbox, users can avoid any unexpected costs associated with live API calls, ensuring their testing remains cost-effective.
  3. Realistic Simulations : Enables the generation of realistic yet synthetic data that emulates actual API responses, including both successful and failed results. The same simulated data can be obtained multiple times by using a special header in the request.

The Sandbox space is enabled for a selected subset of endpoints. The list of available services will be published soon

Special Headers

To configure a sandbox call effectively, you need to include specific headers in your request that are tailored to the sandbox environment:

  • x-demo-type : Use this header to define the type of response you want, according to the following values
    • demo_ok : This value produces a Code 200 response with "Status": "OK" . This simulates a successful API call.
    • demo_error : This value will result in a Code 400 response with JSON in "Status": "ERROR" and a random ErrorCode . This simulates a request that encounters an error.
  • x-demo-items (optional): This header allows you to specify the number of transactions you wish to receive as part of the API response. You can set the value between 0 and 100, depending on your testing needs.
  • x-demo-seed (optional): If you provide a seed value for this header, it will be used as the source for generating fake data. Reusing the same seed value will consistently generate the same set of transactions. If you omit this header, your client identifier (managed internally by Khipu) will be used as the default seed.
  • x-demo-sleep (optional): This header allows you to specify the number of seconds for which the API call should deliberately delay its response. This can be useful when simulating scenarios with long processing times or services that are known to be time consuming. The maximum sleep time is 60 seconds. If you don't set this header, the response will be generated immediately.

By using these headers effectively, you can control the behavior of the sandbox environment and tailor your testing to specific use cases.

Result

The API response from the Sandbox environment has the same structure as a normal response, but can be identified by the AdditionalInformation element, which indicates the simulated nature of the data with the text SANDBOX_GENERATED_RESPONSE. See next section for examples.

Examples

Here's an example of how to make a sandboxed call using curl to get an OK status:

Copy
Copied
curl -X POST 'https://api.khipu.com/v1/cl/banking/personal/<BANK_TRANSACTIONS_ENDPOINT>' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'x-demo-type: demo_ok' \
  -H 'x-demo-items: 4' \
  -H 'x-demo-seed: test_seed' \
  --data-raw '{
    "RequestData": {
      "AccountCredential": {
        "Username": "<USERNAME>",
        "Password": "<PASSWORD>"
      },
      "AccountNumber": "0000"
    }
  }'

Response:

Copy
Copied
{
    "OperationId": "d9d82287-96f3-498e-8632-a2c8fc7c8674",
    "Status": "OK",
    "Data": {
        "Transaction": [
            {
                "AccountId": "2932798040",
                "BookingDateTime": "2023-09-06T00:00:00-0300",
                "CreditDebitIndicator": "Debit",
                "Status": "Booked",
                "TransactionInformation": "Traspaso a Victoria Sonia Valenzuela Riquelme",
                "Amount": {
                    "Amount": 837,
                    "Currency": "CLP"
                },
                "BankTransactionCode": {
                    "Code": "ICDT",
                    "SubCode": "DMCT"
                },
                "DebtorAccount": {
                    "Identification": "2932798040",
                    "Name": "Juan Fernández"
                },
                "DebtorAgent": {
                    "Name": "Banco Falabella"
                },
                "SupplementaryData": {
                    "DebtorId": "9.123.845-4"
                }
            },
            {
                "AccountId": "2932798040",
                "BookingDateTime": "2023-06-28T00:00:00-0400",
                "CreditDebitIndicator": "Debit",
                "Status": "Booked",
                "TransactionInformation": "Transferencia a Carlos Faúndez Lara",
                "Amount": {
                    "Amount": 949,
                    "Currency": "CLP"
                },
                "BankTransactionCode": {
                    "Code": "ICDT",
                    "SubCode": "DMCT"
                },
                "DebtorAccount": {
                    "Identification": "2932798040",
                    "Name": "Juan Fernández"
                },
                "DebtorAgent": {
                    "Name": "Banco Falabella"
                },
                "SupplementaryData": {
                    "DebtorId": "9.123.845-4"
                }
            },
            {
                "AccountId": "2932798040",
                "BookingDateTime": "2023-07-29T00:00:00-0400",
                "CreditDebitIndicator": "Debit",
                "Status": "Booked",
                "TransactionInformation": "Pago de servicios",
                "Amount": {
                    "Amount": 26,
                    "Currency": "CLP"
                },
                "BankTransactionCode": {
                    "Code": "ICDT",
                    "SubCode": "DMCT"
                },
                "DebtorAccount": {
                    "Identification": "2932798040",
                    "Name": "Juan Fernández"
                },
                "DebtorAgent": {
                    "Name": "Banco Falabella"
                },
                "SupplementaryData": {
                    "DebtorId": "9.123.845-4"
                }
            },
            {
                "AccountId": "2932798040",
                "BookingDateTime": "2023-02-03T00:00:00-0300",
                "CreditDebitIndicator": "Debit",
                "Status": "Booked",
                "TransactionInformation": "Transferencia a Matías Francisco Montenegro Varas",
                "Amount": {
                    "Amount": 713,
                    "Currency": "CLP"
                },
                "BankTransactionCode": {
                    "Code": "ICDT",
                    "SubCode": "DMCT"
                },
                "DebtorAccount": {
                    "Identification": "2932798040",
                    "Name": "Juan Fernández"
                },
                "DebtorAgent": {
                    "Name": "Banco Falabella"
                },
                "SupplementaryData": {
                    "DebtorId": "9.123.845-4"
                }
            }
        ]
    },
    "AdditionalInformation": "SANDBOX_GENERATED_RESPONSE",
    "Error": null,
    "LifeSpan": null
}

Example simulating an incorrect response:

Copy
Copied
curl -X POST 'https://api.khipu.com/v1/cl/banking/personal/<BANK_TRANSACTIONS_ENDPOINT>' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'x-demo-type: demo_error' \
  --data-raw '{
    "RequestData": {
      "AccountCredential": {
        "Username": "<USERNAME>",
        "Password": "<PASSWORD>"
      },
      "AccountNumber": "0000"
    }
  }'

Response:

Copy
Copied
{
    "OperationId": "64996c85-c735-4d81-a9da-a0df8cae74bd",
    "Status": "ERROR",
    "Data": null,
    "AdditionalInformation": "SANDBOX_GENERATED_ERROR",
    "Error": {
        "Code": "E301",
        "Type": "DO_NOT_RETRY",
        "Description": "No existen registros para el periodo seleccionado."
    },
    "LifeSpan": null
}

Remember to replace YOUR_API_KEY with your actual key, and also use the same RequestData structure as mentioned in the method documentation. Note that the payload is not validated, so you don't need to use real credentials.

One final comment: If you try to call a method that is not yet sandboxed, you will get a response like this:

Copy
Copied
{
    "OperationId": "160b5061-f6b3-4f4f-803f-b555e8096d3b",
    "Status": "OK",
    "Data": {
        "PostProcessorInfo": {
            "Message": "Demo response is not available for this endpoint yet."
        }
    },
    "AdditionalInformation": "SANDBOX_GENERATED_RESPONSE",
    "Error": null,
    "LifeSpan": null
}