Onboarding business rules
Credential management, notification URL handling, password rotation, audit, and other constraints that govern the onboarding API.
These rules govern every call to the Merchant Onboarding API. Most are operational rather than technical — the API will let you do almost anything, but some things cause silent harm. Read this before you build automation against it.
For the API itself, see Onboarding overview.
Credentials
| Rule | Detail |
|---|---|
PSP credentials are generated in the Portal under the API tab. Username format is psp-{pspId}. | The PSP ID is shown on the Portal home page when you first log in. |
| Acquirer credentials are issued directly by EFT Corp on signed agreement. | Not self-serve — contact [email protected] to request. |
| Both PSPs and acquirers need a corresponding PSP ID when creating merchants. For PSPs, it's your own. For acquirers, you receive a list of permitted PSP IDs in your onboarding pack. | Acquirers without a PSP ID linkage can't create merchants directly. |
| Renewing the API password invalidates the previous one immediately. | This is the most common operational mistake — rotate during a deploy window with the automation scheduled to pick up the new password. |
| Lib Lite tokens are separate from API passwords. | Renew one without affecting the other. |
Merchant lifecycle
| Rule | Detail |
|---|---|
| Merchants auto-activate on create. | No separate "activate" step. The merchant can accept payments as soon as the API password is generated. |
| A welcome email is sent to the admin email automatically when a merchant is created. | The email link expires in 24 hours — the admin must set their Portal password within that window. If it expires, the admin can request a reset from the Portal login page. |
| The Scan to Pay Operations team is also CC'd on the merchant-creation email automatically. | For audit / support purposes. |
| Merchants can be suspended and unsuspended any number of times. | No limit on count. |
| Suspending is not the same as deleting. | Suspended merchants stop accepting payments but their history, codes, and transactions are preserved. Deletion is not supported via API — contact support if needed. |
Updates and idempotency
| Rule | Detail |
|---|---|
| Update only the fields you want to change. | Fields omitted from the body stay as they are. The platform doesn't reset omitted fields to defaults. |
| Updates to merchant data can break transactions if used incorrectly. | Changes to currency, MCC, MID, or acquirer linkage can cause in-flight transactions to fail. Update non-financial fields freely; coordinate financial-field changes during a quiet window. |
Updates do not change the merchantId. | The merchant's identifier is stable for the life of the merchant. |
Notification URL
| Rule | Detail |
|---|---|
| One HTTP notification URL per merchant. | Adding a new one replaces the old one. |
| Renewing the notification URL invalidates the old encryption key. | Webhooks delivered between the rotation and the merchant's deploy will fail to decrypt. Coordinate the rotation. See Signing and verifying webhooks. |
| Allowed ports are 443, 8443 (production) and additionally 80, 8080 (sandbox only). | Production allows HTTPS only. |
| Polling and webhook are mutually exclusive. | If a notification URL is set, queryRef returns HTTP 406. See Querying transactions. |
Backwards compatibility policy
| Rule | Detail |
|---|---|
| EFT Corporation reserves the right to add new request and response fields without notice. | Such changes are considered backwards compatible. Your code must tolerate unknown fields gracefully. |
| Breaking changes are versioned. | Breaking changes will introduce a new version path (e.g. /portal/restful/merchant/v2/...) rather than changing the existing path. |
| Deprecated fields will be marked but not removed within a stated migration window. | Watch the changelog for deprecation notices. |
Audit logging
Every onboarding API call is logged to the platform's audit trail. The log records:
- The authenticated principal (PSP ID or acquirer credential)
- The operation (
create,suspend,update, etc.) - The target
merchantId - The full request body (with sensitive fields redacted)
- The response status and any error
- A timestamp
The audit log is queryable from the Portal under your PSP / acquirer profile. For external audit requirements (PCI, internal compliance), the same log is available on request via [email protected].
Rate limits and load
The platform doesn't enforce per-second onboarding limits today. That said:
- Don't bulk-create thousands of merchants in parallel. Spread bulk runs over time — 5–10 creates per second is comfortable; 100+ in a burst risks transient errors from downstream systems (email service, audit DB).
- Pre-create a sandbox merchant before going live with your automation. It exercises the credentials path and surfaces validation rules before you do anything in production.
See Rate limits for general guidance.
Common errors
| Status | Likely cause |
|---|---|
400 | Missing required field, invalid email, malformed MCC. Inspect the body for the specific field. |
401 | Wrong onboarding credentials. PSPs: regenerate from Portal. Acquirers: contact support. |
403 | Authenticated but the operation isn't permitted for this principal — e.g. PSP trying to manage a different PSP's merchant. |
404 | The merchantId in the path doesn't exist. |
409 | Conflict — merchant already exists with that email, or the merchant is already suspended / unsuspended. |
What's next
- Operation reference → Onboarding overview
- PSP-specific flow → PSP / Aggregator flows
- Acquirer-specific flow → Acquirer flows
- Testing the onboarding flow → Testing
- Webhook setup after onboarding → Webhooks
- Generic versioning policy → Versioning
Updated 3 days ago