Sandbox

Description

The Sandbox environment serves as a safe space for users to thoroughly test calls to the Banking API, with a primary focus on the transaction methods. Its main purpose is to allow developers to experiment with the API, simulate real-world scenarios, generate demos quickly and verify their client applications without incurring any actual charges.

Key Objectives

Testing Environment : The Sandbox space is designed to be a real testing environment that mirrors the real API but avoids scraping the source website, thus allowing users to validate their integration with the banking API with confidence.
Cost-Efficiency : By using the Sandbox, users can prevent any unexpected costs associated with live API calls, ensuring their testing remains cost-effective.
Realistic Simulations : It enables the generation of realistic, yet synthetic data, emulating actual API responses, including both successful and erroneous outcomes. 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 in your request specific headers tailored to the Sandbox environment:

x-demo-type : Use this header to define the desired response type, according to the following values:
- demo_ok : This value produces a Code 200 response with "Status": "OK" . It simulates a successful API call.
- demo_error : Setting this value produces 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 requirements.
x-demo-seed (optional): If you provide a seed value for this header, it will be used as a 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 enables you to define the number of seconds for which the API call should intentionally delay its response. This can be beneficial when simulating scenarios that involve longer processing times, or services 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 utilizing 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 of a normal response, but can be identified by the AdditionalInformation element, that will indicate 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 to simulate an erroneous 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 respective method's documentation. Keep in mind that the payload will not be validated, that means that you don't have to use real credentials.

Final comment: If you try to invoke a method that is not yet sandboxed, you will get a response like the following:

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
}