Reference

json

Restful API

Automated Clearing House, or ACH, is an electronic network for the secure transfer of payments between U.S. financial institutions. The ACH network is governed by rules and regulations established by NACHA (formerly the National Automated Clearing House Association) and the Federal Reserve.

ACH transactions are classified into categories based on the way a payment is presented and the type of account it is linked to. These categories are represented by Standard entry class (SEC) codes. The SEC codes supported by the Worldpay Total platform are:

  • CORPORATE_CASH_DISBURSEMENT - Corporate credit or debit. Primarily used for business-to-business transactions.
  • POINT_OF_SALE - Point-of-sale. A debit at an electronic terminal initiated by use of a plastic card. An example is using a debit card to purchase gas.
  • PREARRANGED_PAYMENT_OR_DEPOSIT - Prearranged payment and deposits. Used to credit or debit a consumer account. Commonly used for payroll direct deposits and preauthorized bill payments.
  • TELEPHONE_INITIATED - Telephone-initiated entry. Oral authorization by telephone to issue an ACH payment such as a phone check. (This code is allowed for inbound telephone orders only. NACHA disallows the use of this code for outbound telephone solicitations unless a prior business arrangement with the customer has been established.)
  • WEB_INITIATED - Web-initiated entry. Electronic authorization through the Internet to initiate an ACH payment.
  • POP - Point-of-purchase. A physical check presented in person to a merchant is converted to an ACH transaction.
  • You can use checking account information to process an ACH payment through the API. The transactions are very similar to Credit Card transactions; however, check transactions do not support as many transaction types. The methods supported for ACH check transactions through the API are Charge, Verify, Void and Credit. All ACH Charge method calls include a Check object and an amount as parameters; in addition, some SEC codes require additional objects to communicate information related to that SEC transaction. The following sections will demonstrate the use of these methods and objects with regard to ACH processing.

    Pay by Check

    POST: Pay by Check

    The first example below demonstrates the use of the Charge method with the check object. This call authorizes the transaction and, if successful, captures it.

    POST https://gwapi.demo.securenet.com/api/Payments/Charge

    Sample Code

    {
      amount: 10.00,
      check: {
        firstName: REPLACE_ME,
        lastName: REPLACE_ME,
        routingNumber: 222371863,
        accountNumber: 123456
      },
       developerApplication: {
         developerId:12345678,
         version:'1.2'
       }
    }
    

    Authorization Request Parameters

    name type description
    required:
    amount decimal amount to charge the account.
    check object required to charge a check; contains check-specific data.
    developerApplication object contains developer Id and version information related to the integration.
    conditional:
    paymentVaultToken object data from a Vault payment account. Required for transactions where a Vault token is sent in the place of card or check data.
    optional:
    addToVault boolean

    indicates whether the card object is to be added to the vault to be stored as a token.

    addToVaultOnFailure boolean

    indicates whether the card object is to be added to the vault to be stored as a token even if the attempted authorization is declined.

    cashBackAmount decimal

    typically used as an optional field for pin debit processing. The value of cashBackAmount indicates the amount in cash to be given back to the customer during card processing.

    allowPartialCharges boolean

    indicates whether it is permissible to authorize less than the total balance available on a prepaid card.

    extendedInformation object

    additional data to assist in reporting, ecommerce or moto transactions, and level 2 or level 3 processing. Includes user-defined fields and invoice-related information.

    transactionDuplicateCheckIndicator int

    indicates how checks for duplicate transactions should behave. Duplicates are evaluated on the basis of amount, card number, and order ID; these evaluation criteria can be extended to also include customer ID, invoice number, or a user-defined field. Valid values for this parameter are:

    0 - No duplicate check
    1 - Exception code is returned in case of duplicate
    2 - Previously existing transaction is returned in case of duplicate
    3 - Check is performed as above but without using order ID, and exception code is returned in case of duplicate

    The transactionDuplicateCheckIndicator parameter must be enabled in the Virtual Terminal under Tools->Duplicate Transactions. Duplicates are checked only for APPROVED transactions.

    orderId string client-generated unique ID for each transaction, used as a way to prevent the processing of duplicate transactions. The orderId must be unique to the merchant's SecureNet ID; however, uniqueness is only evaluated for APPROVED transactions and only for the last 30 days. If a transaction is declined, the corresponding orderId may be used again.

    The orderId is limited to 25 characters; e.g., “CUSTOMERID MMddyyyyHHmmss”.
    name type description
    required:
    WPYPaymentCharge object Charge request object containing all of the information needed to charge a payment.

    Response Parameters

    name type description
     
    result fixed string result of the method call.
    responseCode fixed string response code for the method call.
    message string text description of the response.
    transaction object detailed information about the transaction including but not limited to transaction ID and authorization code.
    emvResponse object emvResponse values are returned from the card issuer during authorization
    nametypedescription
     
    WPYPaymentResponse object detailed information about the transaction, including but not limited to: transaction id; authorization code; avs result code; and cvv result code.

    Charge an Account Using POS

    POST: Charge an account using POINT OF SALE

    When the SEC code POINT_OF_SALE is used, the AdditionalTerminalInfo object must be sent with the transaction to identify the terminal information. The example below demonstrates how to include this object with the ACH Charge request.

    POST https://gwapi.demo.securenet.com/api/Payments/Charge

    Sample Code

    {
      amount: 11.00,
      check: {
        firstName: REPLACE_ME,
        lastName: REPLACE_ME,
        routingNumber: '222371863',
        accountNumber: '147852',
        checkNumber: '107',
        accountType: 'SAVINGS',
        checkType: 'POINT_OF_SALE',
        verification: 'NONE',
      },
      extendedInformation: {
        additionalTerminalInfo: {
          terminalId: '1234',
          terminalCity: 'Austin',
          terminalState: 'TX',
          terminalLocation: 'Office',
          storeNumber: '452'
        }
      },
       developerApplication:{
        developerId:12345678,
        version:'1.2'
       }	
    }
    

    Authorization Request Parameters

    name type description
    required:
    amount decimal amount to charge the account.
    check object required to charge a check; contains check-specific data.
    extendedInformation object

    additional data to assist in reporting, ecommerce or moto transactions, and level 2 or level 3 processing. Includes user-defined fields and invoice-related information. The additionalTerminalInfo object must be used to pass extra terminal information in the case of a POINT_OF_SALE check transaction.

    developerApplication object contains developer Id and version information related to the integration.
    conditional:
    paymentVaultToken object data from a Vault payment account. Required for transactions where a Vault token is sent in the place of card or check data.
    optional:
    addToVault boolean

    indicates whether the card object is to be added to the vault to be stored as a token.

    addToVaultOnFailure boolean

    indicates whether the card object is to be added to the vault to be stored as a token even if the attempted authorization is declined.

    transactionDuplicateCheckIndicator int

    indicates how checks for duplicate transactions should behave. Duplicates are evaluated on the basis of amount, card number, and order ID; these evaluation criteria can be extended to also include customer ID, invoice number, or a user-defined field. Valid values for this parameter are:

    0 - No duplicate check
    1 - Exception code is returned in case of duplicate
    2 - Previously existing transaction is returned in case of duplicate
    3 - Check is performed as above but without using order ID, and exception code is returned in case of duplicate

    The transactionDuplicateCheckIndicator parameter must be enabled in the Virtual Terminal under Tools->Duplicate Transactions. Duplicates are checked only for APPROVED transactions.

    orderId string client-generated unique ID for each transaction, used as a way to prevent the processing of duplicate transactions. The orderId must be unique to the merchant's SecureNet ID; however, uniqueness is only evaluated for APPROVED transactions and only for the last 30 days. If a transaction is declined, the corresponding orderId may be used again.

    The orderId is limited to 25 characters; e.g., “CUSTOMERID MMddyyyyHHmmss”.
    name type description
    required:
    WPYPaymentCharge object Charge request object containing all of the information needed to charge a payment.

    Response Parameters

    name type description
     
    result fixed string result of the method call.
    responseCode fixed string response code for the method call.
    message string text description of the response.
    transaction object detailed information about the transaction including but not limited to transaction ID and authorization code.
    nametypedescription
     
    WPYPaymentResponse object detailed information about the transaction, including but not limited to: transaction id; authorization code; avs result code; and cvv result code.

    Add Billing Address

    POST: Pay by Check and Include the Billing Address

    When performing an ACH transaction, some merchants may wish to include the street address from the check for reporting or record-keeping purposes. The example below demonstrates how to do so.

    POST https://gwapi.demo.securenet.com/api/Payments/Charge

    Sample Code

    {
      amount: 10.00,
      check: {
        firstName: REPLACE_ME,
        lastName: REPLACE_ME,
        routingNumber: 222371863,
        accountNumber: 123456,
        address: {
          line1: '123 Main St.',
          city: 'Austin',
          state: 'TX',
          zip: '78759'
        },
        
      },
      developerApplication: {
        developerId: 12345678,
        version: '1.2'
      }
    }
    

    Authorization Request Parameters

    name type description
    required:
    amount decimal amount to charge the account.
    check object required to charge a check; contains check-specific data.
    developerApplication object contains developer Id and version information related to the integration.
    conditional:
    paymentVaultToken object data from a Vault payment account. Required for transactions where a Vault token is sent in the place of card or check data.
    optional:
    addToVault boolean

    indicates whether the card object is to be added to the vault to be stored as a token.

    addToVaultOnFailure boolean

    indicates whether the card object is to be added to the vault to be stored as a token even if the attempted authorization is declined.

    cashBackAmount decimal

    typically used as an optional field for pin debit processing. The value of cashBackAmount indicates the amount in cash to be given back to the customer during card processing.

    allowPartialCharges boolean

    indicates whether it is permissible to authorize less than the total balance available on a prepaid card.

    extendedInformation object

    additional data to assist in reporting, ecommerce or moto transactions, and level 2 or level 3 processing. Includes user-defined fields and invoice-related information.

    transactionDuplicateCheckIndicator int

    indicates how checks for duplicate transactions should behave. Duplicates are evaluated on the basis of amount, card number, and order ID; these evaluation criteria can be extended to also include customer ID, invoice number, or a user-defined field. Valid values for this parameter are:

    0 - No duplicate check
    1 - Exception code is returned in case of duplicate
    2 - Previously existing transaction is returned in case of duplicate
    3 - Check is performed as above but without using order ID, and exception code is returned in case of duplicate

    The transactionDuplicateCheckIndicator parameter must be enabled in the Virtual Terminal under Tools->Duplicate Transactions. Duplicates are checked only for APPROVED transactions.

    orderId string client-generated unique ID for each transaction, used as a way to prevent the processing of duplicate transactions. The orderId must be unique to the merchant's SecureNet ID; however, uniqueness is only evaluated for APPROVED transactions and only for the last 30 days. If a transaction is declined, the corresponding orderId may be used again.

    The orderId is limited to 25 characters; e.g., “CUSTOMERID MMddyyyyHHmmss”.
    name type description
    required:
    WPYPaymentCharge object Charge request object containing all of the information needed to charge a payment.

    Response Parameters

    name type description
     
    result fixed string result of the method call.
    responseCode fixed string response code for the method call.
    message string text description of the response.
    transaction object detailed information about the transaction including but not limited to transaction ID and authorization code.
    nametypedescription
     
    WPYPaymentResponse object detailed information about the transaction, including but not limited to: transaction id; authorization code; avs result code; and cvv result code.

    Pay by Check with Verification

    POST: Pay by Check with Verification

    Check verification is available for ACH check transactions. Check verification allows businesses or individuals to validate the actual check or draft being presented, the history of the account holder, or both. Special merchant registration is required.

    POST https://gwapi.demo.securenet.com/api/Payments/Charge

    Sample Code

    {
      amount: 10.00,
      check: {
        firstName: REPLACE_ME,
        lastName: REPLACE_ME,
        routingNumber: 222371863,
        accountNumber: 123456,
        verification: 'ACH_PROVIDER'
      },
      developerApplication: {
        developerId: 12345678,
        version: '1.2'
      }
    }
        

    Authorization Request Parameters

    name type description
    required:
    amount decimal amount to charge the account.
    check object check-specific data. Required for check-based charges.
    developerApplication object contains developer Id and version information related to the integration.
    conditional:
    paymentVaultToken object data from a Vault payment account. Required for transactions where a Vault token is sent in the place of card or check data.
    optional:
    addToVault boolean

    indicates whether the card object is to be added to the vault to be stored as a token.

    addToVaultOnFailure boolean

    indicates whether the card object is to be added to the vault to be stored as a token even if the attempted authorization is declined.

    cashBackAmount decimal

    typically used as an optional field for pin debit processing. The value of cashBackAmount indicates the amount in cash to be given back to the customer during card processing.

    allowPartialCharges boolean

    indicates whether it is permissible to authorize less than the total balance available on a prepaid card.

    extendedInformation object

    additional data to assist in reporting, ecommerce or moto transactions, and level 2 or level 3 processing. Includes user-defined fields and invoice-related information.

    transactionDuplicateCheckIndicator int

    indicates how checks for duplicate transactions should behave. Duplicates are evaluated on the basis of amount, card number, and order ID; these evaluation criteria can be extended to also include customer ID, invoice number, or a user-defined field. Valid values for this parameter are:

    0 - No duplicate check
    1 - Exception code is returned in case of duplicate
    2 - Previously existing transaction is returned in case of duplicate
    3 - Check is performed as above but without using order ID, and exception code is returned in case of duplicate

    The transactionDuplicateCheckIndicator parameter must be enabled in the Virtual Terminal under Tools->Duplicate Transactions. Duplicates are checked only for APPROVED transactions.

    orderId string client-generated unique ID for each transaction, used as a way to prevent the processing of duplicate transactions. The orderId must be unique to the merchant's SecureNet ID; however, uniqueness is only evaluated for APPROVED transactions and only for the last 30 days. If a transaction is declined, the corresponding orderId may be used again.

    The orderId is limited to 25 characters; e.g., “CUSTOMERID MMddyyyyHHmmss”.

    Response Parameters

    name type description
     
    result fixed string result of the method call.
    responseCode fixed string response code for the method call.
    message string text description of the response.
    transaction object detailed information about the transaction including but not limited to transaction ID and authorization code.

    Charge using Tokenization

    POST: Charge using Tokenization

    A token which has been returned from the creation of a token using the PreVault/Card or PreVault/Check action can be used in replacement of the actual card or check account information. This token can also be added to the Vault for future re-use.

    POST https://gwapi.demo.securenet.com/api/Payments/Charge

    Sample Code

    {
      amount: 10.00,
      paymentVaultToken: {
        paymentMethodID: '1211121',
        publicKey: '278DCC4B-85FE-485D-AFDD-9927AC4CA229'
      },
      addToVault: true,
      developerApplication: {
        developerId: 12345678,
        version: '1.2'
      }
    }
    

    Authorization Request Parameters

    name type description
    required:
    amount decimal amount to charge the account.
    paymentVaultToken object data from a Vault payment account. Required for transactions where a Vault token is sent in the place of card or check data. primaryMethodId is the parameter which contains the token that is returned for the PreVault/Card or PreVault/Check action.
    developerApplication object contains developer Id and version information related to the integration.
    optional:
    addToVault boolean

    indicates whether the card object is to be added to the vault to be stored as a token

    addToVaultOnFailure boolean

    indicates whether the card object is to be added to the vault to be stored as a token even if the attempted authorization is declined.

    cashBackAmount decimal

    typically used as an optional field for pin debit processing. The value of cashBackAmount indicates the amount in cash to be given back to the customer during card processing.

    allowPartialCharges boolean

    indicates whether it is permissible to authorize less than the total balance available on a prepaid card.

    extendedInformation object

    additional data to assist in reporting, ecommerce or moto transactions, and level 2 or level 3 processing. Includes user-defined fields and invoice-related information.

    transactionDuplicateCheckIndicator int

    indicates how checks for duplicate transactions should behave. Duplicates are evaluated on the basis of amount, card number, and order ID; these evaluation criteria can be extended to also include customer ID, invoice number, or a user-defined field. Valid values for this parameter are:

    0 - No duplicate check
    1 - Exception code is returned in case of duplicate
    2 - Previously existing transaction is returned in case of duplicate
    3 - Check is performed as above but without using order ID, and exception code is returned in case of duplicate

    The transactionDuplicateCheckIndicator parameter must be enabled in the Virtual Terminal under Tools->Duplicate Transactions. Duplicates are checked only for APPROVED transactions.

    orderId string client-generated unique ID for each transaction, used as a way to prevent the processing of duplicate transactions. The orderId must be unique to the merchant's SecureNet ID; however, uniqueness is only evaluated for APPROVED transactions and only for the last 30 days. If a transaction is declined, the corresponding orderId may be used again.

    The orderId is limited to 25 characters; e.g., “CUSTOMERID MMddyyyyHHmmss”.

    Response Parameters

    name type description
     
    result fixed string result of the method call.
    responseCode fixed string response code for the method call.
    message string text description of the response.
    transaction object transaction object contains detailed information about the transaction, including but not limited to: transaction id; authorization code; avs result code; and cvv result code.

    Additional Terminal Info

    name type description
    terminalId string terminal identifier.
    terminalCity string city where the terminal is located.
    terminalState string state where the terminal is located.
    terminalLocation string additional terminal location information.
    storeNumber string store number where the terminal is located.
    deviceSerialNumber string the serial number of the POS terminal used.
    POSTerminalInputCapabilityInd string

    Indicates the input capability of the terminal. Valid values for this parameter are:

    0 - Contact
    1 - Contactless
    1 - Manual; no terminal
    2 - Magnetic stripe reader capability
    5 - Integrated circuit card (ICC) capability
    6 - Key entry only capability
    A - PAN auto-entry via contactless magnetic stripe
    B - Magnetic stripe reader and key entry capability
    C - Magnetic stripe reader, ICC, and key entry capability
    D - Magnetic stripe reader and ICC capability
    E - ICC and key entry capability
    H - ICC Reader and Contactless Capability
    M - PAN auto-entry via contactless chip

    kernalVersionNo string The version number of the kernel used to process the chip data in the transaction.
    CATIndicator int

    Value to indicate if the transaction originated from a cardholder activated terminal. Possible values are:

    0 - Not a CAT Transaction
    1 - ATM with PIN
    2 - Self-service terminal
    3 - Limited-amount terminal
    4 - In-flight commerce
    6 - Electronic commerce
    7 - Transponder transaction

    Address

    name type description
    line1 string street address.
    city string city where address is located.
    state string state where address is located; valid values are 2-character state abbreviations.
    zip string 5- or 9-digit zip code.
    country string country name. Defaults to US.
    company string company name.
    phone string phone number.

    Origin Address

    name type description
    zip string 5- or 9-digit zip code.

    Card

    name type description
    trackData string data that has been read from the card's magnetic stripe.
    number string credit card account number.
    cvv string card security code.
    expirationDate string expiration date for the card. Format: MM/YYYY.
    creditCardType string card type of the payment account.
    ksn string unaltered KSN Number from PIN pad. (Debit only.)
    pinblock string pinblock obtained from the PIN pad. (Debit only.)
    firstName string first name of the account holder.
    lastName string last name of the account holder.
    address object billing address of the account holder.
    emv object Every chip card transaction contain dozens of pieces of information to be exchanged between the card, the terminal and the acquiring bank or processors host. (EMV Only)
    signature image image of the signature of the cardholder as completed at the time of the transaction.
    email string email address of the account holder.
    emailReceipt boolean enable or disable the functionality to send reciept via email.
    contactlessIndicator string Indicates the channel in which the card was input.

    Indicates the channel in which the card was input.Valid values for this parameter are:

    0 - Contact
    1 - Contactless

    isDebit string Indicates whether the card should be processed as a debit card.

    Valid values for this parameter are:

    0 - Credit
    1 - Debit

    fallbackIndicator string

    Indicates if the chip failed and the transaction was entered as mag stripe. Valid values for this parameter are:

    0 - No Fallback
    1 - Fallback

    Check

    name type description
    accountType string

    type of checking account. Valid values are:

    CHECKING
    SAVINGS
    BUSINESS_CHECKING
    BUSINESS_SAVINGS

    Defaults to CHECKING.

    checkType string type of check payment being made. Valid values are: 

    CORPORATE_CASH_DISBURSEMENT
    POINT_OF_SALE
    PREARRANGED_PAYMENT_OR_DEPOSIT
    TELEPHONE_INITIATED
    WEB_INITIATED
    POP
    routingNumber string bank routing number.
    accountNumber string checking account number.
    checkNumber string check number.
    address object billing address of the account holder
    firstName string first name of the account holder.
    lastName string last name of the account holder.
    email string email address of the account holder.
    emailReceipt boolean enable or disable the functionality to send reciept via email.
    front string base64-encoded image of the front of the check in BMP/JPG/PNG format; optional.
    back string base64-encoded image of the back of the check in BMP/JPG/PNG format; optional.
    verification fixed string type of check verification that was used for the transaction. Valid values are:

    NONE
    ACH_PROVIDER
    CERTEGY

    Defaults to NONE. A merchant account must be enabled and registered in order to use ACH_PROVIDER or CERTEGY.

    Developer Application

    name type description
    developerId int developer ID of integrator as assigned by Worldpay.
    version string version number of the integrator's application.

    EMV

    name type description
    applicationCryptogram string Cryptogram returned by the ICC in response of the GENERATE AC command. Tag 9F26.
    applicationInterchangeProfile string Indicates the capabilities of the card to support specific functions in the application. Tag 82.
    applicationTransactionCounter string Counter maintained by the application in the ICC (incrementing the ATC is managed by the ICC). Tag 9F36.
    cardSequenceNumber string This field identifies the card when multiple plastics are associated with a single account number. Tag 5F34.
    cryptogramCashBackAmount string Secondary amount associated with the transaction representing a cashback amount. Tag 9F03.
    cryptogramInformationData string Indicates the type of cryptogram and the actions to be performed by the terminal. Tag 9F27.
    cryptogramTerminalCountryCode string Indicates the country of the terminal, represented according to ISO 3166. Tag 9F1A.
    cryptogramTransactionAmount string Clearing amount of the transaction, including tips and other adjustments. Tag 9F02.
    cryptogramTransactionDate string Local date that the transaction was authorized. Tag 9A.
    cryptogramTransactionType string Indicates the type of financial transaction, represented by the first two digits of the ISO 8583:1987 Processing Code. The actual values to be used for the Transaction Type data element are defined by the relevant payment system. Tag 9C.
    cryptogramTransactioncurrencyCode string Indicates the currency code of the transaction according to ISO 4217. Tag 5F2A.
    formFactorIndicator string Personalized on the card and carries additional information about the contactless device, its security features, and technology used to acquire the transaction. Tag 9F6E.
    issuerApplicationData string Contains proprietary application data for transmission to the issuer in an online transaction. Note: For CCD-compliant applications, Annex C, section C7 defines the specific coding of the Issuer Application Data (IAD). To avoid potential conflicts with CCD-compliant applications, it is strongly recommended that the IAD data element in an application that is not CCD-compliant should not use the coding for a CCD-compliant application. Tag 9F10.
    terminalCapabilityProfile string Indicates the card data input, CVM, and security capabilities of the terminal. Tag 9F33.
    terminalVerificationResults string Status of the different functions as seen from the terminal. Tag 95.
    track2EquivalentDataChip string Contains the data elements of track 2 according to ISO/IEC 7813, excluding start sentinel, end sentinel, and Longitudinal Redundancy Check (LRC), as follows:Primary Account Number Field Separator (Hex 'D') Expiration Date (YYMM) Service Code Discretionary Data (defined by individual payment systems) Pad with one Hex 'F' if needed to ensure whole bytes. Tag 57.
    unpredictableNumber string Value to provide variability and uniqueness to the generation of a cryptogram. Tag 9F37.
    applicationIdentifier string Identifies the application as described in ISO/IEC 7816-5. Tag 9F06.
    transactionStatusIndicator string Indicates the functions performed in a transaction. Tag 9B.
    applicationName string Preferred mnemonic associated with the AID. Tag 9F12.
    cardEntryMode string Indicates chip / contact-less / keyed / swipe, including fallback if used.
    authorizationMode string Indicates Online / Offline.
    cardholderVerification string Identifies a method of verification of the cardholder supported by the application.

    EMV Response Data

    name type description
    emvauthresponsecode string Code that defines the disposition of a message.
    issuerauthenticationdata string Data sent to the ICC for online issuer authentication.
    issuerScriptResult string Indicates the result of the terminal script processing.
    issuerscripttemplate1 string Contains proprietary issuer data for transmission to the ICC before the second GENERATE AC command.
    issuerscripttemplate2 string Contains proprietary issuer data for transmission to the ICC after the second GENERATE AC command.

    Encryption

    name type description
    encryptionMode fixed string

    type of encryption that has been applied to the cardholder information. Valid values are:

    NONE
    IDTECH_MSR
    MAGTEK_MSR
    MAGTEK_IPAD
    MIURA
    VERIFONE_VX805

    Extended Information

    name type description
    typeOfGoods string type of goods that are being purchased. Valid values are DIGITAL or PHYSICAL.
    additionalTerminalInfo object additional terminal information. Required to process checks when using the SEC code POINT_OF_SALE.
    levelTwoData object information related to level two processing.
    levelThreeData object information related to level three processing.
    deviceCode string device code of the device where the transaction originated.
    entrySource string entry source of the transaction.
    mailOrTelephoneOrderData object additional data for remote orders. Required in the case of a mail, phone, or ecommerce transaction.
    serviceData object restaurant-related transaction information.
    userDefinedFields array of userDefinedField custom user-defined fields that can be sent with the transaction for reporting purposes.
    notes string notes associated with the transaction.
    invoiceNumber string invoice number.
    invoiceDescription string invoice description.
    softDescriptor string displays a description in addition to the merchants DBA. Maximum length is 25 characters
    dynamicMCC string displays a 4 characters dynamic merchant category code.

    Installment Payment Plan : Stored Payment Plan

    name type description
    cycleType string

    time unit of billing cycle. Valid values are:

    WEEKLY
    MONTHLY
    QUARTERLY
    SEMI_ANNUALLY
    ANNUALLY

    startDate dateTime plan start date.
    dayOfTheMonth numeric day of the month on which the plan is set to bill.
    dayOfTheWeek numeric day of the week on which the plan is set to bill.
    month string month the plan is set to bill.
    frequency numeric

    frequency (in terms of cycles) with which to bill the account. Valid values are:

    If cycleType = MONTHLY: 1 - 11 (e.g., 2 = every 2 months)
    if cycleType = WEEKLY: 1 - 51 (e.g., 6 = every 6 weeks)

    For cycleType = QUARTERLY, SEMI_ANNUALLY and ANNUALLY, frequency is set to 1 automatically.

    totalAmount decimal total amount to be billed under the plan.
    numberOfPayments numeric total number of installments in the plan.
    installmentAmount decimal individual installment amount.
    balloonAmount decimal balloon amount.
    balloonPaymentAddedTo string

    indicates whether the balloon payment is to be applied to the first or last payment:

    0 - add balloon amount to first payment
    1 - add balloon amount to last payment

    remainderAmount decimal amount of the final payment.
    remainderPaymentAddedTo string

    indicates whether the remainder should be applied to the first or last payment if installments are not equally divided:

    0 - add remainder to first payment
    1 - add remainder to last payment

    active boolean sets the Plan Active or Inactive
    notes string notes associated with the plan.
    softdescriptor string displays a description in addition to the merchants DBA.
    dynamicMCC string displays a 4 characters dynamic merchant category code.
    planId int plan identifier. Auto-generated by the system and given to the merchant when the plan is added.
    nextPaymentDate dateTime next scheduled payment date.
    maxRetries int number of times to retry billing if payment is declined.
    primaryPaymentMethodId string primary payment method to be used for billing.
    secondaryPaymentMethodId string secondary payment method to be used for billing.
    userDefinedFields array of userDefinedField custom user-defined fields tied to the plan, which can be used for reporting.

    Level Three

    name type description
    products array of product details of the product(s) that make up the total transaction.
    vatData object value added tax (VAT) information.
    orderDate datetime date of the transaction.
    destinationAddress object destination address of the purchased items.
    originAddress object origin address of the purchased items.
    discountAmount decimal amount of discount applied to the purchased items.

    Level Two

    name type description
    orderDate datetime date of the transaction.
    purchaseOrder string purchase order number associated with the transaction
    dutyAmount decimal duty amount included in the transaction.
    freightAmount decimal freight amount included in the transaction.
    retailLaneNumber number lane number at which the transaction was completed in a retail environment.
    taxAmount decimal tax amount for the transaction.
    status fixed string tax status of the transaction.

    Mail or Telephone Order

    name type description
    type string

    type of transaction. valid values are:

    SINGLE_PURCHASE
    RECURRING
    INSTALLMENT

    totalNumberOfInstallments string total number of installments. Required if type is INSTALLMENT.
    currentInstallment string current installment number. Required if type is INSTALLMENT.

    Payment Vault Token

    name type description
    customerId string customer identifier.
    paymentMethodId string id of the payment method to be used for billing or token
    publicKey string Public Key used to identify the mechant.
    paymentType fixed string

    payment type that is stored or about to be stored in the Vault. Valid values are:

    CHECK
    DEBIT_CARD
    CREDIT_CARD
    FLEET_CARD
    STORED_VALUE
    UNKNOWN

    Product

    name type description
    alternateTaxId string alternate tax id.
    commodityCode string commodity code.
    discountAmount decimal discount amount.
    discountRate decimal discount rate.
    discountIndicator string discount indicator.
    grossNetIndicator string gross net indicator.
    itemCode string item code.
    itemName string item name.
    itemDescription string item description.
    unit string unit.
    unitPrice decimal unit price.
    quantity decimal quantity.
    totalAmount decimal total amount.
    taxAmount decimal tax amount.
    taxRate decimal tax rate.
    taxTypeIdentifier string tax type identifier.
    taxTypeApplied string tax type applied.
    taxable boolean indicates whether product is taxable.

    Recurring Payment Plan : Stored Payment Plan

    name type description
    amount decimal amount to be billed under the plan.
    cycleType string

    time unit of billing cycle. Valid values are:

    WEEKLY
    MONTHLY
    QUARTERLY
    SEMI_ANNUALLY
    ANNUALLY

    dayOfTheMonth numeric day of the month on which the plan is set to bill.
    dayOfTheWeek numeric day of the week on which the plan is set to bill.
    month string month the plan is set to bill.
    frequency numeric

    frequency (in terms of cycles) with which to bill the account. Valid values are:

    If cycleType = MONTHLY: 1 - 11 (e.g., 2 = every 2 months)
    if cycleType = WEEKLY: 1 - 51 (e.g., 6 = every 6 weeks)

    For cycleType = QUARTERLY, SEMI_ANNUALLY and ANNUALLY, frequency is set to 1 automatically.

    endDate datetime plan end date.
    active boolean sets the Plan Active or Inactive
    notes string notes associated with the plan.
    softdescriptor string displays a description in addition to the merchants DBA.
    dynamicMCC string displays a 4 characters dynamic merchant category code.
    planId int plan identifier. Auto-generated by the system and given to the merchant when the plan is added.
    startDate dateTime plan start date.
    nextPaymentDate dateTime next scheduled payment date.
    maxRetries int number of times to retry billing if payment is declined.
    primaryPaymentMethodId string primary payment method to be used for billing.
    secondaryPaymentMethodId string secondary payment method to be used for billing.
    userDefinedFields array of userDefinedField custom user-defined fields tied to the plan, which can be used for reporting.

    Scheduled Payment

    name type description
    amount decimal amount of the scheduled payment.
    scheduledDate datetime scheduled date of the payment.
    numberOfRetries int number of times to retry if the payment is declined.
    paid boolean indicates whether the payment has been made.
    paymentDate datetime date of the completed payment.
    paymentMethodId string payment method to be charged.
    planId int payment plan identifier.
    processed string indicates whether the payment has been processed.
    scheduleId int schedule ID for the payment.
    transactionId int transaction ID of the completed payment.

    Service Data

    name type description
    gratuityAmount decimal tip amount.
    server string server number (used in restaurant transactions).

    Settlement Data

    name type description
    date datetime date and time when the transaction was settled.
    amount number amount of the transaction.
    batchId number identifier for the batch that the transaction belongs to.

    Stored Payment Plan

    name type description
    planId int plan identifier. Auto-generated by the system and given to the merchant when the plan is added.
    active boolean indicates whether the plan is active or not.
    startDate dateTime plan start date.
    nextPaymentDate dateTime next scheduled payment date.
    maxRetries int number of times to retry billing if payment is declined.
    primaryPaymentMethodId string primary payment method to be used for billing.
    secondaryPaymentMethodId string secondary payment method to be used for billing.
    notes string notes associated with the plan.
    userDefinedFields array of userDefinedField custom user-defined fields tied to the plan, which can be used for reporting.
    schedules array of schedule all schedules assocated with the plan.

    Stored Schedule

    name type description
    amount decimal amount of the scheduled payment.
    installmentDate datetime installment date of the payment.
    numberOfRetries int number of times to retry if the payment is declined.
    paid boolean indicates whether the payment has been made.
    paymentDate datetime date the payment was made.
    paymentMethodId string payment method to be charged.
    installmentNum int installment number.
    processed string indicates whether the payment has been processed.
    scheduleId int schedule ID for the payment.
    transactionId int transaction ID for the completed payment.

    Transaction

    name type description
    secureNetId number merchant account identifier.
    transactionType fixed string transaction type identifier.
    responseText string transaction approval status.
    orderId string client-generated unique ID for each transaction, used as a way to prevent the processing of duplicate transactions. The orderId must be unique to the merchant's SecureNet ID; however, uniqueness is only evaluated for APPROVED transactions and only for the last 30 days. If a transaction is declined, the corresponding orderId may be used again.

    The orderId is limited to 25 characters; e.g., “CUSTOMERID MMddyyyyHHmmss”.
    transactionId number transaction identifier.
    authorizationCode string authorization approval code.
    authorizedAmount number authorized amount.
    allowedPartialCharges boolean indicates whether partial payments are to be accepted.
    paymentTypeCode fixed string

    credit card or check type. Valid values are:

    ACH - Check
    DB - PIN Debit
    PD - Pinless Debit
    VI - VISA
    MC - MasterCard
    AX - American Express
    DS - Discover
    MCF - MasterCard Fleet
    VIF - VISA Fleet
    WX - Wex
    VY - Voyager
    SV - Stored Value

    paymentTypeResult fixed string

    transaction method. Valid values are:

    CHECK
    CREDIT_CARD
    DEBIT_CARD
    FLEET_CARD
    STORED_VALUE
    UNKNOWN

    level2Valid boolean indicates whether the credit card is level 2 eligible.
    level3Valid boolean indicates whether the credit card is level 3 eligible.
    transactionData object date/time and amount of the authorized transaction.
    settlementData object date/time, amount, and batchId of the settled transaction.
    vaultData object customer data and Vault token.
    creditCardType string

    identifies the credit card type. Valid values are:

    VISA
    VISAFLEET
    MASTERCARD
    MASTERCARDFLEET
    AMEX
    DISCOVER

    cardNumber string last 4 digits of the credit card number. Format: XXXXXXXXXXXX 3456.
    avsCode string

    address verification code. Valid values are:

    0 - AVS data not provided.
    A - Street address matches, zip code does not
    B - Postal code not verified due to incompatible formats
    C - Street address and postal code not verified due to incompatible formats.
    D - Street address and postal code match
    E - AVS data is invalid
    G - Non-U.S. issuing bank does not support AVS
    I - Address information not verified by international issuer
    M - Customer name, billing address and zip match
    N - Neither street address nor zip code match
    P - Street address not verified due to incompatible format
    R - Retry: issuer's system unavailable or timed out
    S - U.S. issuing bank does not support AVS
    T - Street address does not match, but 9-digit zip code matches
    U - Address information is unavailable
    W - 9-digit zip matches, street address does not
    X - Street address and 9-digit zip match
    Y - Street address and 5-digit zip match

    avsResult string

    address verification result. Valid values are:

    NOT_CHECKED,
    ADDRESS_INCORRECT,
    ZIP_INCORRECT,
    BOTH_INCORRECT,
    MATCH

    cardholder_firstName string first name of the cardholder.
    cardholder_lastName string last name of the cardholder.
    expirationDate string account expiration date.
    billAddress object billing address of the customer.
    email string email address of the customer.
    cardCodeCode string

    card security code result. Valid values are:

    0 - CVV/CID not provided
    M - Match
    N - No match
    P - Not processed
    S - Data not present
    U - Issuer unable to process request
    Y - Card code matches (Amex only)

    cardCodeResult string

    card security code result. Valid values are:

    MATCH
    NOT_MATCH
    NOT_CHECKED

    accountName string account name of the bank account.
    accountType string account type of the bank account.
    accountNumber string last 4 digits of the bank account number.
    checkNumber string individual check number.
    traceNumber string trace number of an ACH check transaction.
    surchargeAmount number surcharge amount to be added to the transaction.
    cashBackAmount number cash back amount given to a customer. Commonly used for debit transactions.
    gratuity number tip amount.
    industrySpecificData string

    industry-specific data for ecommerce and moto transactions.

    For eCommerce transactions:

    P - Physical goods
    D - Digital goods

    For MO/TO transactions:

    0 - Default
    1 - Single purchase transaction (AVS is required)
    2 - Recurring billing transaction (do not submit AVS)
    3 - Installment transaction

    networkCode string identifier for the network that returned the transaction response.
    additionalAmount number remaining balance on a stored value account.
    method string

    transaction method. Valid values are:

    CC - Credit Card
    DB - Debit
    ECHECK - Electronic Check
    PD - Pinless Debit
    SV - Stored Value

    customerId string customer identifier.
    emailReceipt boolean indicates whether the functionality to send reciept via email is enabled or not.
    fleetCardInfo string not currently used
    fnsNumber string Unique number assigned to a person that participates in the SNAP program.
    voucherNumber string 15 character number representing the EBT Voucher account.
    additionalData1 string For stored value cards this is the Previous Balance (15 characters long zero filled decimal number with explicit decimal point) followed by Cash Out Amount (15 characters long zero filled decimal number with explicit decimal point).
    additionalData2 string For EBT transactions, it will contain the FNS # echoed from the ADDITIONALINFO field of the MERCHANT_KEY object. For stored value cards this is the virtual issued card number.
    additionalData3 string For EBT transactions, it will contain the Voucher # echoed from the ADDITIONALINFO field of the CARD object. For stored value cards it is the issued card EXP date.
    additionalData4 string Virtual issued card pin number. Used only for specific stored value card transactions.
    additionalData5 string P2P Encryption Transaction Response-String (22 Characters): 7-digit Key ID + {1,2} + MMddyyyyHHmmss
    softDescriptor string displays a description in addition to the merchants DBA.
    dynamicMCC string displays a 4 characters dynamic merchant category code.
    userDefinedFields array of userDefinedField custom user-defined fields tied to the transaction, which is used for transaction reporting and settlement only.
    notes string notes associated with the transaction, which is used for transaction reporting and settlement only.
    invoiceDescription string invoiceDescription associated with the transaction, which is used for transaction reporting and settlement only.
    CATIndicator int

    Value to indicate if the transaction originated from a cardholder activated terminal. Possible values are:

    0 - Not a CAT Transaction
    1 - ATM with PIN
    2 - Self-service terminal
    3 - Limited-amount terminal
    4 - In-flight commerce
    6 - Electronic commerce
    7 - Transponder transaction

    callId string Visa Checkout transaction ID associated with a payment request.

    Transaction Data

    name type description
    date datetime date and time when the transaction took place.
    amount number amount of the transaction.

    Wallet Data

    name type description
    callId string Visa Checkout transaction ID associated with a payment request.

    User Defined Field

    name type description
    udfName string valid values are udf1 to udf50.
    udfValue string value of the udf specified in udfName.

    Variable Payment Plan : Stored Payment Plan

    name type description
    planStartDate datetime plan start date.
    planEndDate datetime plan end date.
    primaryPaymentMethodId string primary payment method to be used for billing.
    secondaryPaymentMethodId string secondary payment method to be used for billing.
    nextPaymentDate datetime next payment date for the plan.
    userDefinedFields array of userDefinedField custom user-defined fields tied to the plan, which can be used for reporting.
    scheduledPayments array of scheduledPayment scheduled payments.
    active boolean sets the Plan Active or Inactive
    notes string notes associated with the plan.
    softdescriptor string displays a description in addition to the merchants DBA.
    dynamicMCC string displays a 4 characters dynamic merchant category code.
    planId int plan identifier. Auto-generated by the system and given to the merchant when the plan is added.
    startDate dateTime plan start date.
    nextPaymentDate dateTime next scheduled payment date.
    maxRetries int number of times to retry billing if payment is declined.

    Vault Customer And Payment

    name type description
    vaultCustomer object contents of the newly created Vault customer record.
    vaultPaymentMethod object contents of the newly created payment account record.
    accountResult fixed string result of the method call, e.g., SUCCESS if the customer was created.
    accountResponseCode fixed string response code for the method call. A value of 1 indicates the customer was created.
    accountMessage string text description of the response.
    customerResult fixed string result of the method call, e.g., SUCCESS if the customer was created.
    customerResponseCode fixed string response code for the method call. A value of 1 indicates the customer was created.
    customerMessage string text description of the response.

    Vault Customer

    name type description
    customerId string customer identifier.
    address object billing address of the account holder.
    firstName string first name of the customer.
    lastName string last name of the customer.
    emailAddress string email address of the customer.
    sendEmailReceipts string indicates whether an email receipt should be sent to the customer whenever a transaction is completed.
    company string company of the customer.
    notes string notes associated with the customer.
    userDefinedFields array of userDefinedField custom user-defined fields for reporting purposes.
    paymentMethods array of vaultPaymentMethod all payment methods on file.
    primaryPaymentMethodId string primary payment method for the customer.
    variablePaymentPlans array of variablePaymentPlan all variable payment plans associated with the customer.
    recurringPaymentPlans array of recurringPaymentPlan all recurring payment plans associated with the customer.
    installmentPaymentPlans array of installmentPaymentPlan all installment payment plans associated with the customer.

    Vault Data

    name type description
    token object vault token.
    company string company of the customer.
    firstName string first name of the customer.
    lastName string last name of the customer.
    email string email address of the customer.
    phone string phone number of the customer.

    Vault Payment Method

    name type description
    customerId string customer identifier.
    paymentId string payment account identifier or token.
    card object credit card account associated with the payment method.
    check object checking account associated with the payment method.
    notes string notes associated with the payment account.
    method string

    payment method of the payment account. Valid values are:

    CC - Credit card
    DB - Debit
    ECHECK - Electronic check
    CHECK21 - Electronic check
    PD - Pinless debit
    SV - Stored Value

    primary string indicates whether the account is set as the primary account for the associated customer.
    lastAccessDate string most recent date the payment method was accessed.
    userDefinedFields array of userDefinedField custom user-defined fields for reporting purposes.

    Vault Token

    name type description
    customerId string customer identifier.
    paymentMethodId string payment method to be used for billing.

    Vat Data

    name type description
    purchaserVatNumber string Vat Number used for the purchase
    merchantVatNumber string Merchant Vat Number
    taxRate decimal Tax Rate

    Vault Credentials

    name type description
    securenetId int identifier for a securenet account.
    securenetKey string unique key for a securenet account.

    Response Code values

    name type description
    responseCode fixed string

    response code for a transaction. Values are:

    1 - Approved
    2 - Declined
    3 - Error

    Result Type values

    name type description
    resultType fixed string

    result of a transaction. Values are:

    SUCCESS
    COMMUNICATION_ERROR
    AUTHENTICATION_ERROR
    DECLINE
    DECLINE_AVS
    DECLINE_CVV
    UNSUPPORTED_CARD
    INVALID_NAME
    INVALID_ADDRESS
    INVALID_CARD_NUMBER
    INVALID_CVV
    INVALID_EXPIRATION
    GATEWAY_ERROR
    BAD_REQUEST
    INVALID_ROUTING_NUMBER
    INVALID_AVS
    APPROVED


    Encryption Mode values

    name type description
    encryptionMode fixed string

    type of encryption applied to the cardholder information. Values are:

    NONE
    IDTECH_MSR
    MAGTEK_MSR
    MAGTEK_IPAD
    MIURA
    VERIFONE_VX805

    Payment Type values

    name type description
    paymentType fixed string

    type of payment used for a transaction. Values are:

    CHECK
    DEBIT_CARD
    CREDIT_CARD
    FLEET_CARD
    STORED_VALUE
    UNKNOWN

    Payment Type Code values

    name type description
    paymentTypeCode fixed string

    card or check type used for a transaction. Values are:

    ACH - Check
    DB - PIN Debit
    PD - Pinless Debit
    VI - VISA
    MC - MasterCard
    AX - American Express
    DS - Discover
    MCF - MasterCard Fleet
    VIF - VISA Fleet
    WX - Wex
    VY - Voyager
    SV - Stored Value

    Payment Type Result values

    name type description
    paymentTypeResult fixed string

    type of payment used for a transaction. Values are:

    CHECK
    DEBIT_CARD
    CREDIT_CARD
    FLEET_CARD
    STORED_VALUE
    UNKNOWN

    Status values

    name type description
    status fixed string

    tax status of a transaction. Values are:

    NOT_INCLUDED
    INCLUDED
    EXEMPT

    Transaction Type values

    name type description
    transactionType fixed string

    type of transaction. Values are:

    AUTH_ONLY
    PARTIAL_AUTH_ONLY
    AUTH_CAPTURE
    PARTIAL_AUTH_CAPTURE
    PRIOR_AUTH_CAPTURE
    UPDATE_TRANS_INFO
    CAPTURE_ONLY
    VOID
    PARTIAL_VOID
    CREDIT
    CREDIT_AUTHONLY
    CREDIT_PRIORAUTHCAPTURE
    FORCE_CREDIT
    FORCE_CREDIT_AUTHONLY
    FORCE_CREDIT_PRIORAUTHCAPTURE
    VERIFY
    ACCOUNT_VERIFICATION
    AUTH_INCREMENT
    ISSUE
    ACTIVATE
    REDEEM
    REDEEM_PARTIAL
    DEACTIVATE
    REACTIVATE
    INQUIRY_BALANCE
    RECHARGE
    ISSUE_VIRTUAL
    CASH_OUT

    Verification Type values

    name type description
    verification fixed string

    type of check verification used for a transaction. Values are:

    NONE
    CERTEGY
    ACH_PROVIDER