Extra Fields For Sepa Direct Debit ("european Ach")

[Max]

ACH should have the following changes to make it suitable for international use.

 

 

* Option that restricts access to the "add account" screen to staff. This is because we are only supposed to enable direct debit after having received a written mandate (signed paper form) from the customer here.

 

* Account information screen needs extra fields, and those needs to be passed to processAch():

• company name if the bank account is registered to a company
• mandate ID that uniquely identifies the form the customer signed (could default to customer number)
• date the customer originally signed the mandate

[Cody]

Can you reference any payment gateways that require such fields? Specifically we're looking for documentation for gateway APIs that require these fields to ensure/verify maximum support across all payment gateways.

[flangefrog]

Here's the NZ gateway I'm going to be using: http://www.flo2cash.co.nz/pdf/Flo2Cash%20Recurring%20Payments%20Integration%20Guide.pdf (see page 9). They need the account/routing number split into four fields and don't require the account type. That's for their hosted option but their API option (which is probably what I will use) requires the same information. Granted, this is not a big problem but it would be nice if I could customise the fields shown on Blesta.

 

Other documentation here: http://www.flo2cash.co.nz/downloadAPI.php Note that this gateway allows fully online direct debits without sending the customer a form.

[Cody]

Here's the NZ gateway I'm going to be using: http://www.flo2cash.co.nz/pdf/Flo2Cash%20Recurring%20Payments%20Integration%20Guide.pdf (see page 9). They need the account/routing number split into four fields and don't require the account type. That's for their hosted option but their API option (which is probably what I will use) requires the same information. Granted, this is not a big problem but it would be nice if I could customise the fields shown on Blesta.

That's their nonmerchant gateway.

 

Other documentation here: http://www.flo2cash.co.nz/downloadAPI.php Note that this gateway allows fully online direct debits without sending the customer a form.

This looks like their CC processing API

 

Looks like this is their bank transfer API, but requires you to set up a "per invoice" recurring record, which you then call for every invoice you wish to process. Wonder if that would be problematic when attempting to pay multiple invoices at once? Kind of a bizarre process, obviously one-time debiting was an after thought.

 

So what's is the process of splitting the account/routing number into the the four fields?:

• Bank Code
• Branch Code
• Account Code
• Suffix Code

 

This particular gateway doesn't look like it requires any changes to Blesta. I'm more interested in seeing a payment gateway that requires additional fields as OP suggested are required for European bank transfers.

[Max]

Can you reference any payment gateways that require such fields? Specifically we're looking for documentation for gateway APIs that require these fields to ensure/verify maximum support across all payment gateways.

 

We play our own gateway, and deal with the acquiring bank directly

Banks are traditional organizations that do not have fancy real-time APIs, but instead expect you to upload a batch of transactions as XML file to be processed overnight.

 

PAIN.008 XML specification used in Europe: http://www.ing.nl/Images/XML-Message-for-SDD-Version-6.0-March-2012_tcm7-119112.pdf

 

Banks charge for each batch you submit to them, so companies tend to save transactions up for a while and only submit a batch once every other week or so.

I can create a payment module that saves the transactions to a table in the database, and generates the XML file on request.

 

Just missing these fields in the Blesta "add ACH account" screen that I need to be passed to processAch() :

 

2.48 MandateIdentification

 

XML Tag: <MndtId>

Occurence: [1..1]

Definition: Unique identification, as assigned by the creditor, to unambiguously identify the mandate.

Data Type: Max35Text

maxLength: 35

minLength: 1

Usage EPC: Mandatory

 

2.49 DateOfSignature

XML Tag: <DtOfSgntr>

Occurence: [1..1]

Definition: Date on which the direct debit mandate has been signed by the debtor.

Data Type: ISODate

Usage EPC: Mandatory

 

2.72 Debtor

XML Tag: <Dbtr>

Occurence: [1..1]

Definition: Party that owes an amount of money to the (ultimate) creditor.

Type: This Message Item is composed of the following PartyIdentification32 element(s):

Name <Nm> [0..1] Text

PostalAddress <PstlAdr> [0..1]

Identification <Id> [0..1]

CountryOfResidence <CtryOfRes> [0..1] Code

ContactDetails <CtctDtls> [0..1]

Usage EPC:

‘Name’ is Mandatory.

‘Name’ is limited to 70 characters in length.

