Cygma API

Cygma is a full ISO 8583 payments switch wrapped in a JSON API. One bearer credential per terminal, one POST per transaction, standard ISO response codes that mean exactly what the spec says they mean.

Every endpoint is a POST with a JSON body. The body shape is the same across every transaction type – only the MessageType, ProcessingCode, and the URL path change.

• Production: https://api.cygma.com:443
• Cert sandbox: https://apicert-sandbox.cygma.com:9443

1. Get your CardAcquirerId, TerminalId, and SecurityControlInformation from EPI. The first two go in plaintext per request; the third is the auth secret.
2. POST your transaction JSON to the matching URL (one URL per transaction type – see Sale below for the canonical shape).
3. Read ResponseCode from the response. "00" means approved; anything else, look up in Response codes.

Three fields identify the request – all live in the JSON body:

• CardAcquirerId (DE 42) – your parent merchant number, assigned by EPI when the merchant is provisioned.
• TerminalId (DE 41) – unique per merchant. EPI assigns this when the merchant is provisioned.
• SecurityControlInformation (DE 53) – the per-terminal secret. Cygma validates the (acquirer, SCI) pair on every call and declines if either doesn’t match what they have stored. Treat it like a bearer token.

TLS terminates at the Cygma edge. There’s no Authorization header – credentials travel in the body.

Every transaction uses the same outer shape. A few details that aren’t obvious from the spec PDFs:

• MessageType is the 3-digit form ("200"), not the canonical ISO four-digit MTI. "0200" returns a generic ErrorCode: 100000 / "Server error" without ever reaching the ISO layer.
• LocalTransactionDate and ExpirationDate need slashes on input (MM/DD, YY/MM). The gateway echoes back the no-slash form in responses but rejects unsigned input.
• TransactionAmount is 12 digits, zero-padded, in cents (minor units). "000000000400" = $4.00.
• SystemsTraceNumber (STAN) must be unique per terminal per business day. Reversals match on (terminal, STAN), so keep it stable across retries of the same intent.
• Most optional/conditional fields live inside RequestDataElements – Cygma calls this the “Private Use” data element.

The (POSEntryMode, POSConditionCode) pair tells Cygma how the card data got into the terminal. Picking the right pair matters – it drives interchange qualification, chargeback liability, and (for some processors) whether the transaction downgrades to a higher-cost tier.

CNP also needs the e-commerce indicator. Send RequestDataElements.ElectronicCommerceIndicator: "01" on every key-entered card-not-present transaction. Without it the transaction downgrades.

Implementation note. The table above is the specification. Send 012/08 on keyed CNP and test the pair on its own; a code 30 format error on such a packet points to RequestDataElements, not to the entry-mode pair.

Misclassifying a CNP transaction as card-present (or vice versa) can cost the merchant interchange and expose them to chargebacks they wouldn’t otherwise face. When in doubt, pick the more conservative classification.

Every transaction type has its own dedicated URL under /hostapi/ – the JSON envelope is the same shape everywhere; only the URL (and a couple of type-specific fields) changes. The everyday set is documented in depth below; the rest are listed here so you know the full vocabulary.

MTI 200, ProcessingCode 000000. The canonical card-present sale – terminal swipes / chip-reads / key-enters, terminal sends, gateway authorizes, transaction is stored in the terminal batch for end-of-day settlement.

Three ways to present the card (send exactly one): a keyed PrimaryAccountNumber + ExpirationDate (shown here), raw magstripe Track1Data / Track2Data (DE 45 / DE 35), or an EMV chip/contactless read via ICCSystemRelatedData (DE 55) – see Card entry: MSR / EMV for the track + EMV payload shapes and the matching POSEntryMode values.

For cardholder-not-present (e-commerce, MOTO), use /hostapi/mailorder/ instead – it sets POSConditionCode: "59" and expects ElectronicCommerceIndicator.

Read AuthorizationIdResponse – that’s the auth code you store on your order for future refund / reversal lookups.

Sending CVV2RequestValue or the billing ZipCode / Address? Those aren’t free-form – see CVV2 verification and AVS verification for the exact field formats and the result-code tables.

The CNP / e-commerce / MOTO equivalent of Sale. Same response shape – only the URL and POSConditionCode change. AVS happens off ZipCode + Address; the CVV2 result comes back in ResponseDataElements.CVV2ResultCode.

Reserve funds at one amount, then capture at the final amount when you know it. Common for hospitality (hold $200, charge $187 on checkout), fuel (hold $125 at the pump, charge actual fill), or staged shipments.

ProcessingCode differs per message family. It is not 000000 everywhere. A 0100 sent with 000000 answers 12 INVALID TRANSACTION; the identical packet with 100000 approves, and the completion class is 110000. See the hospitality flow for the full certified sequence.

The completion needs to reference the pre-auth’s STAN + auth code so the gateway can match.

