Sandbox testing

The dLocal Sandbox is a self-contained, virtual testing environment that mimics the live dLocal production environment. It provides a shielded space where you can initiate and watch your application process the requests you make to the dLocal APIs without touching any live dLocal accounts.

When you initiate a transaction by using a sandbox account, dLocal creates a mock transaction that behaves exactly like a transaction in the live environment. All sandbox transactions are tracked on the Merchant Dashboard with the test mode on, and all production transactions are located under the live mode on (test mode off).

The testing process

Test your application by creating an account. You may use the Sandbox (Test mode on) and the Production environments from the same account and dashboard.

If you already have an account, it is not necessary to create another one.

1. Make sure you have your dLocal account.
2. Set the signature needed to authenticate all your requests securely.
3. Format your dLocal API requests using the test data from your account and run them against the Sandbox endpoint.
4. Review the responses and modify your application as necessary.
5. When your application is fully functional and free of bugs, go live by updating the API credentials and endpoint targets.

Make test calls

After you have your sandbox API credentials, you can make dLocal requests to the sandbox environment.
The endpoint for all sandbox API calls starts with https://sandbox.dlocal.com/.

When you decide to go live, you should change your endpoints to https://api.dlocal.com/.

Testing payments

You can test payments using the Create a Payment API method, just remember to use the https://sandbox.dlocal.com/payments endpoint.

In Sandbox, all Credit Card payments are automatically approved by default. If you want to test the response of all possible errors, you can do so with the following trick exclusive for sandbox:

• On the description body parameter of the Create a payment you can include the error code that you want the payment to result to.
• For example, description: “302” will result in the payment being rejected with the error: “Insufficient Amount”.
• You can check the full list of error codes available whenever you need.

Testing examples

General payment

Take the following payment request as an example:

Example request

curl -X POST \
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
    -H 'X-Login: sak223k2wdksdl2' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
    -d '{body}'
    https://sandbox.dlocal.com/payments

{
    "amount": 120.00,
    "currency" : "USD",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "[email protected]",
        "document" : "53033315550",
        "user_reference": "12345",
        "address": {
            "state"  : "Rio de Janeiro",
            "city" : "Volta Redonda",
            "zip_code" : "27275-595",
            "street" : "Servidao B-1",
            "number" : "1106"
        }
    },
    "card":{
        "token": "CV-124c18a5-874d-4982-89d7-b9c256e647b5",
    },
    "order_id": "657434343",
    "description": "Testing Sandbox",
    "notification_url": "http://merchant.com/notifications"
}

We'll use it as an example to show how you should perform tests in the Sandbox environment. Pay special attention to the description property, which will be very useful when testing the suggested scenarios:

1. Payment with credit card approved - PAID
2. Payment with credit card rejected - REJECTED
3. Testing DIRECT cash payments - Approve or expire

⚠️

Check the data

Make sure you are using the correct data for your own testing cases

Payment with credit card approved

As we mentioned earlier, you need to add the status code you want to test on the description body parameter of your request. In this case, we want to test status PAID, so we'll use code 200.

As you are testing cards, make sure you are correctly inputting CARD as the selected payment method.

Example

"payment_method_id" : "CARD",
"description": "200",

"status" : "PAID",
"status_code" : "200",
"status_detail" : "The payment was paid.",

The response you should expect for the specified properties in this test:
As you can see, the testing response is showing PAID as the payment status, and 200 as the status code.

Testing payment with credit card rejected

The same goes to test the REJECTED status, but with 300 as the input code:

Example

"description": "300",

"status" : "REJECTED",
"status_code" : "300",
"status_detail" : "The payment was rejected.",

As we mentioned earlier, you can include in description the error code that you want the payment to result to. For example, "302" will result in the payment being rejected with the error: "Insufficient Amount".

Testing DIRECT cash payments

Our DIRECT cash payment methods can be tested by either forcing an approval (PAID) or an expiration (REJECTED).

Example request

$ curl -X POST \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   https://sandbox.dlocal.com/sandbox-tools/payments

{
   "payment_id" : "PAY4334346343",
   "status": "PAID"
}

$ curl -X POST \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   https://sandbox.dlocal.com/sandbox-tools/payments

{
   "payment_id" : "PAY4334346343",
   "status": "REJECTED"
}

Responses

In both cases, if you receive a code 200, it means your PAID or REJECTED request is successful. Also this will trigger a notification with the new status.

If payment_id doesn’t exist, you will receive a 404 response:

{
 "code": 0,
 "status": "ERROR",
 "message": "404 {\"code\":4000,\"message\":\"Payment not found\"}"
}

If payment_id is not in PENDING status, you will receive a 400 response:

{
 "code": 5002,
 "message": "Payment D-4-fdb6fe34-de6c-4f66-8895-ef87a1918b29 has not status PENDING. Actual status: PAID"
}

Testing refund for cash and bank transfer

For cash and bank transfer refunds, you will get a PENDING status when calling the Create Refunds API.

To test other statuses you can use the below PATCH method to force a refund to update to another status (SUCCESS, REJECTED, or CANCELLED). Then you will be able to receive a refund notification.

Example request

curl --location --request PATCH 'https://sandbox.dlocal.com/sandbox-tools/refunds/update-status' \
--header 'X-Login: cvEiB0USPG' \
--header 'X-Trans-Key: BpbyjOkUIE' \
--header 'Content-Type: application/json' \
--data-raw '

{
    "id_refund": "R-462778-e60039e7-ed75-4cd5-ad47-fc7f05fa6347",
    "status": "SUCCESS" 
}'

curl --location --request PATCH 'https://sandbox.dlocal.com/sandbox-tools/refunds/update-status' \
--header 'X-Login: cvEiB0USPG' \
--header 'X-Trans-Key: BpbyjOkUIE' \
--header 'Content-Type: application/json' \
--data-raw '

{
    "id_refund": "R-462778-e60039e7-ed75-4cd5-ad47-fc7f05fa6347",
    "status": "REJECTED" 
}'

curl --location --request PATCH 'https://sandbox.dlocal.com/sandbox-tools/refunds/update-status' \
--header 'X-Login: cvEiB0USPG' \
--header 'X-Trans-Key: BpbyjOkUIE' \
--header 'Content-Type: application/json' \
--data-raw '

{
    "id_refund": "R-462778-e60039e7-ed75-4cd5-ad47-fc7f05fa6347",
    "status": "CANCELLED" 
}'

Responses

You will get an HTTP code 200 with the below response which means the refund status is updated, and it will trigger a notification with the new status.

{
    "id": "REF-462778-935f3976-2436-4780-9b54-6c1a1b90ddbf",
    "payment_id": "R-462778-e60039e7-ed75-4cd5-ad47-fc7f05fa6347",
    "refund_id": 21549891,
    "id_boleto": 121805245,
    "status": "SUCCESS",
    "status_code": "200",
    "status_detail": "The refund was paid."
}

If the refund is not in pending status, you will get the below response with HTTP code 400:

{
    "code": 5002,
    "message": "Refund REF-462778-935f3976-2436-4780-9b54-6c1a1b90ddbf has not status PENDING. Actual status: SUCCESS"
}

Configure your integration