Only two occurrences of ‘AddressLine’ are allowed.

‘OrganisationIdentification’: Either ‘BIC or BEI’ or one occurrence of ‘Other’ is allowed.

‘PrivateIdentification’: Either ‘Date and Place of Birth’ or one occurrence of ‘Other’ is allowed

 

 

Note that <Nm> is the company name in case the bank account is registered to a company.

So need a company field next to the "first name" and "last name" in the "add ACH screen"

 

Mandatory fields are mandatory everywhere in Europe.

But in the Netherlands we do not care about optional fields like address and OrganisationIdentification or PrivateIdentification that specify things like company registration number and date of birth.

But not sure about banks in other countries.

 

Other fields necessary are the IBAN number (<DbtrAcct><Id><IBAN>), but it is similar enough to the account number field you already have.

And the BIC (<DbtrAgt><FinInstnId><BIC>), but that is similar enough to your routing number.

 

Mandate = the paper form the customer signed authorizing us to collect by direct debit.

We need to receive that first. So customer may NOT add his own data to the system, and "add ACH account" screen should be accessible by staff only.

[Cody]

2.48 MandateIdentification

 

XML Tag: <MndtId>

Occurence: [1..1]

Definition: Unique identification, as assigned by the creditor, to unambiguously identify the mandate.

Data Type: Max35Text

maxLength: 35

minLength: 1

Usage EPC: Mandatory

 

If this must be unique, should it be automatically generated by Blesta? Or is there another system you use that generates the agreement document with this value?

 

I wonder if this could work as a custom client field.

 

2.49 DateOfSignature

XML Tag: <DtOfSgntr>

Occurence: [1..1]

Definition: Date on which the direct debit mandate has been signed by the debtor.

Data Type: ISODate

Usage EPC: Mandatory

 

This might work as a custom client field.

 

2.72 Debtor

XML Tag: <Dbtr>

Occurence: [1..1]

Definition: Party that owes an amount of money to the (ultimate) creditor.

Type: This Message Item is composed of the following PartyIdentification32 element(s):

Name <Nm> [0..1] Text

PostalAddress <PstlAdr> [0..1]

Identification <Id> [0..1]

CountryOfResidence <CtryOfRes> [0..1] Code

ContactDetails <CtctDtls> [0..1]

Usage EPC:

‘Name’ is Mandatory.

‘Name’ is limited to 70 characters in length.

Only two occurrences of ‘AddressLine’ are allowed.

‘OrganisationIdentification’: Either ‘BIC or BEI’ or one occurrence of ‘Other’ is allowed.

‘PrivateIdentification’: Either ‘Date and Place of Birth’ or one occurrence of ‘Other’ is allowed

Sounds like billing details that are already recorded for all payment accounts, with the exception of OrganisationIdentification and PrivateIdentification.

 

Mandate = the paper form the customer signed authorizing us to collect by direct debit.

We need to receive that first. So customer may NOT add his own data to the system, and "add ACH account" screen should be accessible by staff only.

If a mandate is required to process payment, why not just prevent the account from being included in any SEPA XML created? I see no reason to prevent clients from entering their payment details when creating an account. If the mandate is a custom field only available/visible to staff then there is no way that a payment can be processed without a mandate value being entered, regardless of whether or not there are bank details recorded for that client.

 

Other questions:

1. Where is this SEPA XML document submitted?
2. Are these documents expected to be submitted in batches, or can they be submitted separately. For example, you have 1000 transactions to process using direct debit. Can you submit 1000 SEPA XML documents, or must it be one single SEPA XML document containing all 1000 transactions?

[Max]

>If this must be unique, should it be automatically generated by Blesta? Or is there another system you use that generates the agreement document with this value?

 

Could default to the Blesta client number, but should be editable in case someone was already using a different product with different numbers before.

Believe the idea is just that if there is a dispute and the bank asks you for a copy of mandate 1234, you should be able to dig up the piece of paper in your administration.

Number only has to be unique in your own administration, it is not some kind of guid that has to be globally unique.

 

 

>I wonder if this could work as a custom client field.

 

Recall processAch() currently does not pass the client number either, so couldn't fetch any custom client field or anything else either.

 

 

>If a mandate is required to process payment, why not just prevent the account from being included in any SEPA XML created? I see no reason to prevent clients from entering their payment details when creating an account. If the

