Direct Debit Transactions

This page describes how to process Direct Debit transactions via the Paysafe Web Service. The following operations are supported:

Operation	Description	For	Request Type
Charge	Allows you to transfer money from a customer’s bank account to your merchant account. This transaction is completed in real time, though the banking network takes 2–5 days to transfer the funds, depending on the bank scheme.	EFT ACH BACS SEPA	See Building charge or credit requests.
Credit	Allows you to transfer money from your merchant account directly to a customer’s bank account. This transaction is completed in real time, though the banking network takes 2–5 days to transfer the funds, depending on the bank scheme.	EFT ACH BACS SEPA	See Building charge or credit requests.
Update Shipping Info	Allows you to send shipping information, including a tracking number, once you have shipped goods for which you previously processed a charge transaction.	EFT ACH BACS	See Building updateShippingInfo requests.
Information Lookup	Allows you to run a report through the API over a date range you specify to return data on Direct Debit charge and credit transactions processed through your merchant account.	EFT ACH BACS SEPA	See Building lookup requests.
Mandate Request	Allows you to create a mandate for a customer’s bank account and lodge it at their bank, which permits you to transfer money from the customer’s bank account to your merchant account. The banking network typically takes 5 days to process the mandate.	BACS SEPA	See Building BACS mandate requests (UK).
Change Status	Allows you to change the status of a charge, credit, or mandate transaction.	EFT ACH BACS SEPA	See Building change status requests.
Update Mandate	Allows you to update the information contained within an existing mandate.	SEPA	See Building mandate update requests.

Availability of Direct Debit operation types is allotted on a merchant-by-merchant basis, since not all merchant banks support all operations. If you have any questions, contact your account manager.

The charge and credit operations accept a ddCheckRequestV1 document object.
The updateShippingInfo operation accepts a ddShippingRequestV1 document object.
The lookup operation accepts a ddLookupRequestV1 document object.
The mandate request operation accepts a ddMandateRequest document object.
The change status operation accepts a ddChangeStatusRequest document object.
The mandate update operation accepts a ddUpdateMandateRequest document object.
All operations return a ddCheckResponseV1 response.

.NET example

To build the .NET example:

Create a new project.
Add a Web Reference.
Enter the WSDL URL and click the Add Reference button.
The Web client is now built.

Building charge or credit requests

Charge and credit requests require the ddCheckRequestV1 document object. This section describes the structure of a ddCheckRequestV1 and how to construct one. See ddCheckRequestV1 Elements for details on elements required.

charge example – C#

The following is a charge example in C#.

To make this a credit request, modify the value “charge” – in the line “DDCheckResponseV1 ddTxnResponse = ddService.charge(ddCheckRequest)” below – to “credit”.

// Prepare the call to the Direct Debit Web Service



DDCheckRequestV1 ddCheckRequest = new DDCheckRequestV1();



ddCheckRequest.amount = "10.00";



MerchantAccountV1 merchantAccount = new MerchantAccountV1();



merchantAccount.accountNum = "12345678";



merchantAccount.storeID = "myStoreID";



merchantAccount.storePwd = "myStorePWD";



ddCheckRequest.merchantAccount = merchantAccount;



CheckV1 check = new CheckV1();



check.routingNum = "123456789";



check.accountNum = "987654321";



check.accountType = BankAccountTypeV1.PC;



check.bankName = "Chase";



check.checkNum = 12;



check.payee = "ACME Inc.";



ddCheckRequest.check = check;



BillingDetailsV1 billingDetails = new BillingDetailsV1();



billingDetails.firstName = "Jane";



billingDetails.lastName = "Jones";



billingDetails.street = "123 Main Street";



billingDetails.city = "LA";



billingDetails.country = CountryV1.US;



billingDetails.zip = "90210";



billingDetails.phone = "555-555-5555";



billingDetails.checkPayMethod = CheckPayMethodV1.WEB;



ddCheckRequest.billingDetails = billingDetails;



//Perform the Web Services call to process the charge



DirectDebitServiceV1 ddService = new DirectDebitServiceV1();



DDCheckResponseV1 ddTxnResponse = ddService.charge(ddCheckRequest);







// Print out the result



String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +

            " - " + ddTxnResponse.description;



responseTxt += "Details:" + Environment.NewLine;



if (ddTxnResponse.detail != null)



{



   for (int i = 0; i < ddTxnResponse.detail.Length; i++)



   {



      responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " +



      ddTxnResponse.detail[i].value + Environment.NewLine;



   }



}



responseTxt = responseTxt.Replace("\n", Environment.NewLine);



System.Console.WriteLine(responseTxt);



if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision))



{



   System.Console.WriteLine("Transaction Successful.");



}



else



{



   System.Console.WriteLine("Transaction Failed with decision: " +

   ddTxnResponse.decision);



}

ddCheckRequestV1 schema

A ddCheckRequestV1 document object has the following structure:

ddCheckRequestV1 elements

