Network Token Payments

Network token payments let you authorize a card payment with a scheme token instead of the customer’s primary account number. Use this flow when your payment stack receives a tokenized card credential from a token service provider, issuer, wallet, or payment orchestration platform.

When to use this flow

Use network token payments when you can provide:

A network token, also known as a DPAN.
The token expiry date.
A token cryptogram, such as a TAVV or DSRP cryptogram, when supplied by the token service provider or wallet.
3D Secure authentication values, such as CAVV and ECI, when your authentication flow produced them.

For Apple Pay and Google Pay integrations where you receive a decrypted external payment network payload, see Decrypted wallet payloads.

Request fields

Send network token payments through POST /order with transactionMethod set to card.

Field	Required	Description
`networkTokenType`	Yes	Token scheme or token service provider. Accepted values are `MDES`, `VTS`, `APPLE`, `GOOGLE`, and `SAMSUNG`.
`networkToken`	Yes	The network token value, also known as the DPAN. Send 12 to 19 digits. Spaces and dashes are ignored.
`cardExpiryDate`	Yes	Token expiry date in `MM/YY` format.
`networkTokenCryptogram`	No	Token cryptogram. Send TAVV or DSRP cryptograms in this field when available.
`networkTokenEci`	No	Electronic Commerce Indicator associated with the network token.
`cavv`	No	Cardholder Authentication Verification Value from a 3D Secure authentication. This is separate from the token cryptogram.
`eci`	No	3D Secure ECI value.
`xid`	No	3D Secure transaction identifier, when available.
`threeDSProtocolVersion`	No	3D Secure protocol version, for example `2.2.0`.
`threeDsType`	No	Authentication type or result classification from your 3D Secure provider.

Do not send cardId with networkTokenType. A network token payment uses the supplied DPAN and cryptogram data instead of a saved xMoney card token.

cardCvv is not required for network token payments.

Cryptogram mapping

Different partners and token providers use different names for cryptograms. In xMoney requests, map them as follows:

Partner or network term	xMoney field
Network token, DPAN	`networkToken`
TAVV	`networkTokenCryptogram`
DSRP cryptogram	`networkTokenCryptogram`
Token ECI	`networkTokenEci`
CAVV	`cavv`
3DS ECI	`eci`

If you have both a token cryptogram and CAVV, send both. They represent different parts of the authorization context.

Example request

curl -X POST "https://api-stage.xmoney.com/order" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "amount=10.00" \
  -d "currency=EUR" \
  -d "orderType=purchase" \
  -d "customerId=12345" \
  -d "transactionMethod=card" \
  -d "cardTransactionMode=authAndCapture" \
  -d "cardExpiryDate=12/28" \
  -d "networkTokenType=VTS" \
  -d "networkToken=4111111111111111" \
  -d "networkTokenCryptogram=AgAAAAAAAIR8CQrXcIhbQAAAAAA=" \
  -d "networkTokenEci=05" \
  -d "cavv=AkZO5XQAA0rhBxoaufa+MAABAAA=" \
  -d "eci=05" \
  -d "ip=203.0.113.10"

Example response

The create order response uses the standard order response structure. If the payment requires a redirect or 3D Secure step, the response includes redirect details.

{
  "code": 201,
  "message": "Created",
  "data": {
    "orderId": 67890,
    "transactionId": 123456,
    "is3d": 0,
    "isRedirect": false
  }
}

Network transaction ID

For standard xMoney stored-card payments, you do not need to send these fields. xMoney handles card tokenization and the required merchant-initiated transaction data internally.

Send the original scheme reference only when tokenization happens outside xMoney and your integration is responsible for chaining subsequent stored-credential or merchant-initiated payments:

networkTransactionId: the network transaction identifier from the original transaction.
networkTransactionDate: the original transaction date as a Unix timestamp in milliseconds.

These fields are optional. If you send one of them, both fields must be supplied together. To retrieve the network transaction ID returned by the provider, call GET /transaction/{id} and read data.components[].providerNetworkTransactionId.

See Recurring payments for more on merchant-initiated payment flows.