Skip to navigation
Payment Services

The Basics

The ProcessTransaction API is the recommended way to process payments through Payment Services. It provides access to a wide range of payment gateways with a normalized response format, making it easier to handle transactions consistently across different processors.

Overview

The ProcessTransaction API offers several advantages for payment processing:

  • Gateway flexibility — Switch or add payment processors without changing your integration
  • Normalized responses — Receive consistent response structures with pre-parsed AVS and CVV results
  • Token portability — Use the same tokens across any supported gateway
  • Flexible tokenization — Use existing tokens or tokenize new cards during the transaction
  • CVV injection — Include previously collected CVV values without storing them yourself
Why ProcessTransaction API?

For most integrations, the ProcessTransaction API provides the best balance of gateway coverage, ease of integration, and response consistency. Choose the Card/Check/Wallet API only if you need access to complete, raw gateway responses.

How It Works

When you send a transaction request, Payment Services:

  1. Receives your request with the TokenEx token and gateway-specific parameters
  2. Detokenizes the token to retrieve the original PAN
  3. Formats the request according to your gateway’s requirements
  4. Sends the transaction to the payment processor
  5. Parses the response and returns a normalized result with AVS/CVV details

Endpoints

EndpointPathWhen to Use
ProcessTransaction/PaymentServices.svc/REST/ProcessTransactionUse with existing TokenEx tokens: recurring billing, follow-up transactions (capture, refund, void)
ProcessTransactionAndTokenize/PaymentServices.svc/REST/ProcessTransactionAndTokenizeUse with PANs or encrypted PANs: first-time transactions, guest checkout, card data migration
Choosing between endpoints

If you’re using TokenEx iFrame or mobile SDK, cards are typically tokenized during collection—use ProcessTransaction. If you’re receiving PANs directly (from a migration or encrypted source), use ProcessTransactionAndTokenize to tokenize and transact in one call.

Authentication

Both endpoints use request body authentication. Include your credentials in every request:

ParameterTypeRequiredDescription
APIKeystringYesYour TokenEx API key
TokenExIDstringYesYour TokenEx account ID
{
  "APIKey": "your-api-key",
  "TokenExID": "your-tokenex-id",
  "TransactionType": 1,
  "TransactionRequest": {
    // ... gateway and transaction parameters
  }
}
Keep credentials secure

Never expose your APIKey in client-side code. All Payment Services requests should originate from your server.

Transaction Types

Specify the type of transaction using the TransactionType parameter:

ValueTypeDescriptionWhen to Use
1AuthorizeVerifies funds and places a hold without capturingUse for orders that ship later; capture when fulfilling
2CaptureCaptures a previously authorized transactionUse after authorization when ready to collect payment
3PurchaseAuthorizes and captures in a single requestUse for immediate fulfillment (digital goods, in-store)
4RefundReturns funds to the customerUse to return money for completed transactions
5VoidCancels a transaction before settlementUse to cancel authorizations or same-day transactions
6ReverseAttempts void, falls back to refund if settledUse when unsure if transaction has settled
Authorize vs Purchase

Use Authorize (1) followed by Capture (2) when there’s a delay between order placement and fulfillment—this is common for physical goods. Use Purchase (3) for immediate transactions like digital downloads or in-person sales.

Request Structure

Both endpoints use the same request format. The TransactionRequest object contains nested objects for gateway credentials, card data, and transaction details.

{
  "APIKey": "your-api-key",
  "TokenExID": "your-tokenex-id",
  "TransactionType": 1,
  "TransactionRequest": {
    "gateway": {
      "name": "YourGatewayName",
      "login": "your-gateway-login",
      "password": "your-gateway-password"
    },
    "credit_card": {
      "number": "your-tokenex-token",
      "month": "12",
      "year": "2029",
      "verification_value": "cvv"
    },
    "transaction": {
      "amount": 999,
      "order_id": "order-12345",
      "billing_address": {
        "name": "Alex Smith",
        "address1": "123 Main Street",
        "city": "Tulsa",
        "state": "OK",
        "zip": "74119"
      }
    }
  }
}

Request Parameters:

ParameterTypeRequiredDescription
APIKeystringYesYour TokenEx API key
TokenExIDstringYesYour TokenEx account ID
TransactionTypeintegerYesTransaction type (1-6, see table above)
TransactionRequestobjectYesContains gateway, credit_card, and transaction objects

Additional parameters for ProcessTransactionAndTokenize:

ParameterTypeRequiredDescription
TokenSchemestringYesThe token format to generate. See Token Schemes
EncryptedbooleanNoSet to true if the PAN is encrypted. Default: false
Token vs PAN

Use ProcessTransaction when credit_card.number contains a TokenEx token. Use ProcessTransactionAndTokenize when it contains a PAN (or encrypted PAN) that needs tokenization.

The exact fields within each nested object vary by gateway. See Gateway Parameters for the specific structure required by your payment processor.

Response Structure

Both endpoints return the same response structure:

{
  "Success": true,
  "TransactionResult": true,
  "ReferenceNumber": "15102913382030662954",
  "Authorization": "123456;A",
  "Message": "Transaction Approved",
  "Error": "",
  "AVS_Result": {
    "Code": "Y",
    "Message": "Street address and postal code match",
    "PostalMatch": "Y",
    "StreetMatch": "Y"
  },
  "CVV_Result": {
    "Code": "M",
    "Message": "CVV matches"
  },
  "Params": [
    {
      "Key": "AuthorizationCode",
      "Value": "A12345"
    },
    {
      "Key": "TransactionID",
      "Value": "7891011121314"
    }
  ],
  "Token": "411111XXXXXX1111",
  "Test": false
}