This request is used for Direct Debit transactions for a variety of schemes. See Additional Direct Debit Element Requirements below for variations on certain required elements.

The ddCheckRequestV1 document object may contain the following 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 Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
	storePwd	Yes	String Max = 20	This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe 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 created by the merchant and submitted as part of the original request. This is returned only in response to a lookup request.
amount		Yes	String Max = 9999999.99	This is the amount of the transaction request. NOTE: This field requires a leading non-zero digit and two digits after the decimal place. An exception is made in cases where a leading zero is by itself (e.g., 0.99).
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	Yes	Long Max = 8	This is the check serial number, provided at the time of the transaction request.
	accountNum	Yes	String Max = 17 If IBAN, Max = 32	This is the customer’s bank account number. For SEPA transactions, this is IBAN (International Bank Account Number) of the customer’s bank account. NOTE: This cannot be zero (0) and can contain alphanumeric characters only.
	routingNum	Yes	String Min = 6 Max = 9 If BIC, Min = 8 Max = 11	For USD accounts, this is the 9-digit routing number of the customer’s bank. For British pound accounts, this is the 6-digit sort code of the customer’s bank. For Canadian dollar accounts, this is a combination of the 3-digit institution ID followed by the 5-digit transit number of the customer’s bank branch. They must be entered in this order. Do not include spaces or dashes. For SEPA transactions, this is the BIC (Bank Identifier Code) of the customer’s bank account. If you do not have the BIC, you can submit the following case-sensitive value: EMPTYBIC NOTE: This cannot be zero (0) and can contain alphanumeric characters only.
	payee	Conditional	String Max = 81	This is the descriptor that will appear on the customer’s bank account. It is required only for credit 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 for correct codes to use. This is a required element 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 For BACS, Max = 10	This is the mandate reference that allows the account to be charged. This is the value returned for the mandateReference parameter in the response to a ddMandateRequestV1. NOTE: This element is mandatory for BACS and SEPA debits only.
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. It cannot be set to WEB or TEL for credit requests.
	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	Yes	String Max = 50	This is the first line of the customer’s street address.
	street2	Optional	String Max = 50	This is the second line of the customer’s street address.
	city	Yes	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 Codes for correct codes to use.
	country	Yes	Enumeration	This is the country in which the customer resides. See Country codes 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.
personalID	idNumber	Optional	String Max = 20	This is the number of the ID provided for the idType element.
	idType	Optional	Enumeration	This is the type of ID used to identify the owner of the bank account. Possible values are: • DL (Driver’s License) • SS (Government ID) • MI (Military ID) • GN (Generic ID)
	state/region	Optional	If state, then Enumeration If region, then string Max = 40	This is the state/province/region in which the ID was issued. Provide state if within U.S./Canada. Provide region if outside of U.S./Canada. See Codes for correct codes to use.
	country	Optional	String Length = 2	This is the country in which the ID was issued. Possible values are: • CA (Canada) • US (United States)
	expiry	Optional		The expiry child element has three further child elements.
		Child Element of expiry
	day	Optional	Int Length = 2	This is the day the ID expires.
	month	Optional	Int Length = 2	This is the month the ID expires.
	year	Conditional	Int Length = 4	This is the year the ID expires. This element is required if the expiry element is included.
socialSecurityNumber		Optional	String Max = 12	This is the customer’s Social Security Number.
dateOfBirth		Optional		This is the customer’s date of birth.
	year	Conditional	String Max = 4 1900–9999	This is the customer’s year of birth.
	month	Conditional	String Max = 12	This is the customer’s month of birth.
	day	Conditional	String Max = 31	This is the customer’s day of birth.
shippingDetails	carrier	Optional	Enumeration	This is the shipment carrier. Possible values are: • APC = APC Overnight • APS = AnPost • CAD = Canada Postal Service • DHL • FEX = Fedex • RML = Royal Mail • UPS = United Parcel Service • USPS = United States Postal Service • OTHER
	trackingNumber	Optional	String Max = 50	This is the shipping tracking number provided by the carrier.
	shipMethod	Optional	Enumeration	This is the method of shipment. Possible values are: • N = Next Day/Overnight • T = Two-Day Service • C = Lowest Cost • O = Other
	firstName	Optional	String Max = 40	This is the recipients’s first name.
	lastName	Optional	String Max = 40	This is the recipient’s last name.
	street	Optional	String Max = 50	This is the first line of the recipient’s street address.
	street2	Optional	String Max = 50	This is the second line of the recipient’s street address.
	city	Optional	String Max = 40	This is the city in which the recipient resides.
	state/region	Optional	If state, Enumeration If region, then string Max = 40	This is the state/province/region in which the recipient resides. Provide state if within U.S./Canada. Provide region if outside of U.S./Canada.
	country	Optional	Enumeration	This is the country in which the recipient resides.
	zip	Optional	String Max = 10	This is the recipient’s ZIP code if in the U.S.; otherwise, this is the recipient’s postal code.
	phone	Optional	String Max = 40	This is the recipient’s phone number.
	email	Optional	String Max = 100	This is the recipient’s email address.
