Switching to the new Evina Fraud Check service

Mobixone has moved its Evina fraud-check gateway to a new service. Every operation you use today is available on it, unchanged. What changes for you is where you send requests and how you authenticate: the new service takes OAuth 2.0 access tokens instead of a username and password.

This guide walks through the change in order: what you will receive from Mobixone, the changes to make on your side, how to test them in staging, and how to move production traffic.

Nothing changes in the requests themselves

The paths, the request bodies and the responses are identical to the current service. If your integration works today, it works on the new service once it sends the new address and an access token. No field is added, renamed or removed.

What changes, and why

	Today	New service
Base URL	The address you were given at integration time	`https://evina.mobixone.co` (production)
Authentication	HTTP Basic: a username and password on every request	OAuth 2.0 Bearer access token on every request
Credentials	A fixed password	A `client_id` and `client_secret`, exchanged for short-lived tokens
Operations, paths, bodies, responses		Unchanged

Mobixone is moving to one authentication method across all of its partner APIs. The same client_id and client_secret that authenticate you against the XCIS API now authenticate you against the fraud-check service as well. Tokens expire after eight hours, so a leaked token has a short life, and your password no longer travels with every request.

If you are new to OAuth 2.0 at Mobixone, read Authentication overview first. The rest of this guide assumes you know how to request a token.

Environments

The fraud-check service has a staging copy and a production copy. Each one trusts tokens from the matching token endpoint only.

Environment	Token endpoint	Fraud-check base URL	`audience` value	Evina environment
Staging	`https://stgoauth.mobixone.co.za/oauth2/token`	`https://stage-evina.mobixone.co`	`https://stage-evina.mobixone.co`	Evina test
Production	`https://oauth.mobixone.co.za/oauth2/token`	`https://evina.mobixone.co`	`https://evina.mobixone.co`	Evina live

The audience is different from the XCIS API

Every token names the service it is for. A token requested for the XCIS API carries the XCIS audience and is rejected by the fraud-check service, and the reverse is also true. Request a separate token with the fraud-check audience value from the table above. See Step 1.

Staging and production are fully separate systems. Staging credentials do not work in production, and a staging token is rejected by the production service.

What you will receive from Mobixone

Before you start, Mobixone will do the following on its side. Ask your Mobixone technical contact if any item is missing.

Credentials. If you already call the XCIS API with OAuth 2.0, you use the same client_id and client_secret. If you do not, you will be issued a client_id and a client_secret for staging and, separately, for production. The secret is shown once; see Getting started.
Authorisation for the fraud-check service. Your client is enabled for the scope content:fraud-check and for the two audience values in the table above. Until this is done, the token endpoint refuses the scope or the audience with a 400.
Confirmation that staging is ready for you, so that you can test before touching production.
A production window. Mobixone will agree a date with you for moving production traffic, and will confirm when it sees your production calls arriving.
Support during the switch. Mobixone can see every call you make to the new service by transaction id, so a problem report that quotes the ti value, the environment and the time can be traced quickly. See Getting support.
The retirement date of the current address. The current address keeps working while you switch. Mobixone will tell you the date after which it is withdrawn.

Step 1: Request a token for the fraud-check service

Send a POST to the token endpoint with HTTP Basic client authentication, the scope content:fraud-check, and the fraud-check audience for the environment.

curl -X POST https://stgoauth.mobixone.co.za/oauth2/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=content:fraud-check" \
  -d "audience=https://stage-evina.mobixone.co"

A successful response looks like this:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjA0YWJhMTc3...",
  "expires_in": 28799,
  "scope": "content:fraud-check",
  "token_type": "Bearer"
}

Check two things in the response before going further:

scope contains content:fraud-check. If it does not, your client has not been enabled for the fraud-check service yet.
You sent the fraud-check audience. The token endpoint does not add it for you, and it does not complain if it is missing. A token without it is issued normally and then refused by the fraud-check service with 401.

The full token request reference is in Requesting an access token.

Step 2: Send the token on every fraud-check request

Replace the Authorization: Basic ... header with Authorization: Bearer <access_token>. Everything else in the request stays as it is: POST, Content-Type: application/json, the same path, the same body.

curl -X POST https://stage-evina.mobixone.co/evina/evina-dcb-script/ \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjA0YWJhMTc3..." \
  -H "Content-Type: application/json" \
  -H "User-Agent: your-integration/1.0" \
  -d '{
    "contentData": {
      "name": "your-service-name",
      "operatorName": "vodacom-za-t2",
      "country": "ZA",
      "serviceType": "subscribe",
      "serviceId": "your-service-id",
      "contentName": "your-content-name",
      "requestRef": "your-request-reference"
    }
  }'

Three details that matter on the new service:

Paths are exact, including the trailing slash. /evina/evina-dcb-script/ is found; /evina/evina-dcb-script is not.
Send a normal User-Agent header. The service sits behind Cloudflare, which refuses requests with an empty or unusual user agent before they reach the service. Any descriptive value, such as your product name and version, is fine.
Content-Type must be application/json. Other values are refused with 415.

Step 3: Change the base URL

Point your integration at the new base URL for the environment. The paths below are the complete set and are unchanged from the current service; the ones you use today keep working with the same bodies.

