# Testing Tools

### **1. Sandbox Basics**

> Use the sandbox to simulate payments without real transactions.

**Base URL (Sandbox):**

```json
https://engine-sandbox.convergegate.com
```

**Success Limits (Sandbox Rules):**

* **Deposits:** Amount **< 10,000,000**
* **Withdrawals/Refunds:** Amount **≤ 10,000**

**Authentication Methods in Use:**

* **BearerAuth** — for API requests
* **SignatureAuth** — for webhook verification\
  \&#xNAN;*(HMAC-SHA256 over raw JSON body, using your Shop Signing Key, header: `Signature`)*

### **2. Test Cards**

| Card Number         | 3-D Secure | Result                 |
| ------------------- | ---------- | ---------------------- |
| 4000 0000 0000 0002 | Yes        | Success Authorization  |
| 4242 4242 4242 4242 | Yes        | Declined Authorization |
| 4000 0000 0000 0408 | No         | Success Authorization  |
| 4000 0000 0000 0416 | No         | Declined Authorization |

### **3. Ready-to-Use Request Templates**

Below are minimal examples for the most common actions. Replace placeholders (`<...>`) with real values.

**Create Payment – Card (Deposit)**

```json
{
  "referenceId": "test-ref-001",
  "paymentType": "DEPOSIT",
  "amount": 500,
  "currency": "USD",
  "paymentMethod": "BASIC_CARD",
  "description": "Test Card Deposit"
}
```

**Get Payment by ID**

```bash
GET /api/v1/payments/{paymentId}
Authorization: Bearer <your_token>
```

{% hint style="info" %}
💡 **Tip:** For 3-D Secure enrolled cards, expect a challenge/redirect flow.
{% endhint %}

### **4. Webhook Verification Quick-Start**

When a payment is finalized, a webhook is sent to your configured URL.

**Header:**

```markup
Signature: <HMAC_SHA256_value>
```

**Secret:** Shop Signing Key.

**Important:**

> The `Signature` header will only be included **if a Signing Key is generated for your shop**.\
> If missing, create the Signing Key in your merchant configuration.

**Example Verification (Node.js)**

```javascript
const crypto = require('crypto');

function verifySignature(rawBody, signature, signingKey) {
  const computed = crypto
    .createHmac('sha256', signingKey)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(computed));
}
```

### **5. Negative Testing Checklist**

* Test **amount boundaries** (just below/above limits).
* Send **invalid currency codes**.
* Remove **required fields** like `paymentType` or `currency`.
* Use unsupported `paymentMethod` to confirm error handling.

***

### **6. Response & State Tips**

**Common `state` values:**

* [`CHECKOUT`](#user-content-fn-1)[^1], [`PENDING`](#user-content-fn-2)[^2], [`AUTHORIZED`](#user-content-fn-3)[^3], [`CANCELLED`](#user-content-fn-4)[^4], [`DECLINED`](#user-content-fn-5)[^5], [`COMPLETED`](#user-content-fn-6)[^6]

**Capture/Void rules:**

* Only `AUTHORIZED` payments can be **captured** or **voided**.

**Filtering Examples:**

```bash
curl -X GET "$baseUrl/api/v1/payments?created.gte=2025-08-01T00:00:00Z" \
  -H "Authorization: Bearer $bearerToken"
```

***

### **7. BLIK Test Codes**

| Blik Code       | Result             |
| --------------- | ------------------ |
| 777000 - 777999 | Emulate Success    |
| 000000 - 776999 | Emulate Fail/Retry |
| 778000 - 999999 | Emulate Fail/Retry |

[^1]: The user is expected to be redirected to the payment page to provide payment details.

[^2]: The payment provider API is being called, and the transaction is awaiting further processing.

[^3]: A two-phase deposit state where the funds are placed on hold.

[^4]: The transaction was canceled before completion.

[^5]: The transaction was declined by the provider or the issuing bank.

[^6]: The transaction was successfully processed and finalized.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.convergegate.com/v1/payments/testing-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.