This guide takes you from your Pilot credentials to your first approved test transaction on Unigate, Magensa's API for card-present and card-not-present payments through MPPG v5 or later. You'll set up Postman, build the Authorization header Unigate requires, run a sample EMV sale, and learn which response values to keep for later requests.
You need:
A Postman account. The sample requests are published as a Postman collection. Sign up at postman.com if you don't have one.
Your Unigate Onboarding Worksheet. It lists your Pilot CustomerCode, Username, and Password, plus the Base64-encoded version of those credentials.
Familiarity with REST APIs and the basics of payment processing.
A MagTek card reader (optional for this guide). The samples include a working ARQC, so you can run your first transaction without one. You'll need a reader before your integration is complete..
Unigate has two environments, and each has its own credentials.
Sign in to Postman.
Open the collection.
Select Run in Postman in the top right of the page. The button only appears when you're signed in.
Choose the workspace to copy the collection into.
Unigate authenticates every request with HTTP Basic Auth in the Authorization header. Unigate's credential format combines three values instead of the usual two:
Join your CustomerCode and Username with a forward slash (/).
Add a colon (:) and your Password.
Worked example
For Pilot, you can copy the encoded value straight from your Onboarding Worksheet. For Production, generate it in code:
Set your credentials once on the collection so every sample request inherits them:
In Postman, select the Unigate collection and open the Authorization tab.
Set Auth Type to Basic Auth.
Enter CustomerCode/Username as the username (for example, CUSTOMER000/MAGTEST000) and your password as the password. Postman builds the encoded header for you.
Leave each request's authorization set to Inherit auth from parent (the default). If a request fails to authenticate, check that it hasn't been changed.
In the collection, open the Transaction › EMV folder ().
Open EMV ARQC Sale. EMV ARQC Authorize also works as a starting point.
Select Send.
The request already contains a sample ARQC, so it runs against your Pilot account in real time without a card reader.
A Unigate response contains three kinds of data:
Check isTransactionApproved rather than parsing processor-specific status values. Processors report approval differently: Fiserv returns "StatusCode": "OK", TSYS returns status: "PASS", and Worldpay returns TransactionStatus: "Approved". Amount formats (cents vs. dollars) and date formats also vary. For examples from each processor, see .
The sample ARQC proves your credentials and request format work. Before your integration is complete, you must send an ARQC that your own MagTek reader generated.
Connect your test reader. See .
Run an EMV transaction on the reader with a test card. See .
In EMV ARQC Sale, replace the sample ARQC (also called the Authorization Request) with your reader's ARQC output. For the format of that data, see .
Send the request. Pilot uses test systems, so nothing is charged.
To see a reader and Unigate working together in a browser first, try the . For help getting started with readers, see the .
Check your processor's var sheet. Some processors have non-standard requirements, which they list on the var sheet they issue to you.
Build the Production header in code as shown in Step 2. Production credentials don't come pre-encoded.
Contact your assigned solutions architect for processor-specific inputs and outputs, advanced request fields, or anything this guide doesn't cover.
Put Basic and a space in front of the encoded string.
Combined string
CUSTOMER000/MAGTEST000:123456789
Base64 encoded
Q1VTVE9NRVIwMDAvTUFHVEVTVDAwMDoxMjM0NTY3ODk=
Authorization header
Basic Q1VTVE9NRVIwMDAvTUFHVEVTVDAwMDoxMjM0NTY3ODk=
Save the collection.
Browser demos of Unigate with and without MagTek readers.
Environment
Use it for
Credentials
Pilot
Development and testing. Requests go to processor test systems, so nothing is charged.
From your Onboarding Worksheet, which includes the pre-encoded Base64 value.
Production
Live transactions.
Step
Value
CustomerCode
CUSTOMER000
Username
MAGTEST000
Password
import base64
customer_code = "CUSTOMER000"
username = "MAGTEST000"
password = "123456789"
raw = f"{customer_code}/{username}:{password}"
auth_header = "Basic " + base64.b64encode(raw.encode("utf-8")).decode("ascii")const customerCode = "CUSTOMER000";
const username = "MAGTEST000";
const password = "123456789";
const raw = `${customerCode}/${username}:${password}`;
const authHeader = "Basic " + Buffer.from(raw, "utf8").toString("base64");using System;
using System.Text;
string customerCode = "CUSTOMER000";
string username = "MAGTEST000";
string password = "123456789";
string raw = $"{customerCode}/{username}:{password}";
string authHeader = "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes(raw));echo "Basic $(printf '%s' 'CUSTOMER000/MAGTEST000:123456789' | base64)"Data
What it's for
Standardized Magensa fields
Consistent values across every processor. For example, isTransactionApproved tells you whether the processor approved the transaction, whatever that processor calls "approved."
Normalized processor fields
Processor fields renamed to common keys. For example, Fiserv's ReturnCode becomes processorStatusCode, and TSYS's hostReferenceNumber becomes processorReference.
Raw processor fields
Topic
What you'll learn
How initial requests (Sale, Authorize) relate to follow-up actions (Capture, Tip Adjust, Refund, Void).
How Unigate maps processor-specific fields to common keys.
Issued separately. You must build the Authorization header yourself.
123456789
The processor's original values, always included so no data is lost.
Every Transaction and ReferenceTransaction request, with links into the Postman collection.