Path	Purpose
`/evina/evina-dcb-script/`	Protection script for a DCB page; returns `script` and the transaction id `ti`
`/evina/evina-dcb-check/`	Check of a DCB transaction by `transactionId`
`/evina/evina-non-dcb-script/`	Protection script for a non-DCB page; returns `script` and `ti`
`/evina/evina-non-dcb-check/`	Check of a non-DCB transaction by `transactionId`
`/evina/script/`	Script with page redirect, caller-supplied `transactionId` and `arg1`..`arg8`
`/evina/page-redirect/`	Page redirect by API key
`/evina/check/`	Check by `transactionId`
`/evina/check-redirect/?country=`	Check by API key, with the `country` query parameter
`/evina/traffic-screener-script/`	Traffic Screener script
`/evina/traffic-screener-precheck/`	Traffic Screener pre-check

GET /actuator/health answers {"status":"UP"} without a token, and is a quick way to confirm you can reach the service.

Step 4: Remove the password and cache the token

Once the token is in place:

Remove the username and password from your configuration. The new service never asks for them.
Cache the token and reuse it until shortly before it expires. Request a new one when it is within a few minutes of expiry, or when a call returns 401, and retry that call once. Do not request a token per fraud-check call. The required pattern is in Token caching.
If you also call the XCIS API, keep two cached tokens, one per audience. They cannot be shared.

Step 5: Test in staging

The staging service talks to Evina's test environment, so you can run a full script-and-check pair without touching live traffic. Work through these in order; each one proves the next step is worth trying.

Reachability. GET https://stage-evina.mobixone.co/actuator/health returns {"status":"UP"}. If this fails, the problem is network or TLS on your side, not credentials.
Token. Request a token as in Step 1 and confirm scope contains content:fraud-check.
Authentication. Call a check endpoint with the token and a made-up transaction id:
```
curl -X POST https://stage-evina.mobixone.co/evina/evina-dcb-check/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "User-Agent: your-integration/1.0" \
  -d '{"transactionId": "test-0001"}'
```
Expect 200 with a body like {"e":["unknown-transaction-id"],"success":false}. That answer is correct: it proves your token was accepted and the service reached Evina. A 401 here means the token was refused; see Troubleshooting.
Script. Call the script endpoint you use in production, as in Step 2, with your own service details. Expect 200 and a body with script (a long JavaScript string) and ti (a 16-character transaction id). Keep the ti.
Check with that transaction id. Call the matching check endpoint with the ti from step 4. Expect 200 with "success": true and a numeric ft verdict code, not unknown-transaction-id. Evina can take a few seconds to register a new transaction, so if the first attempt answers unknown-transaction-id, wait five seconds and try again. Because no browser has run the script, the verdict will be a failure code; that is expected and shows the pair is wired correctly.
Refusals. Confirm your error handling by provoking two 401 responses: once with a token requested for the XCIS audience, and once with the token altered by a character. Both must be refused.
Your own flow. Run your real integration against staging end to end, with a browser loading the page that carries the script, and confirm the check verdicts are what you see today.

Step 6: Move production

Request a production token from https://oauth.mobixone.co.za/oauth2/token with audience=https://evina.mobixone.co.
Repeat steps 1 to 3 of the staging test against https://evina.mobixone.co. The check with a made-up transaction id sends nothing that affects live traffic.
Switch your production configuration to the new base URL and token, in the time window agreed with Mobixone.
Watch your first live transactions and confirm the script loads and the check verdicts arrive as before. Mobixone will confirm from its side that your calls are arriving on the new service.
Remove the old address and password from your configuration once you are satisfied.

If anything goes wrong, point your configuration back at the current address with the username and password. The current service keeps running until the retirement date Mobixone gives you, so there is no window in which a rollback has nowhere to go.

Troubleshooting

Response	What it means	What to do
`401` with an empty body	The token was not accepted	Check, in this order: the token has not expired; it was requested from the token endpoint of the same environment; the `audience` is the fraud-check base URL, not the XCIS audience; the `scope` includes `content:fraud-check`; the header reads `Authorization: Bearer <token>` with nothing altered. The `WWW-Authenticate` header on this response mentions Basic authentication; that is a compatibility detail and does not mean Basic is expected from you
`400` from the token endpoint	Your client is not authorised for the scope or the audience requested	Ask Mobixone to confirm your client is enabled for `content:fraud-check` and the fraud-check audiences
`403` with a Cloudflare error page (code 1010)	The request was refused before it reached the service	Send a descriptive `User-Agent` header
`404`	Path not found	Check the path against the table in Step 3, including the trailing slash
`405`	Method not allowed	Every fraud-check call is `POST`
`415`	Unsupported media type	Send `Content-Type: application/json`
`400` from the service	The body is not valid JSON	Check the request body
`500` or `502`	Evina did not answer or answered with an error	Retry once after a short wait; if it persists, contact Mobixone with the transaction id

Other responses, including 200 with "success": false and a code in e, are Evina's own answers and are the same as on the current service.

Getting support

Contact your Mobixone technical contact. When reporting a problem, include:

Your client_id (never your client_secret or a full access token)
The environment (staging or production)
The endpoint called
The HTTP status and the response body
The transaction id (ti or transactionId) of the call, if there was one
An approximate timestamp

The transaction id is the fastest way for Mobixone to find your call in its logs.

What changes, and why​

Environments​

What you will receive from Mobixone​

Step 1: Request a token for the fraud-check service​

Step 2: Send the token on every fraud-check request​

Step 3: Change the base URL​

Step 4: Remove the password and cache the token​

Step 5: Test in staging​

Step 6: Move production​

Troubleshooting​

Getting support​