customerIP		Optional	String Max = 50	This is the customer’s IP address.
productType		Optional	Enumeration	This is the type of product sold. Possible values are: • P (Physical Goods) • D (Digital Goods) • C (Digital Content) • G (Gift Certificate/Digital Cash) • S (Shareware) • M (Both Digital and Physical) • R (Account Replenish)
txnAppliedTo		No		This element is not applicable for Direct Debit transactions.
confirmationNumber		Conditional	String Max = 15	This is the confirmation number returned by Paysafe in response to the original request. Include this element only if you are using the ddCheckRequestV1 to process a credit request.
targetVirtualAccount		No		This element is not applicable for Direct Debit transactions.
checkRiskService		No		This element is not applicable for Direct Debit transactions.
txnDate		Optional	dateTime	This is the date and time that the transaction took place. For a charge or credit, or for a ddMandateRequestV1, this can be the future date and time when the transaction will take place. For SEPA, this specifies the future collection date. It must be a minimum of 2 business days in the future for all SEPA transaction requests. NOTE: The resulting collection date will be returned in the tag/value pair for the detail element in the response.
sdk	version	Conditional	String Max = 20	This is the version of the SDK used, if any. Required if sdk element is provided.
	platform	Conditional	String Max = 10	This is the integration language of the SDK used (e.g., Java, .NET). Required if sdk element is provided.
	provider	Conditional	String Max = 20	This is the author of the SDK used. Set to value “op” when the SDK is provided by Paysafe. Required if sdk element is provided.
origin		Optional	Enumeration	The is the origin of the request. Possible values are: • Wireless • Wireline
addendumData	tag	Optional	String Max = 30	This is additional data that the merchant can include with the transaction request.
	value	Optional	String Max = 1024	This is additional data that the merchant can include with the transaction request.

Special considerations for Direct Debit elements

Some merchants are integrated with downstream processors that have different requirements for mandatory Direct Debit elements. In such cases, the following holds.

Additional Direct Debit Element Requirements

Element	Regular Transactions	Guaranteed Transactions	SEPA Transactions
check.accountType	Optional	Required	Optional
check.bankName	Optional	Required	Optional
check.checkNum	Required	Required	Optional
check.payee	Optional	Optional	Required
check.bankCountry	Conditional	Conditional	Optional
check.bankCity	Conditional	Conditional	Optional
check.mandateReference	Conditional	Conditional	Required for Debits only.
billingDetails.firstName	Conditional	Required	Required
billingDetails.lastName	Conditional	Required	Required
billingDetails.companyName	Conditional	Conditional	Optional
billingDetails.state	Conditional	Required	Optional
billingDetails.zip	Optional	Required	Required
billingDetails.phone	Optional	Required	Optional
billingDetails.email	Optional	Required	Required
customerIP	Optional	Required	Optional
dateOfBirth.year	Optional	Required	Optional
dateOfBirth.month	Optional	Required	Optional
dateOfBirth.day	Optional	Required	Optional
personalID.idNumber	Optional	Required	Optional
personalID.state	Optional	Required	Optional
socialSecurityNumber	Optional	Required	Optional

Your account manager will inform you:

If you are integrated with this type of downstream processor and
If you are eligible for guaranteed Direct Debit processing.

Building updateShippingInfo requests

All optional elements that take non-nullable data types (e.g., int or enum) must have their specified attribute set to true when setting values for those elements. See the shipMethod element in the example below

The updateShippingInfo request requires the ddShippingRequestV1 document object. This section describes the structure of a ddShippingRequestV1 and how to construct one.

updateShippingInfo example – C#

The following is an updateShippingInfo example in C#.

// Prepare the call to the Direct Debit Web Service



DDShippingRequestV1 ddShippingRequest = new DDShippingRequestV1();



MerchantAccountV1 merchantAccount = new MerchantAccountV1();



merchantAccount.accountNum = "12345678";



merchantAccount.storeID = "myStoreID";



merchantAccount.storePwd = "myStorePwd";



ddShippingRequest.merchantAccount = merchantAccount;



ddShippingRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous settle auth or purchase



ddShippingRequest.carrier = CarrierV1.FEX; // Fedex



ddShippingRequest.shipMethod = ShipMethodV1.T;



ddShippingRequest.shipMethodSpecified = true;



ddShippingRequest.trackingNumber = "555666888999";



ddShippingRequest.firstName = "Jane";



ddShippingRequest.lastName = "Jones";



ddShippingRequest.street = "123 Main Street";



ddShippingRequest.city = "LA";



ddShippingRequest.country = CountryV1.US;



ddShippingRequest.countrySpecified = true;



ddShippingRequest.zip = "90210";



ddShippingRequest.email = "janejones@emailserver.com"; // optional email address







//Perform the Web Services call to update the shipping info



DirectDebitServiceV1 ddService = new DirectDebitServiceV1();