An approved completion response does not return AuthorizationIdResponse. The approval code appears only inside AlternteResponseText, so any later message needing an auth code must reference the ORIGINAL pre-auth’s code.

Credit funds back to the cardholder. Same envelope as Sale – the only difference is ProcessingCode 200000 (credit rather than debit). MTI is still 200.

Reverses a same-batch transaction: a sale, a mail order, an authorization (releases the hold), or a pre-authorization whose completion did not go through. Send it while the batch is open; after the batch closes, use Refund instead. A captured completion is not reversed by this message: the host approves it and keeps the capture in the batch. Refund a captured completion.

The host locates the original by RetrievalReferenceNumber, STAN, NetworkReferenceNumber and the Original* elements, and it needs PrimaryAccountNumber and ExpirationDate on the reversal. Without the card the response is 31 CALL HELP - NS. The envelope frame (STAN, LocalTransactionTime, LocalTransactionDate) is new; OriginalTime and OriginalTransactionDate are the original message’s own values.

Inquires the available balance on a card. No transaction is recorded – pure read.

Probes the card without authorizing an amount. Use when you want to verify a card-on-file is still valid before billing – common for recurring subscriptions and stored-card vault enrollment.

The production tokenization path is a dedicated service, separate from this ISO-8583 gateway: a mutual-TLS API (tokenize / detokenize) that swaps a PAN for an opaque token and back. Tokenize the PAN once, store only the token, and at void / refund / recurring time detokenize just long enough to build the packet. It requires a client certificate (mTLS) and an IP allow-list; ask EPI to enable it.

The Token then rides TokenizationElements.Token (tag T03) on the gateway call in place of PrimaryAccountNumber – one of PAN / track / token / encrypted-PAN is required on every authorization, financial, and reversal message, and the token satisfies that.

Note – inline indicator (unverified). The reference guide also documents an inline option: TokenizationElements.TokenIndicator: "R"on the sale to have the host return a token in the response. EPI has not certified this against live Cygma (the spec marks the standalone tokenization transaction “reserved for future use”), so the dedicated service above is the path we use.

Level II data qualifies a transaction for commercial-card interchange categories when the cardholder pays with a business / corporate / purchasing card.

Every Level II field is a named top-level key of RequestDataElements (DE 62). Each maps to an L-prefix tag in the host dictionary; conditions come from the host spec – M mandatory, C99 required for Level III qualification (see the chart below).

Minimum Level II set: SalesTaxAmount + SalesTaxCollectedIndicator + MerchantOrderCustomerReferenceNumber. The C99 rows become required when the transaction also carries Level III line items.

For key-entered card-present (POSEntryMode 011): also include ZipCode, Address, CVV2RequestValue.

For CNP / MOTO (POSEntryMode 012 / condition 08): include all the above PLUS ElectronicCommerceIndicator: "01".

Level III adds line-item detail (quantity, unit cost, commodity code, unit of measure) for every product on the order, submitted alongside the Level II data.

Repeating line-item tags travel ONLY inside Level3Items1…Level3Items15 (host tag L99, maximum 15 items). Each value is a packed TLV string: 3-char tag + 4-digit ASCII length + value, concatenated with no separators. Sending a repeating tag as its own top-level key is silently ignored by the host – it must be inside a Level3Items string to count.

Required per item (condition C99): L31 product code, L32 description, L34 unit of measure, L35 extended amount, L36 debit/credit indicator, L37 line discount, L40 unit cost. Required at header: the Level II C99 set above (tax indicator, discount / freight / duty amounts + indicators) plus SalesTaxAmount and MerchantOrderCustomerReferenceNumber.

A commodity code (L30) is needed to qualify – use the NIGP class/subclass list (e.g. 61500 office supplies, 20511 microcomputers). The full list is available as a spreadsheet: cygma-commodity-codes.xlsx (2,839 codes across 192 classes). Amounts inside items are 12-digit zero-padded cents; quantities are 9-digit.

The complete per-tag reference – with types, widths, conditions, and card-brand mappings – is in the L-tag dictionary below.

Tag prefixes group the DE 62 / DE 63 private-use dictionary; conditions come from the Code/Meaning chart.

Tag prefix chart

Condition Code/Meaning chart

L-tag dictionary – header fields (top-level RequestDataElements keys)

L-tag dictionary – repeating line-item fields (inside Level3Items TLV only; ignored at header)

Required tags to build a Level II packet – all card brands

Required tags to build a Level III packet – all card brands (in addition to the Level II set)

Network field mapping – where each tag lands per card brand

Tags L03–L08 and L74/L75/L79–L98 do not exist. There is no “order amount” or “line sequence” tag – ordering is implied by Level3Items1…15. Tax exemption is signaled via L12 = "2"; the legacy TaxExemptIndicator key is accepted by the host but is not part of the dictionary. L50–L64 carry VAT sets 2–6; L68–L73 and L76–L78 are Discover/healthcare industry extras.

