H2H Provider Integration

Host-to-Host callback endpoints for payment providers integrating with VeltoraPay as a source.

Overview

H2H (Host-to-Host) integration is used when VeltoraPay connects to external payment providers (like KolayHavale, FanatikPay, etc.) as a source. The provider sends callbacks to VeltoraPay when deposit or withdraw transactions are processed.

Provider Types

VeltoraPay Callback Format

Used when connecting VeltoraPay instances in a cascade topology.

Deposit Callback

POST/api/source-callbacks/{sourceSubName}/deposit

{
  "event": "deposit.status_changed",
  "token": "c3d4e5f6-7890-abcd-ef12-345678901234",
  "clientToken": "TXN-001",
  "status": "matched",
  "amount": 1000.00,
  "senderName": "Ahmet Yilmaz",
  "iban": "TR12 0001 0012 3456 7890 1234 56",
  "accountHolder": "VeltoraPay A.S.",
  "bank": "Ziraat Bankasi",
  "source": "Source-1",
  "matchedAt": "2026-03-31T10:05:30Z",
  "timestamp": "2026-03-31T10:05:30Z"
}

Status Values

Withdraw Callback

POST/api/source-callbacks/{sourceSubName}/withdraw

{
  "event": "withdraw.status_changed",
  "token": "a1b2c3d4-5678-...",
  "clientToken": "WD-001",
  "status": "succeeded",
  "externalStatus": "Succeeded",
  "amount": 500.00,
  "recipientName": "Mehmet Demir",
  "recipientIban": "TR76 0006 2000 1234 5678 9012 34",
  "recipientBank": "Garanti BBVA",
  "source": "Pool",
  "timestamp": "2026-03-31T11:02:30Z"
}

Status Values

FanatikPay Callback

POST/api/source-callbacks/{sourceSubName}/fanatikpay

Handles both deposit and withdrawal callbacks via the type field.

{
  "reference_code": "FP-REF-123456",
  "site_transaction_id": "TXN-001",
  "site_user_id": "user-12345",
  "type": "deposit",
  "status": "approved",
  "amount": 500.00,
  "net_amount": 490.00,
  "commission": 10.00,
  "hash": "a1b2c3d4e5f6...SHA256_HASH",
  "created_at": "2026-03-31T10:00:00Z",
  "approved_at": "2026-03-31T10:05:30Z",
  "reject_reason": null
}

Fields

Hash Calculation

hash = SHA256(site_transaction_id + api_secret + site_user_id)

// Example:
input  = "TXN-001" + "your-api-secret" + "user-12345"
hash   = SHA256("TXN-001your-api-secretuser-12345")
       = "a1b2c3d4e5f6..."

KolayHavale Callback

POST/api/source-callbacks/{sourceSubName}/kolayhavale

Single endpoint for both deposits and withdrawals. VeltoraPay determines the type by matching the transactionhash against existing records.

{
  "transactionhash": "KH-TXN-HASH-123456",
  "username": "Ahmet Yilmaz",
  "userid": "user-12345",
  "status": "1",
  "amount": "500.00",
  "encryptedhash": "a1b2c3d4e5f6...SHA512_HASH"
}

Fields

Hash Calculation

The hash formula differs between deposits and withdrawals:

encryptedhash = SHA512(transactionhash + "_" + username + "_" + userid + "_" + amount + "_" + status)

// Example:
input = "KH-TXN-HASH-123456_Ahmet Yilmaz_user-12345_500.00_1"
hash  = SHA512(input)

encryptedhash = SHA512(transactionhash + "_" + username + "_" + userid + "_" + status)

// Note: amount is NOT included in withdraw hash
input = "KH-TXN-HASH-123456_Ahmet Yilmaz_user-12345_1"
hash  = SHA512(input)

Generic Provider

POST/api/source-callbacks/{sourceSubName}/generic

A no-code/low-code callback endpoint driven entirely by the ProviderDefinition.CallbackConfig JSON configuration. This allows integrating new providers without code changes.

Hash Verification Summary

Status Mapping

Deposit Status Mapping

Withdraw Status Mapping

Security

1. Hash Verification: All callbacks with hash fields are verified before processing. Invalid hashes are rejected with 403 Forbidden.
2. IP Whitelisting: Source callbacks can be restricted to specific provider IPs via the source configuration.
3. Idempotency: Duplicate callbacks for already-finalized transactions are safely ignored and return 200 OK.
4. Token Matching: Callbacks are matched against existing transaction records by externalToken or clientToken. Unmatched callbacks are logged and rejected.
5. HTTPS Only: All callback URLs must use HTTPS in production.