Testing Tools

1. Sandbox Basics

Use the sandbox to simulate payments without real transactions.

Base URL (Sandbox):

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 (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)

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

Get Payment by ID

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

💡 Tip: For 3-D Secure enrolled cards, expect a challenge/redirect flow.

4. Webhook Verification Quick-Start

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

Header:

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)

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, PENDING, AUTHORIZED, CANCELLED, DECLINED, COMPLETED

Capture/Void rules:

• Only AUTHORIZED payments can be captured or voided.

Filtering Examples:

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