Response Parameters:

ParameterTypeDescription
Successbooleantrue if TokenEx successfully communicated with the gateway. false indicates a connectivity or configuration issue—check Error for details.
TransactionResultbooleantrue if the gateway approved the transaction. false typically means declined—check Message and Params for details.
ReferenceNumberstringTokenEx reference number for this transaction. Use this for support inquiries.
AuthorizationstringCombined authorization data from the gateway. Use this value for follow-up transactions (capture, void, refund).
MessagestringHuman-readable message from the gateway (e.g., “Transaction Approved”, “Insufficient Funds”).
ErrorstringError details if Success is false. Empty string on success.
AVS_ResultobjectAddress Verification System results with Code, Message, PostalMatch, and StreetMatch.
CVV_ResultobjectCard Verification Value results with Code and Message.
ParamsarrayKey-value pairs containing additional gateway-specific response data. Contents vary by gateway.
Tokenstring(ProcessTransactionAndTokenize only) The newly created TokenEx token for the card.
Testbooleantrue if this was a test/sandbox transaction.

Understanding Success vs TransactionResult

The response contains two boolean fields that indicate different things:

FieldMeaning
SuccessDid TokenEx successfully send the request to the gateway and receive a response?
TransactionResultDid the gateway approve the transaction?

Common scenarios:

SuccessTransactionResultMeaning
truetrueTransaction approved
truefalseTransaction declined by gateway (check Message)
falsefalseCommunication error with gateway (check Error)
Always save the Authorization

When TransactionResult is true, save the Authorization value. You’ll need it for any follow-up transactions like captures, voids, or refunds.

CVV Injection

If you collected the CVV separately using TokenEx (for example, through the iFrame with CVV-only collection), you can inject it into the transaction without handling the value directly.

To use CVV injection, set the verification_value field to the literal string "cvv":

{
  "APIKey": "your-api-key",
  "TokenExID": "your-tokenex-id",
  "TransactionType": 1,
  "TransactionRequest": {
    "gateway": {
      "name": "YourGatewayName",
      "login": "your-gateway-login",
      "password": "your-gateway-password"
    },
    "credit_card": {
      "number": "your-tokenex-token",
      "month": "12",
      "year": "2029",
      "verification_value": "cvv"
    },
    "transaction": {
      "amount": 999,
      "order_id": "order-12345"
    }
  }
}

Payment Services will replace "cvv" with the actual CVV value associated with the token before sending to the gateway.

CVV storage duration

CVV values are stored temporarily and associated with the token during collection. Check with TokenEx support for CVV retention policies in your configuration.

Common Transaction Flows

Authorize Then Capture

For orders where fulfillment is delayed (e.g., physical goods):

Step 1: Authorize

{
  "APIKey": "your-api-key",
  "TokenExID": "your-tokenex-id",
  "TransactionType": 1,
  "TransactionRequest": {
    "gateway": {
      "name": "YourGatewayName",
      "login": "your-gateway-login",
      "password": "your-gateway-password"
    },
    "credit_card": {
      "number": "your-tokenex-token",
      "month": "12",
      "year": "2029",
      "verification_value": "cvv"
    },
    "transaction": {
      "amount": 9999,
      "order_id": "order-12345"
    }
  }
}

Step 2: Capture (when ready to ship)

{
  "APIKey": "your-api-key",
  "TokenExID": "your-tokenex-id",
  "TransactionType": 2,
  "TransactionRequest": {
    "gateway": {
      "name": "YourGatewayName",
      "login": "your-gateway-login",
      "password": "your-gateway-password"
    },
    "transaction": {
      "authorization": "123456;A",
      "amount": 9999
    }
  }
}

Purchase with New Card

For immediate transactions with a new card (tokenize and purchase together):

{
  "APIKey": "your-api-key",
  "TokenExID": "your-tokenex-id",
  "TransactionType": 3,
  "TokenScheme": "sixTOKENfour",
  "TransactionRequest": {
    "gateway": {
      "name": "YourGatewayName",
      "login": "your-gateway-login",
      "password": "your-gateway-password"
    },
    "credit_card": {
      "number": "4111111111111111",
      "month": "12",
      "year": "2029",
      "verification_value": "123"
    },
    "transaction": {
      "amount": 999,
      "order_id": "order-12345"
    }
  }
}

The response includes both the transaction result and a Token for future use.

Refund a Transaction

To return funds after settlement:

{
  "APIKey": "your-api-key",
  "TokenExID": "your-tokenex-id",
  "TransactionType": 4,
  "TransactionRequest": {
    "gateway": {
      "name": "YourGatewayName",
      "login": "your-gateway-login",
      "password": "your-gateway-password"
    },
    "transaction": {
      "authorization": "123456;A",
      "amount": 999
    }
  }
}

Testing

Use your gateway’s test/sandbox environment during development:

  1. Configure your Payment Services request for the test environment
  2. Use test card numbers and any specific values provided by your gateway
Test mode indicator

When processing test transactions, the response will include "Test": true. Always verify this field is false before going live.

Next Steps