Do NOT send a CardScheme key inside RequestDataElements – the host rejects the transaction as code 30 format error.

An industry addendum describes WHAT was bought, in the vocabulary the card networks defined for that trade. A hotel sends arrival and departure dates and a room rate; a fuel pump sends gallons, price per gallon and an odometer reading; an airline sends a ticket number and an itinerary. The authorization approves with or without it – what the data buys is the industry interchange rate and a chargeback defence, since the issuer can see the stay or the trip rather than a bare amount.

Two rules cover the whole mechanism. First, set IndustryIndicator (tag J26) to the industry’s number – that is what tells the host how to read the rest. Second, send the industry’s own tags as ordinary keys inside RequestDataElements. There is no wrapper object and no repeating container, unlike Level III.

Send the indicator only alongside real data. Announcing an industry and then describing nothing is worse than sending neither: the host has been told to expect a hotel and finds no folio. Omit IndustryIndicator when you have no addendum fields to go with it.

Widths and implied decimals are not uniform, and this is what catches integrators.Every amount is a zero-filled integer with no decimal point, but the scale differs BY FIELD rather than by type – a single fuel message carries three of them. Unit price and the gross and net fuel prices take four implied decimals in a 12-digit slot; the sale amount and the non-fuel prices take two in the same width; fuel quantity takes threein a 6-digit slot. A wrong scale is not rejected – it is accepted as a different number. $38.39 at four decimals is 000000383900, and sending 000000003839 books 38 cents. Read the scale off the per-field tables below rather than inferring it.

Fixed-width alphanumeric codes are space-padded on the right. Level III’s AN tags are variable-length and never padded, but a fixed-width code slot is different: Visa’s own worked examples show Expanded Fuel Type as 19   and FC  – a two-character code left-justified in four. The tables mark those fields space-padded.

Not every brand carries every industry. Where a field or a whole profile is defined by only some networks, the tables say so. Sending a profile to a brand that does not define it earns nothing and risks a format error, so gate on the brand rather than sending it universally.

The J26 dictionary also enumerates Visa Limited Data (7), Mail order / telephone order (9), Retail (10), Temporary services (24). Those are classifications rather than data sets – they carry no addendum fields, so there is nothing to send beyond the indicator itself.

These are two profiles split by brand, not by trade. Fuel (J26 = 8) is the Mastercard and Discover profile; fleet (J26 = 25) is the Visa one. There is no separate Visa fuel profile – Visa fuel data rides Fleet, which is why a fuel sale on a Visa card sends J26 = 25 and the S-tags rather than the B-tags. Send the profile that matches the card in hand; the tables mark which brands carry each one.

Both describe the same dispense – product, quantity, unit price, service type, odometer. Fleet adds the identifiers a fleet card exists to capture: employee number, trailer number, and the two free-form prompted-data fields the pump collects.

Product codes come from the Visa Fleet 2.0 tables, not from the NIGP commodity list. These are two different catalogues and they are not interchangeable. Fuel products (01 unleaded, 02 mid-grade, 19 diesel, and so on) and non-fuel products (B9, 45car wash, and so on) are also separate namespaces from each other – the same two characters mean different things in each table, so a code is only meaningful alongside the field it was sent in.

Type of purchase (S51) gates the rest of the fleet block. A non-fuel-only purchase has no fuel type, no service type and no unit of measure; sending them anyway describes a dispense that did not happen. The conditional fields are marked in the tables above with the value that enables them.

Unit of measure follows the market. US fuel is sold in gallons (G); litres (L) apply where the pump does. It follows from the fuel type rather than being an independent choice.

Odometer is a whole number of miles or kilometres– no separators and no decimal. It is a reading, not a measurement, and the host reads it as digits.

The full Visa product tables are published as a spreadsheet: visa-fleet-product-codes.xlsx – 133 fuel codes and 195 non-fuel codes, each with its Conexxus equivalent and its unit of measure.

Surcharge, tip, and cashback amounts ride in the AdditionalAmounts field (DE 54). Two rules:

• ProcessingCode stays "000000" for surcharge and tip. ONLY a cash-back request flips the first two digits to "09" – sending 090000 on a credit surcharge sale is a format-error decline (code 30).
• TransactionAmount is the total – base + surcharge + tip + cashback.

AdditionalAmounts is a 20-character positional string:

Surcharge rules: max 3% of the base amount. Your terminal must vet the BIN before applying – if you send a surcharge on a debit card BIN, Cygma returns response code 97 “Surcharge Not Permitted”. Re-prompt the user and resubmit without the surcharge.

Cashback is only valid on debit / EBT (the "D" credit-debit flag); never on credit. Surcharge is only valid on credit ("C"); never on debit.

