|
|
Direct Debit Documentation
This document describes collecting payments using direct debit via TargetPay.com. You may call the API as described in paragraph 2.
The next office day at 08:00 AM the transactions are offered to the bank. Until this moment the status is 'open'. From this moment it takes the bank 10 working days to process the transaction. During this period the transaction status is 'Processing'
After 10 working days we receive the status from the bank, on this moment your reporturl receives a status update from our server.
2.1 Call
You submit a direct debit transaction by calling:
https://www.targetpay.com/directdebit/start
Using the parameters:
Parameter |
Name |
Format |
Required |
rtlo | Layoutnumber | Numeric | Yes |
description | Description | Alphanumeric | Yes |
userip | Your customers IP address | Alphanumeric | Yes |
amount | Tariff in Euro cents | Numeric | Yes |
country | Country code customer | Alphanumeric | Yes |
mandate | Unique ID of the SEPA mandate | Alphanumeric | Yes |
mandatestart | Start date of the SEPA mandate | Alphanumeric | Yes |
cbank | IBAN bank account customer | Alphanumeric | Yes |
cname | Name customer | Alphanumeric | Yes |
salt | Some random characters for the reporturl checksum verification. Max. 32 characters long. | Alphanumeric | Yes |
reporturl | Report URL | Alphanumeric | Yes |
email | Your customer's E-mail address | Alphanumeric | No |
returnurl | Return URL | Alphanumeric | Yes |
duedate | Transaction date | YYYY-MM-DD | No |
securitylevel | Security level | Numeric | Yes |
oneoff | One-off debit | 0 or 1 | No |
test | Test mode | 0 or 1 | No |
Description of each parameter:
- rtlo
The subaccount where the sales need to be registered. To check or create a subaccount see: subaccounts.
- description
A clear description of the service. Only letters or numbers, maximum 32 characters.
- userip
The customers IP address or other unique customer identification number
- amount
The amount in eurocents. Minimum value: 84 cent, maximum value: 100000 cent (€ 0,84 - € 1.000,00)
- country
The customers coutrycode in ISO 3166-1 format. Direct Debit is currently only available in the Netherlands, so you may use the value NL.
- mandate
The unique identifier for the mandate in your administration.
- mandatestart
The date on which the debtor signed your mandate. Use “2009-11-01” for mandates that existed before the 1st of February 2014, and the actual date for mandates that are created after.
- cbank
Customers Bankaccount. Only digits, no dash, colon, semicolon etc. Account number 1234.56.789 becomes 123456789
For ex-Postbank/ING customers the letter P is ommitted. So giro P12345678 becomes 12345678
- cname
Your customers bank account name.
- reporturl
As soon as the status of the payment changes we will call this URL from our server. We will add 4 parameters to this URL:
- trxid: Transaction ID
- rtlo: layoutnumber
- status: Payment status. Possible values are:
- Success: The bank processed the payment succesfully.
- Chargeback: The customer did a chargeback.
- Rejected: The transaction has been refused by the bank.
- checksum: Lowercase md5 value calculated over the trxid, rtlo, status and salt. Example: suppose the value for salt was 'e381277' the outcome of the checksum will be $checksum = md5($_POST["trxid"].$_POST["rtlo"].$_POST["status"]."e381277");
- email
Your customers E-mail address. You may use this field if you want us to send an E-mail to your customer. We will add the returnurl to this E-mail where the costomer may check the order status.
- returnurl
If you provided an E-mail address in the E-mail field this URL will be send to your customer. We will add the parameter trxid with the transaction number.
- duedate
If you want to postpone the Direct debit transaction, you may provide us with a transaction date in the format YYYY-MM-DD. We will offer the transaction to the bank on this date. Until this date the transaction status will be open. If you do not provide a due date, the transaction will be offered to the bank on the same day. If the due date is in the weekend or on a holiday, the transaction will be offered on the next workday.
- securitylevel
You may choose how strict the security checks will be, by setting this parameter. It is designed to prevent double payments. The higher the level the more secure. It is wise to choose the level as high as possible. If you use Direct Debit to charge a customer once a month, you should choose level 5(very strict) because one bank account may not be charged more than once on that day. If it is possible to charge the same account more than once a day you should choose a lower level. A payment wil not be accepted by TargetPay if:
- 5: ... this bankaccount already has been charged over the last week. (very strict)
- 4: ... this bankaccount still has open transactions
- 3: ... this bankaccount still has open transactions with the same amout.
- 2: ... this bankaccount still has open transactions with the same amout and the same description.
- 1: No checks. The payment will always be accepted.
- oneoff
If you set this parameter to 1, the debit will be marked as a one-off. This means it will show as a one-off in the consumer's banking environment and the mandate should be unique for this layoutcode.
- test
If you set this parameter to 1, you activate the testmode. In this case the transaction will not be executed ant the transation ID will always be '12345678'. If you request for the status of this ID the answer will always be '000000 OK'.
2.2 Response codes
If the transaction has been submitted succesfully the response will be:
000000 OK|#transaction-ID
If the transaction has not been submitted one of the following errormessages will be returned:
TP0001 No layoutcode specified
TP0002 Amount too low
TP0003 Amount too high
TP0004 Invalid return URL
TP0005 Invalid or no report URL
TP0006 No description specified
TP0007 Invalid e-mailaddress
TP0009 Invalid or no user IP given
TP0010 No value for salt specified
TP0011 Value for salt is too long
TP0012 Invalid or no securitylevel set
TP0014 No bankaccount given
TP0015 No or invalid country given
TP0016 TargetPay account does not exist
TP0017 No customer name given (cname)
TP0018 No IBAN given
TP0019 No mandate given
TP0020 No mandatestart given
TP0021 Invalid mandatestart given
TP0022 SEPA cannot be in live and test mode at the same time
TP0999 Layoutcode expected, customer number given. Please use your correct layoutcode.
TP1000 Refused: invalid bankaccount, fails IBAN validation
TP1001 Refused: same account already billed last week
TP1002 Refused: same account still pending
TP1003 Refused: same account and amount still pending
TP1004 Refused: same account, amount AND description still pending
TP1006 Refused: user made a chargeback in the last 12 months
TP1007 Refused: not allowed to use direct debit
TP1008 Refused: only allowed after iDEAL/bank wire transaction
TP1009 Refused: duplicate mandate found for this one-off payment, must be unique
3.1 Call
You may also submit an active status request. This may be done by calling:
https://www.targetpay.com/directdebit/check
Using the parameters:
Parameter |
Name |
Format |
Manditory |
trxid | Transaction ID | Number | Yes |
rtlo | Layout number | Number | Yes |
checksum | Checksum | Number | Yes |
once | 'Already checked' message? | 0 of 1 | Yes |
Description of each parameter:
- trxid
Transaction ID, returned to you in the previous step(max. 16 digits)
- rtlo
Layoutnumber (identical as in paragraph 2.1)
- checksum
Used for verification $checksum = md5($trxid.$rtlo.'salt'); The calculation is the same as the reporturl without the amounmt parameter.
- once
If you provide the value once=1, the 00000 OK status will be returned only once for thie transaction. Each next time you will receive the errormessage TP00014 Already redeemed at XXXX-XX-XX XX:XX:XX.
If you provide the valuel once=0 the staus will always be 000000 OK.
If you are not sure, always use the value 1. In this way you are sure your product will be delivered only once if your customer refreshes the page.
3.2 Resultcodes
You will receive the current status of the transaction in the response:
000000 OK
Means the transaction has been processed by the bank.
Other statusses:
000001 Open - Payment has not been submitted to the bank yet
000002 Processing - Payment has been submitted, but is still being processed
000003 Chargeback - The money has been chargebacked by the customer
000004 Rejected - The transaction has been refused by the bank
Possible errormessages:
TP0014 Already redeemed at XXXX-XX-XX XX:XX:XX
TP0020 No layoutcode given
TP0021 No transaction ID given
TP0022 No transaction with this ID
TP0023 Layoutcode doesn't match transaction
TP0024 Checksum incorrect..
|
|
|
|