Authentication

Every request uses HTTP Basic authentication. There is no token exchange, no expiry, and no refresh step: you send the same header on every call.

3.1 Build the header

Join your username and password with a colon: username:password.
Base64-encode that string.
Send it as Authorization: Basic <encoded>.

# Build the header yourself (it matches the portal's "Derived Authorization header")
printf '%s' 'sbx_yourusername:yourpassword' | base64

# Or let curl do it with -u
curl -u "$EIP_USERNAME:$EIP_PASSWORD" \
  'https://developers.ecocash.co.zw/sandbox/payment/v1/{endUserId}/transactions/amount/{clientCorrelator}'

3.2 Store credentials safely

Keep every EIP value in configuration, never in code:

# .env — never commit this file
EIP_BASE_URL=https://developers.ecocash.co.zw/sandbox/payment/v1
EIP_USERNAME=sbx_yourusername
EIP_PASSWORD=your_password

# Merchant values: copy them from your portal's Authentication tab → Credential Reference
EIP_MERCHANT_CODE=287164
EIP_MERCHANT_PIN=1234
EIP_MERCHANT_NUMBER=778503033
EIP_TERMINAL_ID=TERM001
EIP_MERCHANT_NAME="Test Merchant"
EIP_SUPER_MERCHANT_NAME="EcoCash Sandbox"
EIP_CHANNEL=WEB
EIP_LOCATION=Harare

# Refund transaction type: REF (refund) or REV (reversal). See section 4.5.
EIP_REFUND_TRAN_TYPE=REF

Which merchant values? The portal publishes two sandbox merchant sets. Use the one on your Authentication tab’s Credential Reference (it matches what the API Playground sends). The other set, from the Documentation tab’s Test Data, is listed in Sandbox merchant values.

3.3 Authentication errors

HTTP	Code	Meaning	Fix
`401`	`E006`	Header missing, malformed, or wrong username/password	Re-copy both values from the Inbox and rebuild the header
`403`	`E007`	Sandbox not enabled	Click Request Sandbox Access, then Save & Activate

This page is generated from section 3 of the README in README.md. Spotted something wrong? Open an issue.