> For the complete documentation index, see [llms.txt](https://developer.convergegate.com/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.convergegate.com/v1/payments/testing-tools.md).

# 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.