>mandate is a custom field only available/visible to staff then there is no way that a payment can be processed without a mandate value being entered, regardless of whether or not there are bank details recorded for that client.

 

What should be returned in processAch() in that case? status => pending?

 

 

>Where is this SEPA XML document submitted?

 

Small customers like us have to upload it manually to an Internet banking site.

Requires two factor authentication to get in, so not something you automate.

 

 

>Are these documents expected to be submitted in batches, or can they be submitted separately. For example, you have 1000 transactions to process using direct debit. Can you submit 1000 SEPA XML documents, or must it be one single

>SEPA XML document containing all 1000 transactions?

 

Single document.

(Believe there is a 100,000 transactions per file limit, not a limitation you will likely run into).

 

[flangefrog]

That's their nonmerchant gateway.

Yes that's right, although with either credit cards or direct debits it can create create an account which could be used by the Blesta payment account system. Not much point in using the hosted option for direct debits though as PCI DSS doesn't apply.

Looks like this is their bank transfer API, but requires you to set up a "per invoice" recurring record, which you then call for every invoice you wish to process. Wonder if that would be problematic when attempting to pay multiple invoices at once? Kind of a bizarre process, obviously one-time debiting was an after thought.

Are you talking about the latency for multiple HTTP requests? Just under that method they have another one for scheduling multiple transactions for different clients.

 

So what's is the process of splitting the account/routing number into the the four fields?:

• Bank Code
• Branch Code
• Account Code
• Suffix Code

Well it would be very easy to split the two fields into four values, the point is that nobody in New Zealand would know what to type in the two fields as every bank here uses four fields for that information. So it's possible to implement the gateway already, it would just be a lot more user friendly in NZ if it could be changed to multiple fields.

[Max]

Sounds like billing details that are already recorded for all payment accounts, with the exception of OrganisationIdentification and PrivateIdentification.

 

Company name is missing in the admin "add ACH account" screen.

Only have first and last name.

 

[Cody]

Company name is missing in the admin "add ACH account" screen.

Only have first and last name.

 

Company name is under the client's account.

[Max]

Company name is under the client's account.

 

Why not in the add ACH account screen as well?

You do have all other information there.

 

 

Also keep in mind that it is non-trivial to fetch any information from under the client's account.

    /**
     * Process an ACH transaction
     *
     * @param array $account_info An array of bank account info including:
     *     - first_name The first name on the account
     *     - last_name The last name on the account
     *     - account_number The bank account number
     *     - routing_number The bank account routing number
     *     - type The bank account type (checking or savings)
     *     - address1 The address 1 line of the card holder
     *     - address2 The address 2 line of the card holder
     *     - city The city of the card holder
     *     - state An array of state info including:
     *         - code The 2 or 3-character state code
     *         - name The local name of the country
     *     - country An array of country info including:
     *         - alpha2 The 2-character country code
     *         - alpha3 The 3-character country code
     *         - name The english name of the country
     *         - alt_name The local name of the country
     *     - zip The zip/postal code of the account holder
     * @param float $amount The amount to debit this account
     * @param array $invoice_amounts An array of invoices, each containing:
     *     - id The ID of the invoice being processed
     *     - amount The amount being processed for this invoice (which is included in $amount)
     * @return array An array of transaction data including:
     *     - status The status of the transaction (approved, declined, void, pending, reconciled, refunded, returned)
     *     - reference_id The reference ID for gateway-only use with this transaction (optional)
     *     - transaction_id The ID returned by the remote gateway to identify this transaction
     *     - message The message to be displayed in the interface in addition to the standard message for this transaction status (optional)
     */

    public function processAch(array $account_info, $amount, array $invoice_amounts=null);

Not just no company name, but I am also not passed a client ID there.

Perhaps by jumping through some hoops, I can learn which customer it concerns by querying the invoice, but invoice_amounts has a default parameter null which could indicate that there is not always an invoice either...

[Max]

Hmm, you do have a "company" field in the CLIENTAREA'S "add ach" screen ( http://demo.blesta.com/client/accounts/add/ach/ ) as opposed to the admin's "add ach" screen.

However what you enter there is not actually saved.

[Cody]

Hmm, you do have a "company" field in the CLIENTAREA'S "add ach" screen ( http://demo.blesta.com/client/accounts/add/ach/ ) as opposed to the admin's "add ach" screen.

However what you enter there is not actually saved.

 

