MasterCard Gateway (formerly TNS) fact sheet

Quick Start

New to integrating MasterCard Gateway (formerly TNS) with Spreedly? Here's your setup guide:

1. Retrieve your MasterCard Gateway (formerly TNS) credentials:
   1. Ask your Mastercard Gateway provider for the merchant id and API password. Test and live credentials are separate.
   2. Confirm which region host the merchant uses: north_america, europe, or asia_pacific.
   3. Confirm whether the merchant is enabled for single-step Pay. If it is, set pay_mode to true when you add the gateway.
2. Get familiar with the Spreedly API:
   1. Review Spreedly API basics.
   2. Review Gateways, Payment Methods, and Transactions.
3. Add an MasterCard Gateway (formerly TNS) gateway to Spreedly in sandbox mode.

Adding a MasterCard Gateway (formerly TNS) gateway

Required Credentials

• userid: Your Mastercard Gateway merchant ID.
• password: Your Mastercard Gateway API password.

Optional Gateway Settings

• region: north_america, europe, or asia_pacific. Defaults to north_america.
• pay_mode: true sends Purchase as a single Pay request. false or omitted sends Authorize and then Capture.

Request

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>tns</gateway_type>
        <userid>Your merchant id</userid>
        <password>Your API password</password>
        <region>north_america</region>
        <pay_mode>false</pay_mode>
      </gateway>'

Response

<gateway>
  <token>IwiokZMEbaxOsNfnJorNvpPRxyz</token>
  <gateway_type>tns</gateway_type>
  <name>MasterCard Gateway (formerly TNS)</name>
  <description nil="true"/>
  <userid>Your merchant id</userid>
  <region>north_america</region>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_partial_capture type="boolean">true</supports_partial_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_partial_credit type="boolean">true</supports_partial_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_purchase type="boolean">false</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">false</supports_3dsecure_2_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    <supports_card_scheme_ntid type="boolean">true</supports_card_scheme_ntid>
    <supports_moto_exemption type="boolean">true</supports_moto_exemption>
    <supports_inquire_by_gateway_transaction_id type="boolean">true</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">true</supports_inquire_by_order_id>
  </characteristics>
  <credentials>
    <credential>
      <name>userid</name>
      <value>Your merchant id</value>
    </credential>
    <credential>
      <name>region</name>
      <value>north_america</value>
    </credential>
  </credentials>
  <gateway_settings>
    <pay_mode>false</pay_mode>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>order_certainty</gateway_specific_field>
    <gateway_specific_field>expected_number_of_captures</gateway_specific_field>
    <gateway_specific_field>agreement_id</gateway_specific_field>
    <gateway_specific_field>reference_order_id</gateway_specific_field>
    <gateway_specific_field>agreement_amount_variability</gateway_specific_field>
    <gateway_specific_field>agreement_expiry_date</gateway_specific_field>
    <gateway_specific_field>agreement_minimum_days_between_payments</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">true</sandbox>
</gateway>

Purchase

curl https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "PAYMENT_METHOD_TOKEN",
      "amount": 1000,
      "currency_code": "USD",
      "order_id": "ORDER1001",
      "email": "[email protected]",
      "ip": "203.0.113.10",
      "billing_address": {
        "name": "Jane Shopper",
        "address1": "123 Main St",
        "address2": "Apt 4",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US",
        "phone": "5555550100"
      }
    }
  }'

email is sent as customer.email. The cardholder first and last name are sent on customer. ip is sent as device.ipAddress. The billing address is sent on billing.address, with country converted to alpha-3 (US becomes USA). A shipping address is sent on shipping.address, and the shipping name is split into shipping.contact.firstName and shipping.contact.lastName.

On a two-step Purchase, card, wallet, 3DS, and stored-credential data are sent on the Authorize. The Capture sends the amount and the reference to that authorization.

Pay mode

Set pay_mode to true when the merchant profile uses single-step Pay. Purchase then sends apiOperation PAY. Authorize, Capture, Refund, Void, and Verify stay on their own operations.

Partial capture

Capture one authorization in more than one payment. Set order_certainty on the Authorize, or on a Purchase that is not in Pay mode (a Purchase sends it on the Authorize step). Set expected_number_of_captures to the same value on every Capture.