DDCheckResponseV1 ddTxnResponse =



ddService.updateShippingInfo(ddShippingRequest);



// Print out the result



String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " +

            ddTxnResponse.description;



responseTxt += "Details:" + Environment.NewLine;



if (ddTxnResponse.detail != null)



{



   for (int i = 0; i < ddTxnResponse.detail.Length; i++)



   {



      responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " +



      ddTxnResponse.detail[i].value + Environment.NewLine;



   }



}



responseTxt = responseTxt.Replace("\n", Environment.NewLine);



System.Console.WriteLine(responseTxt);



if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision))



{



   System.Console.WriteLine("Transaction Successful.");



}



else



{



   System.Console.WriteLine("Transaction Failed with decision: " +

   ddTxnResponse.decision);



}

ddShippingRequestV1 schema

A ddShippingRequestV1 document object has the following structure:

ddShippingRequestV1 elements

The ddShippingRequestV1 document object may contain the following 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 Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
	storePwd	Yes	String Max = 20	This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
carrier		Yes	Enumeration	This is the shipment carrier. Possible values are: • APC = APC Overnight • APS = AnPost • CAD = Canada Postal Service • DHL • FEX = Fedex • RML = Royal Mail • UPS = United Parcel Service • USPS = United States Postal Service • OTHER
trackingNumber		Yes	String Max = 50	This is the shipping tracking number provided by the carrier.
confirmationNumber		Yes	String Max = 15	This is the confirmation number returned by Paysafe.
shipMethod		Optional	Enumeration	This is the method of shipment. Possible values are: • N = Next Day/Overnight • T = Two-Day Service • C = Lowest Cost • O = Other
firstName		Optional	String Max = 40	This is the customer’s first name.
lastName		Optional	String Max = 40	This is the customer’s last name.
street		Optional	String Max = 50	This is the first line of the customer’s street address.
street2		Optional	String Max = 50	This is the second line of the customer’s street address.
city		Optional	String Max = 40	This is the city in which the customer resides.
state/region		Optional	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.
country		Optional	Enumeration	This is the country in which the customer resides.
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.

Building lookup requests

The Direct Debit lookup request allows you to run a report, over a date range you specify, to return data on Direct Debit charge and credit transactions processed through your merchant account.

Lookup example – C#

The following is a ddLookupRequest example in C#.

// Prepare the call to the Direct Debit Web Service



DDLookupRequestV1 ddLookupRequest = new DDLookupRequestV1();



MerchantAccountV1 merchantAccount = new MerchantAccountV1();



merchantAccount.accountNum = "12345678";



merchantAccount.storeID = "myStoreID";



merchantAccount.storePwd = "myStorePWD";



ddLookupRequest.merchantAccount = merchantAccount;



ddLookupRequest.confirmationNumber = "123456789";



DateV1 startDate = new DateV1();



startDate.year = "2012";



startDate.month = "08";



startDate.day = "15";



startDate.hour = "11";



startDate.minute = "00";



startDate.second = "00";



ddLookupRequest.startDate = startDate;



ddLookupRequest.startDateSpecified = true;



DateV1 endDate = new DateV1();



endDate.year = "2012";



endDate.month = "08";



endDate.day = "15";



endDate.hour = "14";



endDate.minute = "00";



endDate.second = "00";



ddLookupRequest.endDate = endDate;



ddLookupRequest.endDateSpecified = true;







//Perform the Web Services call to process the charge



DirectDebitServiceV1 ddService = new DirectDebitServiceV1();



DDCheckResponseV1 ddCheckResponse = ddService.lookup(ddLookupRequest);



// Print out the result



String responseTxt = ddCheckResponse.code + " - " + ddCheckResponse.decision;



responseTxt += "Transactions:" + Environment.NewLine;



if (ddCheckResponse.transaction != null)



{



for (int i = 0; i < ddCheckResponse.transaction.Length; i++)



{



responseTxt += " - confirmationNumber: " +



ddCheckResponse.transaction[i].confirmationNumber + Environment.NewLine;



responseTxt += " - merchantRefNum: " +



ddCheckResponse.transaction[i].merchantRefNum + Environment.NewLine;



responseTxt += " - txnTime: " +



ddCheckResponse.transaction[i].txnTime + Environment.NewLine;



responseTxt += " - amount: " +



ddCheckResponse.transaction[i].amount + Environment.NewLine;



StatusV1 status = ddCheckResponse.transaction[i].status;



if (status != null){



responseTxt += " - status: " +



status.code + Environment.NewLine;



responseTxt += " - status effective date:" +



status.effectiveDate + Environment.NewLine;



}



responseTxt += Environment.NewLine;



}



}



responseTxt = responseTxt.Replace("\n", Environment.NewLine);



System.Console.WriteLine(responseTxt);



if (DecisionV1.ACCEPTED.Equals(ddCheckResponse.decision))



{



System.Console.WriteLine("Transaction Found.");



}



