Search Overlay

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:

  1. Create a new project.

  2. Add a Web Reference.

  3.  Enter the WSDL URL and click the Add Reference button.

  4. 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:

  1. If you are integrated with this type of downstream processor and
  2. 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:

  1. 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);

    }
  2. 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.