paymentInstrument Object Reference

A unified object for submitting all supported payment methods — cards, digital wallets, tokens, and alternative payments — through a single consistent API shape.

---

The paymentInstrument object is a unified, flexible structure for submitting payment details across all supported payment methods. It replaces older flat card fields (pan, cvv, cardHolderName, etc.) with a consistent shape that works regardless of payment type.

---

Object Structure

{
  "paymentInstrument": {
    "type": "PAN",
    "subType": "CREDIT_CARD",
    "instrumentData": {
      "instrumentMetadata": {
        "name": "John Doe",
        "expiryMonth": "12",
        "expiryYear": "2027"
      },
      "panData": {
        "pan": "4111111111111111",
        "cvv": "123"
      }
    }
  }
}

Top-level Fields

Field	Type	Required	Description
type	string	Yes	Identifies the payment instrument. See Supported Types.
subType	string	Conditional	Further qualifies the type. Required for certain types. See Type & subtype Reference.
instrumentData	object	Yes	Container for all instrument-specific data and common metadata.

---

Supported Types

Type	Description
PAN	Direct card entry using a card number (PAN).
APPLE_PAY	Apple Pay payment token.
GPAY	Google Pay payment token.
INSTRUMENT_TOKEN	Previously tokenised card or digital wallet.
CLICK_TO_PAY	Mastercard Click to Pay.
SCHEME_TOKEN	Network / scheme-level token.

---

Type & subtype Reference

type	Valid subType values	Notes
PAN	CREDIT_CARD, DEBIT_CARD, CARD	CARD when card category is not known.
APPLE_PAY	CARD, VALIDATE_MERCHANT	VALIDATE_MERCHANT for merchant validation flow only.
GPAY	CARD
INSTRUMENT_TOKEN	CARD_TOKEN

---

instrumentData

The instrumentData object holds all payment details. It has two parts:

1. instrumentMetadata — Common fields shared across multiple instrument types. Mandatory when using the paymentInstrument object. name is always required; other fields are conditionally required depending on the payment instrument type.
2. Type-specific data object — e.g. panData, payIdData, applePayData, etc. Include only the object matching your type.

instrumentMetadata (Common Fields)

Field	Type	Description
name	string	Cardholder or instrument holder name.
expiryDate	string	Full expiry date of the instrument.
expiryMonth	string	Expiry month (e.g. "12").
expiryYear	string	Expiry year (e.g. "2027").
instrumentDescription	string	Optional free-text description of the instrument.

---

PAN — Direct Card Entry

Use when the customer enters their card number directly.

Required type: PAN
Recommended subType: CREDIT_CARD or DEBIT_CARD
Data object: panData

panData Fields

Field	Type	Max Length	Required	Description
pan	string	19	Yes	The card number (PAN).
cvv	string	4	No	Card CVV or CVC security code.

Example

{
  "paymentInstrument": {
    "type": "PAN",
    "subType": "CREDIT_CARD",
    "instrumentData": {
      "instrumentMetadata": {
        "name": "Jane Smith",
        "expiryMonth": "09",
        "expiryYear": "2026"
      },
      "panData": {
        "pan": "4111111111111111",
        "cvv": "737"
      }
    }
  }
}

---

INSTRUMENT_TOKEN — Saved Token

Use when charging against a previously tokenised card or digital wallet. Tokens are created via the Tokenisation API.

Required type: INSTRUMENT_TOKEN
Required subType: CARD_TOKEN, APPLE_PAY, or GOOGLE_PAY
Data object: tokenData

tokenData Fields

Field	Type	Required	Description
instrumentToken	string	Yes	The token value returned when the instrument was created.

Example

{
  "paymentInstrument": {
    "type": "INSTRUMENT_TOKEN",
    "subType": "CARD_TOKEN",
    "instrumentData": {
      "tokenData": {
        "instrumentToken": "tok_4f2a1c9e83b7d061f52e"
      }
    }
  }
}

---

APPLE_PAY

Use when processing an Apple Pay payment. Pass the payment token payload returned by the Apple Pay JS/Native SDK directly — do not decrypt it.

Required type: APPLE_PAY
Required subType: CARD (or VALIDATE_MERCHANT for merchant validation)
Data object: applePayData

applePayData Structure

The applePayData object mirrors the PKPaymentToken structure returned by Apple's SDK.

Field	Type	Required	Description
token	object	Yes	The payment token object from Apple Pay.
token.transactionIdentifier	string	Yes	Unique transaction ID from Apple.
token.paymentData	object	Yes	Encrypted payment data.
token.paymentData.version	string	Yes	Encryption protocol version (e.g. "EC_v1").
token.paymentData.data	string	Yes	Base64-encoded encrypted payment data.
token.paymentData.signature	string	Yes	CMS signature for verification.
token.paymentData.header	object	Yes	Encryption header metadata.
token.paymentData.header.ephemeralPublicKey	string	Yes	Ephemeral EC public key.
token.paymentData.header.publicKeyHash	string	Yes	Hash of the merchant's public key.
token.paymentData.header.transactionId	string	Yes	Transaction ID used during encryption.
token.paymentMethod	object	Yes	Details about the card used.
token.paymentMethod.displayName	string	Yes	Masked card name (e.g. "Visa 1234").
token.paymentMethod.network	string	Yes	Card network (e.g. "Visa", "Mastercard").
token.paymentMethod.type	string	Yes	Instrument type (e.g. "CARD").
billingContact	object	No	Customer billing address from the Apple Pay sheet.
shippingContact	object	No	Customer shipping address from the Apple Pay sheet.

