The ddMandateRequestV1 document object may contain the following elements:
Table 2-6: ddMandateRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String
Max = 10
This is the merchant account number.
storeID Yes String
Max = 80
This is the Optimal Payments store identifier, used to authenticate the request. It is defined by Optimal Payments and provided to the merchant as part of the integration process.
storePwd Yes String
Max = 20
This is the Optimal Payments store pass-word, used to authenticate the request. It is defined by Optimal Payments and provided to the merchant as part of the integration process.
merchantRefNum Conditional String
Max = 40
This is the unique ID number associated with the original request. The value is cre-ated by the merchant and submitted as part of the original request.
check accountType Optional Enumeration This is the type of checking account used for the transaction. Possible values are:
• PC (Personal Checking)
• PS (Personal Savings)
• PL (Personal Loan)
• BC (Business Checking)
• BS (Business Savings)
• BL (Business Loan)
NOTE: If this element is not specified, the value defaults to PC.
bankName Optional String
Max = 40
This is the name of the customer’s bank, to which this transaction is posted.
checkNum Optional Long
Max = 8
This is the check serial number, provided at the time of the transaction request.
accountNum Yes String
Max = 17
This is the customer’s bank account number.
For SEPA transactions, this is IBAN (Interna-tional Bank Account Number) of the cus-tomer’s bank account.
routingNum Yes String
Min = 6 Max = 9
For British pound accounts, this is the 6-digit sort code of the customer’s bank.
For SEPA transactions, this is the BIC (Bank Identifier Code) of the customer’s bank account.
payee Optional String Max = 81
This is the descriptor that will appear on the customer’s bank account. It is required only for credit and verify transactions.
If you provide a value for this field, this value will be used as the statement descriptor. If you do not provide a value for this field, a default value configured for the merchant account will be used.
bankCountry Conditional Enumeration This is the country in which the bank is located. See Country codes on page C-3 for correct codes to use. This is a required ele-ment only for certain countries.
bankCity Conditional String
Max = 40
This is the city in which the bank is located.
This is a required element only for certain countries.
mandateReference Conditional String Max = 10 For SEPA, Max = 35
This is the mandate reference that allows the account to be charged. You may optionally set the value of the mandateReference your-self when making the request. If you do not supply a value here then it will be set by Optimal Payments and returned in the response.
For SEPA, this element is mandatory, and the merchant creates their own
mandateReference.
billingDetails checkPayMethod Optional Enumeration This is the payment type.
Possible values are:
• WEB (Personal Check Only)
• TEL (Personal Check Only)
• PPD (Personal Check Only)
• CCD (Business Check Only)
NOTE: If this element is not specified, the value defaults to WEB.
firstName Conditional String Max = 40
This is the customer’s first name.
Required if checkPayMethod is set to WEB or TEL.
lastName Conditional String Max = 40
This is the customer’s last name.
Required if accountType is set to PC, PS, or PL.
companyName Conditional String Max = 50
This is the company’s name.
Required if accountType is set to BC, BS, or BL.
street Optional String
Max = 50
This is the first line of the customer’s street address.
street2 Optional String This is the second line of the customer’s Table 2-6: ddMandateRequestV1 Elements (Continued)
Element Child Element Required Type Description
city Optional String Max = 40
This is the city in which the customer resides.
state/region Conditional If state, then Enumeration If region, then string
Max = 40
This is the state/province/region in which the customer resides.
Provide state if within U.S./Canada. Provide region if outside of U.S./Canada.
See Appendix C: Geographical Codes for correct codes to use.
country Optional Enumeration This is the country in which the customer resides. See Country codes on page C-3 for correct codes to use.
zip Optional String
Max = 10
This is the customer’s ZIP code if in the U.S.;
otherwise, this is the customer’s postal code.
phone Optional String
Max = 40
This is the customer’s telephone number.
email Optional String
Max = 100
This is the customer’s email address.
customerIP Optional String
Max = 50
This is the customer’s IP address.
txnDate Optional dateTime This is the date and time that the transaction
took place.
For a charge or credit, or for a ddMandat-eRequestV1, this can be the future date and time when the transaction will take place.
autoSend Optional Boolean This controls when the mandate is sent to
the bank.
Possible values are:
• Y = The mandate will be set to W (Pending) status, ready to be batched and then sent to the bank
• N = The mandate will remain with the status of PCA (Pending Customer Approval), and will not be sent to the bank.
If the autoSend status is set to N, the man-date can later be changed to a status of W by using the changeStatus request, at which point the mandate will then be sent to the bank at the next batching time (see Building change status requests on page 2-28).
NOTE: For SEPA, this must be set to Y, and the mandate will be set to AP (Active).
Table 2-6: ddMandateRequestV1 Elements (Continued)
Element Child Element Required Type Description