Merchant API

Merchant APIs let external platforms resolve users, fund external wallets, withdraw to EgaCard, create payment sessions, rotate credentials, manage apps, and reconcile webhook events.

Customer authorisation

Create the payment intent on your server. Open checkout_url on web or app_authorization_url in the EgaCard app.
EgaCard displays the verified merchant, amount, currency, fees, reason, and expiry before PIN, biometric, passkey, or risk-based approval.
Fulfil only after payment.succeeded is received and its signature is verified, or a server-side status lookup returns SUCCEEDED.

Marketplace funding

Approved merchants can be searchable in EgaCard with a merchant-defined account identifier such as email, customer ID, phone, or username.
Customers link and verify that identifier, then approve each funding transfer. EgaCard uses a ledger hold and automatically releases it if the merchant callback fails.

Endpoints

Endpoint	Method	Auth	Headers	Notes
Register merchant `/business/api/v1/merchant/register/` Create a merchant profile and owner relationship.	POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Merchant KYB `/business/api/v1/merchant/{code}/kyb/` Create, submit, and update a merchant KYB profile.	GET/POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Resolve EgaCard user `/business/api/v1/public/users/resolve/` Resolve an EgaCard user for merchant-to-wallet withdrawal flows.	POST	Merchant HMAC Authenticated caller	`X-EGACARD-API-KEY: <merchant-public-key>` `X-EGACARD-SIGNATURE: <hmac-signature>` `X-EGACARD-TIMESTAMP: <unix-timestamp>` `X-EGACARD-IDEMPOTENCY-KEY: <unique-request-key>`	Idempotency: Required Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Create payment session `/business/api/v1/public/payment-sessions/` Create an EgaCard payment intent for hosted checkout or EgaCard-app approval.	POST	Merchant HMAC Authenticated caller	`X-EGACARD-API-KEY: <merchant-public-key>` `X-EGACARD-SIGNATURE: <hmac-signature>` `X-EGACARD-TIMESTAMP: <unix-timestamp>` `X-EGACARD-IDEMPOTENCY-KEY: <unique-request-key>`	Parameters: merchant_reference — unique order or funding reference amount — positive decimal string currency — ISO 4217 wallet currency customer_email or external_user_id — optional hint payment_description — shown during approval capture_method — automatic or manual redirect_url and callback_url — allowlisted HTTPS URLs expiry_minutes — 1 to 1440 metadata — JSON object Idempotency: Required Status lifecycle: REQUIRES_CUSTOMER_ACTION, AUTHORISED, SUCCEEDED, PARTIALLY_REFUNDED, REFUNDED, FAILED, EXPIRED, CANCELLED Webhooks: payment.authorized, payment.succeeded, payment.failed, payment.refunded Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Request {'merchant_reference': 'dpa_1042', 'amount': '1000.00', 'currency': 'USD', 'external_user_id': 'patient_82', 'payment_description': 'Fund DPAppointment wallet', 'capture_method': 'automatic', 'redirect_url': 'https://dpappointment.com/payments/return'} Response {'payment_intent_id': 'EGC-…', 'lifecycle_status': 'REQUIRES_CUSTOMER_ACTION', 'checkout_url': 'https://egacard.com/business/checkout/EGC-…/', 'app_authorization_url': 'egacard://payments/authorize?payment_intent=EGC-…'}
Verify transaction `/business/api/v1/public/transactions/verify/` Verify a merchant-linked EgaCard transaction by reference.	POST	Merchant HMAC Authenticated caller	`X-EGACARD-API-KEY: <merchant-public-key>` `X-EGACARD-SIGNATURE: <hmac-signature>` `X-EGACARD-TIMESTAMP: <unix-timestamp>` `X-EGACARD-IDEMPOTENCY-KEY: <unique-request-key>`	Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Resolve external merchant user `/business/api/v1/consumer/external-users/resolve/` Consumer flow that resolves an external wallet recipient on a merchant platform.	POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Fund external wallet `/business/api/v1/consumer/external-wallets/fund/` Debit an EgaCard wallet and fund an external merchant wallet.	POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Webhooks: api.payment.successful, wallet.debited Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Search merchant marketplace `/business/api/v1/consumer/marketplace/?q={name}` Search active, KYB-approved merchants available for linking and funding.	GET	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Link merchant account `/business/api/v1/consumer/merchant-connections/` Save a merchant-specific customer identifier.	POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Parameters: merchant_code — marketplace merchant code external_identifier — identifier required by that merchant Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits
Verify merchant account `/business/api/v1/consumer/merchant-connections/{id}/verify/` Verify the saved identifier through the merchant's signed resolver endpoint.	POST	User JWT Authenticated caller	`Authorization: Bearer <user-jwt>` `Content-Type: application/json`	Sandbox: Supported with sandbox keys and adapters. Production: Available subject to verification, country activation, and provider support. Rate limits: Standard authenticated rate limits