Boarding a Merchant with Worldpay

You can board a Worldpay merchant either through the Koard Merchant Management System (MMS) UI or programmatically via the API. Koard targets Worldpay's 610 interface (TPS / Vantage) for mPOS EMV COTS.

Worldpay assigns the merchant a Merchant ID and Terminal ID out-of-band. Those two values plus mcc are all Koard needs from the merchant. The other 610 credentials (User ID, Password, Network Routing, Bank ID) are configured by Koard once per environment.

Before You Start

Worldpay provisions merchants on their side; Koard never makes a "create merchant" call. The packet you get from Worldpay for a new merchant contains:

That's it from the merchant. The other 610 fields you may have heard about (userid, password, network_routing, bank_id) are owned by Koard and configured once per environment — never paste them into a POST /v2/terminals body.

Via the MMS

After creating the merchant account, click New Terminal and select Worldpay as the processor.

Once saved, assign the terminal to a location and generate merchant credentials as usual.

Via the API

Create Terminal — POST /v2/terminals

Request body

Example

curl https://api.uat.koard.com/v2/terminals \
  -X POST \
  -H "X-Koard-apikey: $KOARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "100200300001",
    "processor_config_id": "prc_live_worldpay_us",
    "terminal_name": "Front Counter iPhone",
    "mid": "000038462929",
    "tid": "001",
    "mcc": "5812"
  }'

Update Terminal — PUT /v2/terminals/{terminal_id}

Send a PUT with only the fields you want to change.

Batch & Settlement

The 610 spec describes Worldpay as "host capture" with "host settlement requirements" (610 §1.1.1). The integrator can drive batch release explicitly:

The spec is silent on whether Worldpay can be configured to auto-release — that would be a per-merchant boarding option not documented in the 610 reference. Koard exposes a batch_schedule on the terminal to drive Batch Release on a schedule; see Automated Batch Scheduling.

Currency & Country

The 610 base message has no wire currency field. Field 04 (Amount) is n9 cents and the spec layers on ISO 8583's "amount expressed in U.S. Dollars" (ISO 8583 §F004). Multi-currency on a USD-boarded MID is not supported by the 610 message set.

The 610 base message has no wire country field either. Country is inferred from the MID profile. For EMV transactions only, the terminal country surfaces via EMV TLV tag 9F1A inside G035 chip data; Koard builds this internally.

currency exposed at the API level defaults to USD and is reserved for future multi-currency support.

Reading the Response

A Worldpay 610 response comes back with a 21-byte TPS header prefix, the MTI, then a 2-character Bitmap Type that tells you whether the transaction was approved or declined:

The full canonical response-code list is in Appendix A of the Worldpay 610 Interface Reference Guide.

Express vs 610 vs RAFT

Worldpay offers three integration surfaces. Koard targets 610 for mPOS EMV COTS because it's the only interface in the spec that exposes device classes 6 — SoftPOS Device and 9 — MPOS explicitly in fields F25 and F107.

Gotchas

• mid and tid are top-level fields on the request — not inside var_sheet. Matches every other processor on Koard.
• userid, password, network_routing, bank_id are configured by Koard once per environment. Don't ask the merchant for these.
• The 610 wire has no currency or country field. Both are inferred from the MID. If the merchant needs multi-currency, contact Koard support — it requires Worldpay-side reconfiguration.
• MCC is not on the 610 wire either — it's held in the Worldpay merchant profile. Koard still requires it on the API for surcharge calculation and reporting.
• F22 / F25 / F107 are device-class constants (SoftPOS), set by Koard once per device class. Not configurable per merchant.

Troubleshooting

400 Bad Request on create

• Verify mid, tid, and mcc are at the top level.
• Confirm processor_config_id is a valid Worldpay config ID for your environment.

Transactions erroring with FORMAT ERROR (response code 730)

• Usually an EMV TLV issue — Worldpay's whitelist of allowed EMV tags is narrow. Capture the request body and forward to Koard support.

Transactions erroring with CALL OPER (response code 701)

• Card-side decline. Have the merchant ask the cardholder to call their bank.

Need multi-currency

• Not supported on the 610 wire as written. Requires Worldpay-side reconfiguration of the MID; contact Koard support.

Need explicit batch close

• Use batch_schedule on the terminal to schedule MTI 0500 / PC 930000 Batch Release on a recurring cadence, or trigger manually via the batch API.