else



{



System.Console.WriteLine("Transaction Failed or Not Found with decision: " +



ddCheckResponse.decision);



}

ddLookupRequestV1 schema

A ddLookupRequestV1 document object has the following structure:

ddLookupRequestV1 elements

The ddLookupRequestV1 document object may contain the following 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 Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
	storePwd	Yes	String Max = 20	This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber		Optional	String Max = 15	This is the confirmation number returned by Paysafe in response to the original request. Include this element only if you want to search using this field. This field takes precedence over the merchantRefNum field.
merchantRefNum		Conditional	String Max = 40	This is a unique ID number associated with the original request. The value is created by the merchant and submitted as part of the request.
startDate	year	Required	Int Max = 9999	This is the year set for the search start.
	month	Required	Int Min = 1 Max = 12	This is the month set for the search start.
	day	Required	Int Min = 1 Max = 31	This is the day set for the search start.
	hour	Required	Int Min = 0 Max = 23	This is the hour set for the search start.
	minute	Required	Int Min = 0 Max = 59	This is the minute set for the search start.
	second	Required	Int Min = 0 Max = 59	This is the second set for the search start.
endDate	year	Required	Int Max = 9999	This is the year set for the search end.
	month	Required	Int Min = 1 Max = 12	This is the month set for the search end.
	day	Required	Int Min = 1 Max = 31	This is the day set for the search end.
	hour	Required	Int Min = 0 Max = 23	This is the hour set for the search end.
	minute	Required	Int Min = 0 Max = 59	This is the minute set for the search end.
	second	Required	Int Min = 0 Max = 59	This is the second set for the search end.

Building BACS mandate requests (UK)

The Direct Debit mandate allows you to create a mandate for a customer’s bank account and lodge it at their bank, which is required before you can perform a charge operation to transfer money from that customer’s bank account to your merchant account.

When you submit a ddMandateRequestV1, Paysafe will return a value for the mandateReference element in the response. This value is either based on the value you send in the request, or it is automatically generated by the Paysafe system. You will use this value in the mandateReference element (which is a child element of the check element) when you process future charge requests against the customer’s bank account using the ddCheckRequestV1.

The mandateReference is 10 characters in length. If you send a request with a value of fewer than 10 characters, Paysafe will pre-fill the reference with 0’s to make up 10 characters. For example, a requested value of “ABCDEFG” will return a value of “000ABCDEFG”. If no value is passed, Paysafe will create the value for you and return it within the response.

Initially, the status of the mandate is set to W (Pending), followed by C (Completed) when it has been batched – at this point the mandate cannot yet be used for Direct Debit transactions. The banking network typically takes 5 days to process the mandate, so 5 days after the mandate has been batched, Paysafe changes the status of the mandate to AP (Active). At that point it can be used to authorize Direct Debit transactions on the bank account for which it was set up. Note that if the charge is postdated by setting the txnDate in the ddCheckRequestV1 request, then the mandate may be used while it is not yet active, provided the txnDate is set to a minimum of 5 working days in the future to allow the mandate time to become active. To assist this process, the date a mandate will become active is returned in the effectiveDate element of the response to the ddMandateRequestV1.

Mandates are automatically batched the next working day unless the autoSend value is not set to Y, in which case the mandate will remain in a PCA (Pending Customer Approval) state. This optional intermediate state before W allows you to perform extra checks on the customer, or for the customer to review the information having received the mandateReference, before proceeding. The mandate may then be turned from a PCA to W state by using either the changeStatus request or the Paysafe merchant back office.

Building SEPA mandate requests

In order to process a SEPA Direct Debit transaction, you will need to pre-establish a mandate agreement with your customer and send your mandate reference ID in the mandateReference element. Please note that your mandate reference ID can have up to 35 characters.

Mandates are not required for SEPA credits.

SEPA Direct Debit mandates are active as soon they are created by the merchant, so you can immediately follow up the ddMandateRequest request with a ddCheckRequest.

mandate example – C#

The following is a ddMandateRequest example in C#.

// Prepare the call to the Direct Debit Web Service



DDMandateRequestV1 ddMandateRequest = new DDMandateRequestV1();



MerchantAccountV1 merchantAccount = new MerchantAccountV1();



merchantAccount.accountNum = "12345678";



merchantAccount.storeID = "myStoreID";



merchantAccount.storePwd = "myStorePWD";



ddCheckRequest.merchantAccount = merchantAccount;



CheckV1 check = new CheckV1();



check.routingNum = "123456789";



check.accountNum = "987654321";



check.bankName = "Chase";



check.payee = "ACME Inc.";



ddMandateRequest.check = check;



BillingDetailsV1 billingDetails = new BillingDetailsV1();



billingDetails.firstName = "Jane";



billingDetails.lastName = "Jones";



billingDetails.street = "123 Main Street";



billingDetails.city = "Cambridge";



billingDetails.country = CountryV1.UK;



billingDetails.zip = "CB12345";



