The reference section contains details related to the PayOS API endpoints, actions, and reference objects.

 

RESTful Structure

The following REST endpoints are used to create and manage payments:

URL Verb Description
/payments/Authorize POST Authorizes a payment
/payments/Capture POST Captures a previously authorized payment
/payments/Charge POST Authorizes and Captures a payment
/payments/Credit POST Refunds a payment without requiring a linked transaction
/payments/Refund POST Refunds a previously authorized and settled payment
/payments/Verify POST Verifies that a credit card account number, address, or security code is valid on a credit card
/payments/Void POST Voids a previously authorized payment
/batches/Current GET Retrieves the current batch
/batches/{id} GET Retrieves a batch by id
/batches/Close POST Closes all pending transactions and creates a batch
/customers/ POST Adds a new customer to the vault
/customers/{id} PUT Updates a customer in the vault
/customers/{id} GET Retrieves a customer from the vault
/customers/{customerId}/PaymentSchedules/installment POST Adds an installment payment plan to a customer in the vault
/customers/{customerId}/PaymentSchedules/recurring POST Adds a recurring payment plan to a customer in the vault
/customers/{customerId}/PaymentSchedules/variable POST Adds a variable payment plan to a customer in the vault
/customers/{customerId}/PaymentSchedules/{planId} GET Retrieves a payment plan for a customer in the vault
/customers/{customerId}/PaymentSchedules/{planId} DELETE Deletes a payment plan for a customer in the vault
/transactions/{transactionId} GET Retrieves a transaction
/transactions/Search POST Searches for transactions
/transactions/{referenceTransactionId} PUT Updates a transaction

Object Definitions

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.
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.
deviceSerialNumber string the serial number of the POS terminal used.
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.
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

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 tied to the plan, which can be used for reporting.
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. Valid values are: 1 - 7 (e.g., 1 = Sunday, 7 = Saturday)
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.
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.

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. Valid values are: 1 - 7 (e.g., 1 = Sunday, 7 = Saturday)
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
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

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 tied to the plan, which can be used for reporting.
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 credit card 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 tied to the plan, which can be used for reporting.

Vault Token

name type description
customerId string customer identifier.
paymentMethodId string payment method to be used for billing.
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

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
securenet Id int identifier for a securenet account.
securenet Key string unique key for a securenet account.


Fixed String Definitions

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

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