• order_certainty: Sent as order.certainty. Use FINAL when the authorized amount will not change. ESTIMATED is also accepted. (Pay mode ignores order_certainty).
• expected_number_of_captures: Sent as order.expectedNumberOfCaptures. Spreedly forwards the value you send. Whether Mastercard stops later captures and voids the uncaptured amount depends on the merchant profile. Ask your payment service provider to enable Automatically Reverse Outstanding Authorization Amounts if you need that behavior.

Authorize

curl https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/authorize.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "PAYMENT_METHOD_TOKEN",
      "amount": 500,
      "currency_code": "USD",
      "gateway_specific_fields": {
        "tns": { "order_certainty": "FINAL" }
      }
    }
  }'

Each capture, using the authorization token:

curl https://core.spreedly.com/v1/transactions/AUTHORIZATION_TOKEN/capture.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "amount": 200,
      "gateway_specific_fields": {
        "tns": { "expected_number_of_captures": "2" }
      }
    }
  }'

Partial refund

Refund part of a Purchase or Capture by sending a lower amount. No gateway specific field is required. Repeat until the captured amount is used up.

curl https://core.spreedly.com/v1/transactions/TRANSACTION_TOKEN/credit.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "amount": 200,
      "currency_code": "USD"
    }
  }'

General credit

General Credit is an unreferenced refund to a card. It sends apiOperation REFUND with the card and no prior transaction reference.

curl https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/general_credit.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "PAYMENT_METHOD_TOKEN",
      "amount": 500,
      "currency_code": "USD"
    }
  }'

A network token can be used. The token number is sent with sourceOfFunds.type``SCHEME_TOKEN. The cryptogram and ECI are omitted on General Credit.

Verify

Verify authorizes 1.00 and then voids that authorization. The Verify succeeds when the authorization succeeds, including when the void does not.

curl `https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/verify.json` \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "PAYMENT_METHOD_TOKEN",
      "currency_code": "USD"
    }
  }'

Transactions without CVV

Leave verification_value off the payment method. Spreedly omits securityCode. A blank value is omitted too. A CVV that is present is still sent.

This applies to Authorize, Purchase, Pay, Verify, Store, and General Credit. Capture does not send the card.

If the merchant profile requires CSC, Mastercard fails the transaction with INVALID_REQUEST on sourceOfFunds.provided.card.securityCode. When Mastercard returns no CSC result, the CVV result code and message are empty.

Store and remove

Store creates a Mastercard Gateway token and returns it as a Spreedly third_party_token. Use that payment method on later Authorize, Purchase, and Pay requests. Spreedly sends it as sourceOfFunds.token.

Remove deletes that gateway token. A later payment with the removed token fails.

Store and remove call the version 100 token API: POST and DELETE /version/100/merchant/USERID/token.

MOTO

Set three_ds_exemption_type to moto on Authorize or Purchase. Spreedly sends transaction.source MOTO.

On a merchant-initiated stored-credential payment, transaction.source stays MERCHANT. The MOTO source is not sent on that follow-up.

Apple Pay and Google Pay

Pass an Apple Pay or Google Pay payment method on Authorize, Purchase, or Verify.

The card security code is omitted for all three.transaction.source is INTERNET unless the transaction is MOTO or a merchant-initiated stored credential.

A missing cryptogram or ECI is left off devicePayment.On a two-step Purchase or on Verify, the wallet block is sent on the Authorize only.

A merchant-initiated Apple Pay follow-up omits devicePayment. A merchant-initiated Google Pay follow-up still sends the cryptogram.

Network tokenization

Send attempt_network_token true on Authorize, Purchase, or Verify when the payment method has a Spreedly network token. Mastercard receives:

• sourceOfFunds.type: SCHEME_TOKEN
• sourceOfFunds.provided.card.number: the token PAN
• devicePayment.onlinePaymentCryptogram: the cryptogram
• devicePayment.eciIndicator: the ECI, when the token has one

The card security code is omitted. Capture, Refund, and Void of that payment do not send the token again. A token with no cryptogram is declined by Mastercard.

The merchant account must be enabled for network tokens. See the Network tokenization guide.

Stored Credentials

Purchase, Authorize, Pay, and Verify accept Spreedly stored-credential fields. Both fields are required. An initiator with no reason type is ignored.

• stored_credential_initiator: cardholder or merchant
• stored_credential_reason_type: recurring, unscheduled, or installment

See the Stored Credentials guide.

