Getting Started with Unigate

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.

New to Unigate? Read the MPPG/Unigate overview first for what Unigate does and when to use it.

Before you begin

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..

Pilot and Production

Unigate has two environments, and each has its own credentials.

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.	Issued separately. You must build the Authorization header yourself.

Building Tap to Pay on iPhone? Apps with a development entitlement use the Magensa SANDBOX environment, and apps with a production entitlement use PRODUCTION. See Tap to Pay on iPhone API

Step 1: Copy the collection to Postman

1. Sign in to Postman.

2. Open the Unigate API collection.

3. Select Run in Postman in the top right of the page. The button only appears when you're signed in.

4. Choose the workspace to copy the collection into.

Step 2: Build the Authorization header

Unigate authenticates every request with HTTP Basic Auth in the Authorization header. Unigate's credential format combines three values instead of the usual two:

1. Join your CustomerCode and Username with a forward slash (/).

2. Add a colon (:) and your Password.

3. Base64-encode the resulting string.

4. Put Basic and a space in front of the encoded string.

Worked example

Step	Value
CustomerCode	CUSTOMER000
Username	MAGTEST000
Password	123456789
Combined string	CUSTOMER000/MAGTEST000:123456789
Base64 encoded	Q1VTVE9NRVIwMDAvTUFHVEVTVDAwMDoxMjM0NTY3ODk=
Authorization header	Basic Q1VTVE9NRVIwMDAvTUFHVEVTVDAwMDoxMjM0NTY3ODk=

For Pilot, you can copy the encoded value straight from your Onboarding Worksheet. For Production, generate it in code:

Python

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")

Node.js

const customerCode = "CUSTOMER000";
const username = "MAGTEST000";
const password = "123456789";

const raw = `${customerCode}/${username}:${password}`;
const authHeader = "Basic " + Buffer.from(raw, "utf8").toString("base64");

C#

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));

Shell

echo "Basic $(printf '%s' 'CUSTOMER000/MAGTEST000:123456789' | base64)"

WARNING: Base64 is encoding, not encryption. Anyone who sees the header can decode your password. Send requests only over HTTPS, keep credentials out of source control, and never log the header.

Step 3: Save your credentials at the collection level

Set your credentials once on the collection so every sample request inherits them:

1. In Postman, select the Unigate collection and open the Authorization tab.

2. Set Auth Type to Basic Auth.

3. Enter CustomerCode/Username as the username (for example, CUSTOMER000/MAGTEST000) and your password as the password. Postman builds the encoded header for you.

4. Save the collection.

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.

Step 4: Run your first EMV sale

1. In the collection, open the Transaction › EMV folder (EMV).

2. Open EMV ARQC Sale. EMV ARQC Authorize also works as a starting point.

3. Select Send.

The request already contains a sample ARQC, so it runs against your Pilot account in real time without a card reader.

Step 5: Read the response

A Unigate response contains three kinds of data:

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	The processor's original values, always included so no data is lost.

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 Processor Responses.

Save the MagTranID. Record the full response from every Transaction request. To Capture, Tip Adjust, Refund, or Void a transaction later, you send a ReferenceTransaction request that uses the original MagTranID.

Step 6: Test with your own MagTek reader

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.

1. Connect your test reader. See Connection Basics.

2. Run an EMV transaction on the reader with a test card. See Your First Transaction.

3. 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 EMV ARQC Type.

4. 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 MMS Unigate Demo. For help getting started with readers, see the RMS reader quickstart.

Before you go to Production

• 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.

Next steps

Topic	What you'll learn
Transactions and Reference Transactions	How initial requests (Sale, Authorize) relate to follow-up actions (Capture, Tip Adjust, Refund, Void).
Normalized Processor Response Fields	How Unigate maps processor-specific fields to common keys.
Unigate API Reference	Every Transaction and ReferenceTransaction request, with links into the Postman collection.
Web-based Demos	Browser demos of Unigate with and without MagTek readers.

Need More Help?

Need Help?

For additional support, please contact MagTek Support:

Technical Support:

• 📧 Email: [e-mail]

• 📞 Phone: [phone] (US)

• 🕐 Hours: Monday-Friday, 5:30 AM - 5:00 PM PST

Online Resources:

• 🌐 Support Portal: developer.magtek.com

Documentation Feedback:

Help us improve this documentation! [e-mail]