PayShap Use Cases

PayShap is a South African real-time interbank low-value payment scheme operated through the South African Reserve Bank (SARB). Eclipse integrates with PayShap via Standard Bank (SBSA) as the sponsoring bank, using the ZA_SBSA_PAYSHAP gateway.

Eclipse supports the full PayShap workflow:

• Send — debit a wallet and push funds to a PayShap recipient using either their bank account number or their PayShap proxy ID (phone number or custom identifier)
• Receive — register a wallet as a PayShap-reachable destination by linking a proxy identifier to it, so other banks can resolve and credit it

Prerequisites:

• A valid JWT for API calls
• An active ZAR wallet funded with sufficient balance
• The following tenant config keys provisioned by the EFT onboarding team:

Sending via PayShap (Withdrawal)

Debit a wallet and send funds to a PayShap recipient. Two routing modes are supported:

Send to a proxy ID

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "type": "ZA_SBSA_PAYSHAP",
  "amount": 250.00,
  "payshapId": "+27821234567@standardbank",
  "description": "Payment to supplier",
  "externalUniqueId": "payshap-wdr-00000001",
  "callbackUrl": "https://your-system.example.com/webhooks/withdrawal"
}

Send to a bank account directly

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "type": "ZA_SBSA_PAYSHAP",
  "amount": 250.00,
  "accountNumber": "1234567890",
  "branchCode": "051001",
  "accountName": "Sipho Dlamini",
  "description": "Payment to supplier",
  "externalUniqueId": "payshap-wdr-00000002",
  "callbackUrl": "https://your-system.example.com/webhooks/withdrawal"
}

Response

{
  "withdrawalId": 8829301,
  "externalUniqueId": "payshap-wdr-00000001",
  "status": "PENDING",
  "amount": 250.00,
  "currency": "ZAR",
  "gateway": "ZA_SBSA_PAYSHAP",
  "type": "WALLET",
  "created": "2026-05-19T10:00:00.000Z"
}

The initial status is always PENDING. PayShap withdrawals are asynchronous — the final SUCCESSFUL or ERROR result is delivered via the callbackUrl if provided, or polled via GET .../withdrawals/{withdrawalId}.

Terminal statuses: SUCCESSFUL, ERROR, TIMEOUT, CANCELLED.

On-us detection: If the payshapId or accountNumber resolves to another wallet on the same Eclipse tenant, the transfer settles immediately without routing through SBSA.

Proxy resolution: For proxy-based withdrawals, Eclipse initiates an async proxy resolution with SBSA. Resolution typically completes within 120 seconds. The withdrawal remains PENDING until the proxy resolves and the payment is confirmed.

API Reference →

Sending via PayShap (Payment)

The same outbound PayShap payment can also be initiated through the payments endpoint. Use this when your integration uses the payments flow rather than the withdrawals flow.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/payments
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "type": "ZA_SBSA_PAYSHAP",
  "paymentData": "+27821234567@standardbank",
  "amount": 250.00,
  "currency": "ZAR",
  "externalUniqueId": "payshap-pay-00000001",
  "callbackUrl": "https://your-system.example.com/webhooks/payment"
}

For account-based payments, omit paymentData and provide accountNumber and branchCode in additionalFields.

The response, async behaviour, and on-us detection are the same as the withdrawal flow above.

API Reference →

PayShap Proxy Management

Register a wallet as a PayShap-reachable destination by linking a proxy identifier to it. Once registered, other banks can resolve the proxy and send funds directly to the wallet without needing the account number.

Two proxy sub-types are supported:

List proxies on a wallet

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/proxies
    ?type=PAYSHAP
Authorization: Bearer {jwt}

[
  {
    "proxyIdentifier": "+27821234567",
    "type": "PAYSHAP",
    "subType": "PHONE",
    "accountNumber": "1234567890"
  }
]

Register a proxy

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/proxies
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "proxyIdentifier": "+27821234567",
  "type": "PAYSHAP",
  "subType": "PHONE"
}

Eclipse registers the proxy with SBSA and links it to the wallet's settlement account. The payshap.proxy.config.payshapProxyDomain tenant config key controls the domain used during registration.

Response: 201 Created with the created proxy object including the resolved accountNumber.

Get a proxy by identifier

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/proxies/{proxyIdentifier}
    ?type=PAYSHAP
Authorization: Bearer {jwt}

Response: the proxy object for the given identifier.

Update a proxy

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/proxies/{proxyIdentifier}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "proxyIdentifier": "+27829876543",
  "type": "PAYSHAP",
  "subType": "PHONE"
}

The {proxyIdentifier} path parameter is the existing registered identifier. If the new proxyIdentifier differs from the existing one, Eclipse de-registers the old proxy and registers the new one with SBSA. If only the account linkage needs updating, the identifier can remain the same.

Delete a proxy

DELETE /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/proxies/{proxyIdentifier}
Authorization: Bearer {jwt}

Response: 204 No Content. The proxy is de-registered from SBSA and unlinked from the wallet. Subsequent inbound PayShap payments addressed to this proxy will no longer resolve to the wallet.