billingDetails.phone = "1222 444000";



billingDetails.checkPayMethod = CheckPayMethodV1.WEB;



ddMandateRequest.billingDetails = billingDetails;



ddMandateRequest.autoSend = "Y";



//Perform the Web Services call to process the charge



DirectDebitServiceV1 ddService = new DirectDebitServiceV1();



DDCheckResponseV1 ddTxnResponse = ddService.mandate(ddCheckRequest);







// Print out the result



String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +

            " - " + ddTxnResponse.description;



responseTxt += "Details:" + Environment.NewLine;



if (ddTxnResponse.detail != null)



{



   for (int i = 0; i < ddTxnResponse.detail.Length; i++)



   {



      responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " +



      ddTxnResponse.detail[i].value + Environment.NewLine;



   }



}



responseTxt = responseTxt.Replace("\n", Environment.NewLine);



System.Console.WriteLine(responseTxt);



if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision))



{



   System.Console.WriteLine("Transaction Successful.");



}



else



{



   System.Console.WriteLine("Transaction Failed with decision: " +

   ddTxnResponse.decision);



}

ddMandateRequestV1 schema

A ddMandateRequestV1 document object has the following structure:

ddMandateRequestV1 elements

The ddMandateRequestV1 document object may contain the following 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 Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
	storePwd	Yes	String Max = 20	This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe 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 created 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 (International Bank Account Number) of the customer’s bank account.
	routingNum	Yes	String Min = 6 Max = 9 If BIC, Min = 8 Max = 11	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. If you do not have the BIC, you can submit the following case-sensitive value: EMPTYBIC
	payee	Optional	String Max = 81	This is the descriptor that will appear on the customer’s bank account. It is required only for credit 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. This is a required element 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 yourself when making the request. If you do not supply a value here then it will be set by Paysafe 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 Max = 50	This is the second line of the customer’s street address.
	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.
	country	Optional	Enumeration	This is the country in which the customer resides.
	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 ddMandateRequestV1, 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 mandate 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. NOTE: For SEPA, this must be set to Y, and the mandate will be set to AP (Active).
addendumData	tag	Optional	String Max = 30	This is additional data that the merchant can include with the transaction request.
	value	Optional	String Max = 1024	This is additional data that the merchant can include with the transaction request.

Building change status requests

A change status request allows you to change the status of some Direct Debit transactions. You can make the following status changes:

Solution	Request Type	Initial Status	Resulting Status
UK Direct Debit (BACS)	• Mandate	• PCA – Pending Customer Approval	• W – Pending • X – Cancelled
UK Direct Debit (BACS)	• Charge • Credit • Mandate	• W – Pending	• X – Cancelled
UK Direct Debit (gateway merchants)	• Charge • Credit • Mandate	• C – Completed • CL – Cleared	• RE – Returned NOTE: Use only when your sponsoring bank has rejected the transaction and no BACS report has been produced. Allow 5 working days from the completed date and then contact Technical Support before making this change request.
EFT/ACH	• Charge • Credit	• C – Completed	• X – Cancelled NOTE: Only possible where the request has not yet been sent to the bank.
SEPA Direct Debit	• Mandate	• AP – Active	• X – Cancelled
SEPA Direct Debit	• Charge	• W – Pending • C – Completed	• X – Cancelled NOTE: SEPA Direct Debit transactions can be cancelled only before their execution date.

Paysafe responds to your change status request with the ddCheckResponseV1. In this response, the confirmationNumber identifies the request that was updated (charge, credit, or mandateRequest), and you can confirm the new status of the transaction you updated.

Change status example – C#

The following is a ddChangeStatusRequest example in C#.

// Prepare the call to the Direct Debit Web Service



DDChangeStatusRequestV1 ddChangeStatusRequest = new DDChangeStatusRequestV1();



MerchantAccountV1 merchantAccount = new MerchantAccountV1();



merchantAccount.accountNum = "12345678";



merchantAccount.storeID = "myStoreID";



merchantAccount.storePwd = "myStorePWD";



ddChangeStatusRequest.merchantAccount = merchantAccount;



ddChangeStatusRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous mandate or echeck;



ddChangeStatusRequest.status = "C";



//Perform the Web Services call to process the charge



DirectDebitServiceV1 ddService = new DirectDebitServiceV1();



DDCheckResponseV1 ddTxnResponse = ddService.changeStatus(ddCheckRequest);







// Print out the result



String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +

            " - " + ddTxnResponse.description;



responseTxt += "Details:" + Environment.NewLine;



if (ddTxnResponse.detail != null)



{



   for (int i = 0; i < ddTxnResponse.detail.Length; i++)



   {



      responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " +



      ddTxnResponse.detail[i].value + Environment.NewLine;



   }



}



responseTxt = responseTxt.Replace("\n", Environment.NewLine);



System.Console.WriteLine(responseTxt);



if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision))



{



   System.Console.WriteLine("Transaction Successful.");



}



else