On a two-step Purchase these values are sent on the Authorize. The Capture does not repeat them. Pay mode sends them on the Pay.

The agreement id is agreement_id when that gateway specific field is sent. Otherwise Spreedly uses customer_agreement_id. The agreement object is omitted when neither is present.

Any other reason type sends the agreement id and omits agreement.type. A follow-up sends the agreement id and omits agreement.type.

agreement_amount_variability, agreement_expiry_date, and agreement_minimum_days_between_payments are sent only on the first recurring or installment transaction, and only when an agreement id is present. agreement_amount_variability is sent in uppercase (FIXED, VARIABLE).

Spreedly stores response.network_transaction_id and the Transaction Link ID from the Authorize response. See Transaction Link ID.

reference_order_id is sent as referenceOrderId on a stored-credential request, including the first transaction.

curl https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/authorize.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "PAYMENT_METHOD_TOKEN",
      "amount": 1000,
      "currency_code": "USD",
      "stored_credential_initiator": "cardholder",
      "stored_credential_reason_type": "recurring",
      "customer_agreement_id": "AGR-1001",
      "gateway_specific_fields": {
        "tns": {
          "agreement_amount_variability": "VARIABLE",
          "agreement_expiry_date": "2031-06-30",
          "agreement_minimum_days_between_payments": 30
        }
      }
    }
  }'

Apple Pay and Google Pay use the same stored-credential mapping. On a later merchant-initiated Apple Pay payment, the cryptogram is omitted. Google Pay still sends it.

3DS Global (External Authentication Passthrough)

Spreedly sends third-party 3DS authentication on Authorize and Purchase. Gateway-specific 3DS is unavailable. For the Spreedly fields, see the 3DS2 third-party authentication guide.

3DS2 also sends the authentication.3ds2 object. 3DS1 sends authentication.3ds only. Empty authentication fields are omitted. A request with no 3DS data omits authentication.

On a two-step Purchase the authentication block is sent on the Authorize. Pay mode sends it on the Pay.

curl https://core.spreedly.com/v1/gateways/GATEWAY_TOKEN/authorize.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "PAYMENT_METHOD_TOKEN",
      "amount": 1000,
      "currency_code": "USD",
      "three_ds_version": "2.1.0",
      "three_ds": {
        "ecommerce_indicator": "05",
        "authentication_value": "mHyn+7YFi1EUAREAAAAvNUe6Hv8=",
        "directory_server_transaction_id": "a3a721f3-b6fa-4cb5-84ea-c7b5c39890a2",
        "acs_transaction_id": "c4b83204-c7fb-5dc6-95fb-d8c6d40901b3",
        "authentication_response_status": "Y"
      }
    }
  }'

Mastercard rejects an authentication value it does not accept. The transaction fails with INVALID_REQUEST. A transactionStatus of N is passed through, and the authorization fails when Mastercard declines it.

Inquire (Transaction Status Retrieval)

Spreedly can retrieve the current Mastercard result for Purchase, Authorize, Verify, and Refund.

• With a gateway_transaction_id, Spreedly retrieves that order and transaction.
• Without one, Spreedly retrieves the order. The order id is the order_id from the original transaction, or the Spreedly transaction token when no order_id was sent.

An order lookup that finds no matching transaction leaves the Spreedly transaction unchanged. The same is true when Mastercard returns ERROR, PENDING, or UNKNOWN, or gateway code ACQUIRER_SYSTEM_ERROR, SUBMITTED, SYSTEM_ERROR, TIMED_OUT, or UNKNOWN.

A declined result updates the transaction to failed. SUCCESS confirms the original success. After an authorization is captured, a lookup of that authorization still reads the authorization.

Gateway Specific Fields

Gateway Specific Response Fields

A response may contain these fields under gateway_specific_response_fields.tns. A field is present when Mastercard returns it. On a two-step Purchase or on Verify, the values come from the Authorize response.

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
    <tns>
      <authorization_code>22376</authorization_code>
      <transaction_identifier>123456789</transaction_identifier>
      <financial_network_code>MCC</financial_network_code>
      <financial_network_date>2026-10-14</financial_network_date>
    </tns>
  </gateway_specific_response_fields>
</transaction>

These standard response fields are separate from the gateway specific block:

gateway_transaction_id is the Mastercard order id and transaction id, joined with |.

Additional resources