Thanks. CORE-1165.

[Cody]

>If this must be unique, should it be automatically generated by Blesta? Or is there another system you use that generates the agreement document with this value?

 

Could default to the Blesta client number, but should be editable in case someone was already using a different product with different numbers before.

Believe the idea is just that if there is a dispute and the bank asks you for a copy of mandate 1234, you should be able to dig up the piece of paper in your administration.

Number only has to be unique in your own administration, it is not some kind of guid that has to be globally unique.

 

 

>I wonder if this could work as a custom client field.

 

Recall processAch() currently does not pass the client number either, so couldn't fetch any custom client field or anything else either.

You have the contact_id, you can load the Contacts model and call Contacts::get().

 

Actually, looks like that isn't passed through after all. Will look into adding it.

 

>If a mandate is required to process payment, why not just prevent the account from being included in any SEPA XML created? I see no reason to prevent clients from entering their payment details when creating an account. If the

>mandate is a custom field only available/visible to staff then there is no way that a payment can be processed without a mandate value being entered, regardless of whether or not there are bank details recorded for that client.

 

What should be returned in processAch() in that case? status => pending?

Error because the payment can not be processed until the mandate is set. This is equivalent to submitting a payment without a credit card number.

 

>Where is this SEPA XML document submitted?

 

Small customers like us have to upload it manually to an Internet banking site.

Requires two factor authentication to get in, so not something you automate.

I see, so you would need some utility within the staff interface to download the SEPA XML file for all payments that should be processed? This, obviously, makes it impossible to automatically process bank transfers since they can not be processed through a payment gateway. This is just like batch payments, except instead of automatically processing the batch an XML file is built.

 

>Are these documents expected to be submitted in batches, or can they be submitted separately. For example, you have 1000 transactions to process using direct debit. Can you submit 1000 SEPA XML documents, or must it be one single

>SEPA XML document containing all 1000 transactions?

 

Single document.

(Believe there is a 100,000 transactions per file limit, not a limitation you will likely run into).

Looking at the format of the XML document, 100,000 transactions would probably be a 50 MB file.

[Max]

I see, so you would need some utility within the staff interface to download the SEPA XML file for all payments that should be processed? This, obviously, makes it impossible to automatically process bank transfers since they can not be processed through a payment gateway. This is just like batch payments, except instead of automatically processing the batch an XML file is built.

 

Yes, was thinking about just creating a button for spitting out the XML on the manage page of the payment module.

 

Note that if you do use a gateway for ACH payments, it ends up being batch processed by them as well.

So be aware that unlike with credit cards a gateway can conduct no real-time checks on the information provided either, and you do not get any useful feedback until the day after.

This applies to both Europe, the US and probably everywhere else.

[Cody]

Note that if you do use a gateway for ACH payments, it ends up being batch processed by them as well.

So be aware that unlike with credit cards a gateway can conduct no real-time checks on the information provided either, and you do not get any useful feedback until the day after.

This applies to both Europe, the US and probably everywhere else.

 

Yes, we're well aware of that. The difference is that ACH is processed through a payment gateway, and are submitted individually not as a batch.

[Max]

The difference is that ACH is processed through a payment gateway, and are submitted individually not as a batch.

 

Believe submitting as a batch exists as well.

 

Bank_of_America_NACHA_File_Specs.pdf

 

Might not be advertised/offered to smaller companies though.

[Cody]

Believe submitting as a batch exists as well.

 

Bank_of_America_NACHA_File_Specs.pdf

 

Might not be advertised/offered to smaller companies though.

 

NACHA applies to payment gateway processors.

 

Blesta will never be a payment gateway processor, so it will never implement NACHA standards.

[Max]

FYI the Dutch banks have just released the eMandate technical specifications.

Allowing you to redirect the customer to the online banking website of his own bank, and confirm the direct debit authorization there with the 2 factor authentication system banks use. This is similar to how iDeal works, but for recurring payments.

 

http://www.incassomachtigen.nl/wp-uploads/eMandates-Implementation-Guide-B2C.pdf

http://www.incassomachtigen.nl/wp-uploads/eMandates-Creditor-Libraries-Integration-Manual.pdf

 

It replaces paper authorization forms that the customer needs to print, sign and return.

Only handles the customer giving you authorization part though, you then still need to use PAIN XML batch files to actually collect the funds.

 

And still requires Blesta core changes to implement.