Example

{
  "paymentInstrument": {
    "type": "APPLE_PAY",
    "subType": "CARD",
    "instrumentData": {
      "applePayData": {
        "token": {
          "transactionIdentifier": "ABCDEF1234567890",
          "paymentData": {
            "version": "EC_v1",
            "data": "base64encodedEncryptedData==",
            "signature": "base64encodedSignature==",
            "header": {
              "ephemeralPublicKey": "base64encodedKey==",
              "publicKeyHash": "base64encodedHash==",
              "transactionId": "abc123transactionid"
            }
          },
          "paymentMethod": {
            "displayName": "Visa 1234",
            "network": "Visa",
            "type": "CARD"
          }
        },
        "billingContact": {
          "givenName": "John",
          "familyName": "Doe",
          "addressLines": ["123 Main St"],
          "locality": "Sydney",
          "administrativeArea": "NSW",
          "postalCode": "2000",
          "country": "Australia",
          "countryCode": "AU"
        }
      }
    }
  }
}

---

GPAY — Google Pay

Use when processing a Google Pay payment. Pass the payment token object returned by the Google Pay API directly.

Required type: GPAY
Required subType: CARD
Data object: gPayData

gPayData Structure

The gPayData object mirrors the PaymentData response from the Google Pay API.

Field	Type	Required	Description
apiVersion	integer	Yes	Google Pay API major version (e.g. 2).
apiVersionMinor	integer	Yes	Google Pay API minor version (e.g. 0).
merchantId	string	No	Merchant ID registered with Google Pay.
paymentMethodData	object	Yes	Payment method details.
paymentMethodData.description	string	No	Masked payment descriptor (e.g. "Visa •••• 1234").
paymentMethodData.type	string	Yes	Always "CARD".
paymentMethodData.info	object	No	Card metadata.
paymentMethodData.info.cardDetails	string	No	Last 4 digits of the card.
paymentMethodData.info.cardNetwork	string	No	Card network (e.g. "Visa").
paymentMethodData.tokenizationData	object	Yes	The encrypted token payload.
paymentMethodData.tokenizationData.type	string	Yes	Tokenisation type (e.g. "PAYMENT_GATEWAY" or "DIRECT").
paymentMethodData.tokenizationData.token	object	Yes	Encrypted payment token.

Example

{
  "paymentInstrument": {
    "type": "GPAY",
    "subType": "CARD",
    "instrumentData": {
      "gPayData": {
        "apiVersion": 2,
        "apiVersionMinor": 0,
        "paymentMethodData": {
          "description": "Visa •••• 1111",
          "type": "CARD",
          "info": {
            "cardDetails": "1111",
            "cardNetwork": "Visa"
          },
          "tokenizationData": {
            "type": "DIRECT",
            "token": {
              "signature": "crypto-string",
              "protocolVersion": "ECv2",
              "intermediateSigningKey": {
                "signedKey": "json-string",
                "signatures": ["signature1"]
              },
              "signedMessage": "json-string"
            }
          }
        }
      }
    }
  }
}

---

CLICK_TO_PAY — Mastercard Click to Pay

Use for Mastercard Click to Pay transactions.

Required type: CLICK_TO_PAY
Data object: mastercardData

note

Contact your integration team for field details and enablement.

---

SCHEME_TOKEN — Network Token

Use when submitting a scheme-level network token (e.g. a token issued directly by Visa or Mastercard).

Required type: SCHEME_TOKEN
Data object: schemeTokenData

note

Contact your integration team for field details and enablement.

---

Encoded Payloads

For APPLE_PAY and GPAY, only the encoded (encrypted) payload is supported:

Mode	Description	When to use
Encoded	Pass the raw encrypted token payload as received from Apple/Google SDK. Connected Payments handles decryption.	Required for all integrations.

For all other types (PAN, INSTRUMENT_TOKEN, CLICK_TO_PAY, SCHEME_TOKEN), there is no encoded/decoded distinction — the structure is the same in all cases.

---

Quick-Start Examples by Use Case

Checkout with a new card

{
  "paymentInstrument": {
    "type": "PAN",
    "subType": "CREDIT_CARD",
    "instrumentData": {
      "instrumentMetadata": {
        "name": "Jane Smith",
        "expiryMonth": "11",
        "expiryYear": "2028"
      },
      "panData": {
        "pan": "5105105105105100",
        "cvv": "123"
      }
    }
  }
}

Checkout with a saved card token

{
  "paymentInstrument": {
    "type": "INSTRUMENT_TOKEN",
    "subType": "CARD_TOKEN",
    "instrumentData": {
      "tokenData": {
        "instrumentToken": "tok_4f2a1c9e83b7d061f52e"
      }
    }
  }
}

Apple Pay checkout

{
  "paymentInstrument": {
    "type": "APPLE_PAY",
    "subType": "CARD",
    "instrumentData": {
      "applePayData": {
        "token": {
          "...": "Apple Pay SDK response"
        }
      }
    }
  }
}