Incremental authorization uses AdditionalAmounts amount type "39" – the complete flow with packets is in the next section.

The bar-tab / hospitality lifecycle: open a tab with a pre-authorization, raise it with incremental authorizations as the tab grows, capture the final amount with a completion, then adjust for the written tip.

Rules for the incremental messages (steps 2-3):

• RequestDataElements.ReasonCode: "10" (Incremental Authorization) is mandatory.
• AdditionalAmounts amount type "39" carries the cumulative authorized total; TransactionAmount is the additional amount being authorized in this message.
• The original RetrievalReferenceNumber (DE 37) must be present and match – response code 98 “Incremental Transaction Validation Error” means DE 54 was missing or the original RRN was missing/mismatched.
• Visa: set RequestedACI: "I" (Incremental Payments).

The completion (step 4) and tip adjust (step 5) reference the transaction by AuthorizationIdResponse + OriginalSystemTraceAuditNumber+ the original’s exact transmitted date/time. Tip adjust is only valid while the sale is in the OPEN batch.

There are two ways to close a tab and they are not equivalent. Putting the tip inside the completion is a single message and is the right close whenever the final amount is known at capture time - authorize with headroom (20% over the running tab is customary) and capture the total. Reach for /adjustsale/ only when the amount changes after the capture has already happened.

Do not use /adjustsale/ to raise an authorization. Adjust does not route to the card brand - it is a host-local batch edit whose amount reaches the brand at clearing - so the issuer’s hold does not move. Growing the tab that way would settle above the authorized amount with no authorization behind the difference. Raising a tab is what the incremental authorizations in steps 2-3 are for.

Run the full sequence against the cert host before production.

Send the card security code in CVV2RequestValue inside RequestDataElements. It is not a bare 3–4 digit value – it is a fixed 6-character field. Sending the raw code (e.g. "123") is the classic 30 Format error on Mastercard and a suspect-fraud decline on Visa.

The issuer's answer is normalized into CVV2ResultCode (DE63.A42):

The digit length and card-brand name for the code differ by network, but every brand normalizes to the same M/N/P/S/U result above. The raw per-network code is echoed in CVV2NetworkResultCode.

Submit the cardholder's billing ZIP in ZipCode and the street in Address, inside RequestDataElements. AVS runs whenever either is present – there is no explicit AVS request flag to set. The issuer's answer returns in AVSResponseCode; the raw per-network code is in AVSNetworkResultCode.

Cygma settles by batch. At end of business day, post your own tallied totals to /hostapi/settlementrequest/ – MTI 500, ProcessingCode 920000. Cygma compares them against what it captured during the day.

• ResponseCode 00 – totals match; the batch is closed. Done.
• ResponseCode 95 – totals mismatch. Cygma's tape and yours disagree, so it needs the itemized batch to reconcile.

On a 95, run the two-step upload flow:

1. Post one /hostapi/batchupload/ (MTI 320) for each captured transaction in the batch – the same BatchNumber, echoing the original SystemsTraceNumber, ProcessingCode, TransactionAmount, and AuthorizationIdResponse.
2. Close with /hostapi/settlementtrailer/ (MTI 500) carrying the same count/amount totals you sent in step 1. Once the uploaded items add up to the trailer, Cygma returns 00 and the batch settles.

The totals block is four count / amount pairs. Amounts are 12-digit, zero-padded, in minor units (cents):

ResponseCode follows the ISO 8583 standard – "00" is the only happy path. "10" (partial approval) is conditionally happy: Cygma approved a smaller amount than you requested; you ll find the approved amount in TransactionAmount on the response.

On a non-approved response, ResponseDataElements.AlternteResponseText (note the typo in the spec) often carries a human-readable message from the issuer.

For POS terminals with a magstripe reader (or an EMV reader falling back to magstripe), pass the raw track data in Track1Data / Track2Data and update POSEntryMode:

• 010 manual / key-entered (default)
• 021 Track 2 read
• 022 Track 1 read
• 050 EMV chip
• 070 contactless
• 090 EMV fallback to magstripe

EMV chip & contactless – for chip reads (dip or tap), send the ICC TLV payload from the kernel in ICCSystemRelatedData (DE 55) as a hex string, alongside the chip’s track-2 image in Track2Data, with POSEntryMode 050 (contact), 070 (contactless) or 090 (fallback to magstripe). Devices that encrypt at the read head (DUKPT / P2PE) also send the KeySerialNumber in RequestDataElements; end-to-end P2PE envelopes ride DE 60 (P2PE). PIN debit adds PINData (DE 52) + SecurityControlInformation (DE 53).

Cert sandbox lives at apicert-sandbox.cygma.com:9443 (the same port as production, just a different host). Same JSON shape, same response codes, no real money moves. Ask EPI for sandbox credentials.