Authentication

Two authentication mechanisms are used. Pick the right one based on which endpoint you are calling.

Basic auth (API endpoints)

Used for all transaction-flow endpoints: /inbound, /outbound, /account-lookup, /balance, /transactions, /transaction/status, /transactions/{ref}/timeline, /settlement/list, /wallet/history.

Authorization: Basic base64(merchant_code:merchant_secret)

• merchant_code — issued at sign-up. Looks like MKA-XXXX-XXXX.
• merchant_secret — issued at sign-up. Looks like sk_live_XXXXXXXX…. Treat as a password: never commit to git, never log, never expose in the browser.

Do not embed credentials in the browser

The API is not a public-endpoint API. Every request must originate from your server (or a signed proxy). Do not put merchant_secret in browser JavaScript.

Example request:

curl -X GET https://staging.remittance.gofreshpay.com/api/v1/remittance/balance \
  -u 'MKA-XXXX-XXXX:sk_live_XXXXXXXX'

Bearer auth (dashboard / self-service)

Used for merchant-dashboard-only endpoints: /merchant/login, /merchant/change-password, /merchant/secret, /merchant/whitelist, /merchant/callback, /merchant/go-live.

Step 1 — log in with email + password:

POST /api/v1/merchant/login
Content-Type: application/json

{
  "email":    "you@example.com",
  "password": "…"
}

Response includes access_token. Send it as Authorization: Bearer <access_token> on subsequent dashboard calls.

Rotating your merchant_secret

POST /api/v1/merchant/secret (Bearer auth) generates a new merchant_secret and invalidates the previous one. Read carefully — this is a destructive operation. Any deployed system still using the old secret will start failing with 401 immediately after rotation.

Secret handling on the merchant side

• Store merchant_secret in an encrypted secret store, not in plain files.
• Rotate on personnel change or suspected exposure.
• If you need short-lived tokens for a fleet of callers, generate merchant-side sub-tokens signed by your own service, and use the merchant-level Basic auth for the outbound call.