{



   System.Console.WriteLine("Transaction Failed with decision: " +

   ddTxnResponse.decision);



}

ddChangeStatusRequest schema

A ddChangeStatusRequestV1 document object has the following structure:

ddChangeStatusRequestV1 elements

The ddChangeStatusRequestV1 document object may contain the following 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 Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
	storePwd	Yes	String Max = 20	This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber		Optional	String Max = 15	This value identifies the transaction whose status you want to change. This is the confirmationNumber returned by Paysafe in response to the original transaction request.
status		Required	Enumeration	This is the new status code for the transaction. Possible values are: • C – Completed • RE – Returned • W – Pending • X – Cancelled
addendumData	tag	Optional	String Max = 30	This is additional data that the merchant can include with the transaction request.
	value	Optional	String Max = 1024	This is additional data that the merchant can include with the transaction request.

Building mandate update requests

Only merchants processing SEPA Direct Debits can use this request type.

A mandate update request allows you to update an existing mandate. Effectively, you are creating a new mandate based on the information contained in the existing mandate, but with some updated information (e.g., a customer’s bank account number might change).

When you submit a ddUpdateMandateRequestV1, Paysafe sets the status of the mandate to T (Transferred). A new mandate is created, copying the data from the existing mandate, except for any of the following three values that may have been specified in the mandate update request:

mandateReference
accountNum
routingNum

Any new values that were specified in the request for these elements will be used in the new mandate.

The new mandate will have a status of either PCA (Pending Customer Approval) or AP (Active) as per the existing mandate. The new mandate will be linked to the existing mandate, so the system knows that the existing mandate was transferred to the new mandate.

Paysafe responds to your update mandate request with the ddCheckResponseV1. In this response, the confirmationNumber identifies the new mandate that has been created.

Mandate update example – C#

The following is a ddUpdateMandateRequest example in C#.

// Prepare the call to the Direct Debit Web Service



DDUpdateMandateRequestV1 ddUpdateMandateRequest = new DDUpdateMandateRequestV1();



MerchantAccountV1 merchantAccount = new MerchantAccountV1();



merchantAccount.accountNum = "12345678";



merchantAccount.storeID = "myStoreID";



merchantAccount.storePwd = "myStorePWD";



ddUpdateMandateRequest.merchantAccount = merchantAccount;



ddUpdateMandateRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous mandate or echeck;



ddUpdateMandateRequest.mandateReference = "NL95ZZZ999999991458_TEST7A";



//Perform the Web Services call to process the charge



DirectDebitServiceV1 ddService = new DirectDebitServiceV1();



DDCheckResponseV1 ddTxnResponse = ddService.updateMandate(ddCheckRequest);







// Print out the result



String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +

            " - " + ddTxnResponse.description;



responseTxt += "Details:" + Environment.NewLine;



if (ddTxnResponse.detail != null)



{



   for (int i = 0; i < ddTxnResponse.detail.Length; i++)



   {



      responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " +



      ddTxnResponse.detail[i].value + Environment.NewLine;



   }



}



responseTxt = responseTxt.Replace("\n", Environment.NewLine);



System.Console.WriteLine(responseTxt);



if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision))



{



   System.Console.WriteLine("Transaction Successful.");



}



else



{



   System.Console.WriteLine("Transaction Failed with decision: " +

   ddTxnResponse.decision);



}

ddUpdateMandateRequestV1 schema

A ddUpdateMandateRequestV1 document object has the following structure:

ddUpdateMandateRequestV1 elements

The ddUpdateMandateRequestV1 document object may contain the following 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 Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
	storePwd	Yes	String Max = 20	This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber		Optional	String Max = 15	This value identifies the mandate that you want to update. This is the confirmationNumber returned by Paysafe in response to the original transaction request.
mandateReference		Conditional	String Max = 10 For SEPA, Max = 35	This is the mandate reference that allows the account to be charged. This is the value returned for the mandateReference parameter in the response to a ddMandateRequestV1. You might need to update the mandateReference, e.g., if the billing terms have changed but all other mandate information remains the same.
accountNum		Conditional	String Max = 17 If IBAN, Max = 32	For SEPA transactions, this is the IBAN (International Bank Account Number) of the customer’s bank account. You might need to update the accountNum, e.g., if the customer is now going to be billed out of a different account but from the same bank (i.e., where there is no need to change the BIC).
routingNum		Conditional	String Min = 6 Max = 9 If BIC, Min = 8 Max = 11	For SEPA transactions, this is the BIC (Bank Identifier Code) of the customer’s bank account. If you do not have the BIC, you can submit the following case-sensitive value: EMPTYBIC You would need to update the routingNum, e.g., if the customer has changed banks, in which case the accountNum would also have to be updated.

At least one of these three elements must be included in the request: mandateReference, accountNum, and routingNum.

Processing the response

A ddCheckResponseV1 has the following structure:

The following elements are relevant for a ddCheckResponseV1:

Element	Child Element	Required	Type	Description
requestId		Optional		This is the unique ID number returned by Paysafe for a record if it was processed in a batch file.
confirmationNumber		Yes	String Max = 15	This is the confirmation number returned by Paysafe. If this is returned in response to a ddUpdateMandateRequestV1, this identifies the new mandate that has been created.
merchantRefNum		Optional	String Max = 40	This is the unique ID number associated with the original request. The value is created by the merchant and submitted as part of the original request. This is returned only in response to a lookup request.
mandateReference		Yes	String Max = 20	This is the mandate reference returned by Paysafe. It is either the value echoed back from the request, or if it was not specified correctly in the request, then it is generated by Paysafe. For SEPA, this is the mandate reference created by the merchant in the request.
decision		Yes	Enumeration	This is the status of the transaction. One of the following is returned: • Accepted – the transaction was processed. • Error – the transaction was attempted, but failed for some reason. • Declined – the transaction was declined before it was sent for processing. • Not Found – the transaction lookup did not find any matches.
code		Yes	Int	This is a numeric code that categorizes the response. See Response codes.
actionCode		Optional	Enumeration	This indicates what action to take. The following values are possible: • C = Consumer Parameter Error. The consumer has provided incorrect information. Ask the customer to correct the information. • D = Do Not Retry. Further attempts will fail. • M = Merchant Parameter Error. Your application has provided incorrect information. Verify your information. • R = Retry. The problem is temporary. Retrying the request will likely succeed.
description		Optional	String Max = 100	This is a human readable description of the code element.
detail	tag	Optional	String Max = 1024	This is the classification of the detail element.
	value	Optional	String Max = 30	This is the description of the detail.
txnTime		Yes	dateTime	This is the date and time the transaction was processed by Paysafe.
status		Optional
	code	Conditional	Enumeration	This is the status of the first transaction that matches a lookup request. Possible values are: • AP – Active • C – Complete batch • CB – Clawed back • CL – Cleared transaction • DE – Declined • DI – Disputed • E – Error batch • EX – Expired • F – Failed • GR – Good for reversal • MI – Manual intervention required • PCA – Pending customer approval • PR1 – Re-Presented 1 • PR2 – Re-Presented 2 • PX – Pending cancel • RE – Returned • REF – Rejected final • RV – Reversed • T – Transferred • UM – Unauthorized mandate • W – Pending • X – Cancelled
	effectiveDate	Conditional	dateTime	• This is the date and time at which the status of the lookup request is in effect. • When included in the tag/value pair for the detail element for a response to a mandate request, this is the date the mandate will become active with the bank (counting 5 working days from batching time). You may submit a charge request from midnight on this date, or postdate your charge with a txnTime that has a value of this date or later. If you submit a charge with a date before the mandate effectiveDate, you will receive an error.
currency		Optional	String	The value will be a currency code. This value is returned only in response to lookup requests.
amount		Optional	String Max = 9999999.99	This is the amount of the first transaction that matches a lookup request.
transaction		Optional		This is returned only in response to a lookup request. All transactions that match the lookup request are returned here.
	confirmationNumber	Conditional	String Max = 15	This is the confirmation number returned by Paysafe for a previous transaction.
	merchantRefNum	Optional	String Max = 255	This is the unique ID number associated with the original request. The value is created by the merchant and submitted as part of the original request. This is returned only in response to a lookup request.
	txnTime	Conditional	dateTime	This is the date and time the transaction was processed by Paysafe.
	status	Conditional		This contains code and effectiveDate elements for the transaction. See the status element above in this table for details.
	amount	Conditional	String Max = 9999999.99	This is the amount of the transaction.

To process the response:

Get the response details, which are available via get() methods of the response.

String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision +

            " - " + ddTxnResponse.description;



responseTxt += "Details:" + Environment.NewLine;



if (ddTxnResponse.detail != null)



{



   for (int i = 0; i < ddTxnResponse.detail.Length; i++)



   {



      responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " +



      ddTxnResponse.detail[i].value + Environment.NewLine;



   }



}



responseTxt = responseTxt.Replace("\n", Environment.NewLine);



System.Console.WriteLine(responseTxt);



if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision))



{



   System.Console.WriteLine("Transaction Successful.");



}



else



{



   System.Console.WriteLine("Transaction Failed with decision: " +

   ddTxnResponse.decision);



}

Process based on the decision element. You would insert handling code appropriate to your application. You can also look at the code element to provide more fine-grained control for your application. See Response codes for more details.

Was this page helpful?

On this Page

.NET example
Building charge or credit requests
Building updateShippingInfo requests
Building lookup requests
Building BACS mandate requests (UK)
Building change status requests
Building mandate update requests
Processing the response

Search Overlay

Direct Debit Transactions

charge example – C#

Special considerations for Direct Debit elements

updateShippingInfo example – C#

Lookup example – C#

Building SEPA mandate requests

mandate example – C#

Mandate update example – C#

Was this page helpful?

Thank you for your response!