DalPay Checkout Integration Guide

Transcription

DalPay Internet Billing
Checkout Integration Guide
Online Payments
Version 1.3
Last revision: 01/07/2011
For public release
Copyright © 2011 Snorrason Holdings ehf
Page 1 of 38
Version 1.3
For public release
Page 2 of 38
REVISION HISTORY
4
INTRODUCTION
5
HOW DOES DALPAY CHECKOUT WORK?
FIGURE 1: Transaction Flow
5
5
WHAT THE CUSTOMER SEES
6
Payment Card Details Screen Only (Single Page Checkout)
Step 1: Payment Type and Customer Country
Step 2: Customer Information (Contact Details, Billing Address)
Step 2a: Customer Information (Different Shipping Address)
Step 3: Payment Card Details
Step 4c: Confirmation Receipt Page (Simple Continue Button Mode)
Step 4d: Confirmation Receipt Page (Instant Silent Post Mode)
6
7
8
9
10
11
12
GETTING STARTED IMPLEMENTATION NOTES
13
ORDER PAGES INITIALLY BLOCKED
ENABLING THE INTERNAL TEST CARD
TRANSACTION TYPES
TRANSACTION STATES
13
14
15
16
TRANSACTION POST API
17
Transaction Post API input parameters
Example Input Minimum Mandatory Fields
Example Input Adding Shipping Fields
Example Input Adding Discount Field
Example Input Adding Sales Tax Field
Most Frequent Account Setting-Related Errors
Common Error Messages
17
21
21
21
21
22
23
INTERNATIONALIZATION
25
INTERNATIONAL LANGUAGE SUPPORT
INTERNATIONAL CURRENCY SUPPORT
25
26
INSTANT SILENT POST
27
Order Page Silent Post Settings
Silent Post Fields
Dynamic Custom Receipt Message
Response From Your Listening Script
Responding With a Login or Custom Download Link Generated On-The-Fly
27
28
31
32
33
AFFILIATE MARKETING FEATURES
34
CONFIRMATION PAGE AFFILIATE CODE SETTINGS
34
WEBSITE COMPLIANCE
35
Website Content
Minimum Test Plan
35
35
PAYMENT CARD INDUSTRY DATA SECURITY STANDARD COMPLIANCE
37
What Must Never Be Stored
DalPay Checkout and Compliance
FIGURE 2: Extract from the PCI DSS Version 2.0
Version 1.3
For public release
37
38
38
Page 3 of 38
Revision History
Version
Change Notice
1.0
Date
Released
July 1, 2007
Pages
Affected
All
Remarks
1.1
July 1, 2009
Introduction,
pay_type update,
Screen shot changes
Screen shot changes
p. 5, 6-12,
15
PCI DSS 1.2 applies
1.2
Jan 1, 2010
p. 6-12
PCI DSS 1.2.1 applies
1.3
July 1, 2011
Screen shot changes,
Figure 2
p. 38
PCI DSS 2.0 applies
First release
PCI DSS 1.1 applies
The latest version of this document can be downloaded here:
https://www.dalpay.com/en/dalpayapi/DalPay_Checkout_Integration_Guide.pdf
Supporting files:
https://www.dalpay.com/en/dalpayapi/DalPay_ISO_3166-1_country_list_en.csv
https://www.dalpay.com/en/dalpayapi/DalPay_CA_abbr_provinces_en.csv
https://www.dalpay.com/en/dalpayapi/DalPay_US_abbr_states_en.csv
Version 1.3
For public release
Page 4 of 38
Introduction
This integration guide describes DalPay Checkout, DalPay’s hosted payment
page integration method for payment card or bank ePayment transactions.
DalPay Checkout is a hosted payment processing solution that securely
handles all of the steps in processing a transaction, including:
•
•
•
•
Collection of customer payment information through a secure hosted form,
Generation of a receipt page with a copy to the customer by email,
Secure transmission to the DalPay payment gateway for transaction processing,
Secure storage of cardholder information (including for optional recurring billing).
DalPay Checkout does not require merchants to collect, transmit or store
sensitive cardholder or bank account information to process transactions.
DalPay Checkout is equivalent to Authorize.net’s SIM (Server Integration
Method) or Simple Checkout. For our solution equivalent to Authorize.net’s
AIM (Advanced Integration Method) see the DalPay Direct Integration Guide.
How Does DalPay Checkout work?
FIGURE 1: Transaction Flow
1. The customer clicks on a buy now button*, or enters
their contact and address information via a form or
shopping cart installed at the merchant’s website.
2. The merchant’s website redirects the customer
securely to DalPay Checkout - to enter any missing
contact information, and their payment card or bank
account details.
3. DalPay redirects the customer securely (if needed) to
their bank’s website for online bank ePayment or 3-D
Secure** authentication, and back to DalPay Checkout.
4. If setup, the merchant’s server receives a Silent Post
response for the successful transaction from DalPay’s
server, and returns an optional dynamic custom receipt
message.
5. DalPay Checkout displays its confirmation receipt
page (the fixed custom confirmation page message and
if received the dynamic custom receipt message) and
sends a copy of the receipt to the customer by email.
*DalPay Buy Now buttons are for one item per order (different product variations such as
size or quantity, and order quantity for that single item are supported, as is setup of recurring
billing). Equivalent to PayPal Payment Buttons or Authorize.net’s Simple Checkout.
**Verified by Visa, MasterCard SecureCode, JCB J/Secure or AMEX SafeKey.
Version 1.3
For public release
Page 5 of 38
What the Customer Sees
You can view larger versions of these co-brandable screens here:
https://www.dalpay.com/en/support/customer_checkout_screens.html
Payment Card Details Screen Only (Single Page Checkout)
TIP: POST customer contact and address information to DalPay for single page checkout. (See
p. 17.)
Version 1.3
For public release
Page 6 of 38
Step 1: Payment Type and Customer Country
TIP: Icons to accompany selection of the pay_type on your webpage:
https://www.dalpay.com/en/dalpayapi/checkout/icons_for_dalpay_checkout.zip
TIP: The ISO 3166-1 alpha-2 list for selection of cust_country_code:
Version 1.3
For public release
Page 7 of 38
Step 2: Customer Information (Contact Details, Billing
Address)
TIP: alpha-2 lists for cust_state; Canada, and the United States:
Version 1.3
For public release
Page 8 of 38
Step 2a: Customer Information (Different Shipping Address)
TIP: If an order page’s settings are set to ‘address’ or ’address+phone’ these Shipping
Address fields are revealed beneath the Billing Address fields, after the customer selects
the radio button for ‘Use different shipping address’.
TIP: alpha-2 lists for ship_state; Canada, and the United States):
Version 1.3
For public release
Page 9 of 38
Step 3: Payment Card Details
This step is followed* by a decline screen or confirmation receipt page if the
transaction was accepted and charged.
*3-D Secure authentication via redirect is also attempted at this stage.
TIP: If a bank ePayment transaction was selected, the customer is prompted to redirect to
their bank to enter details and authenticate the transaction.
Version 1.3
For public release
Page 10 of 38
Step 4c: Confirmation Receipt Page (Simple Continue Button
Mode)
TIP: The continue button can be replaced with your own message from the ‘Simple Continue
Button Label’ setting in the order page settings.
Clicking on the Simple Continue button takes a customer to the URL set in the
‘PostURL’ for that order page.
You can also set the ‘Simple Continue Button Force Press’ mode from the order
page settings. (That pops up a dialog box prompting the user if they try to
leave the confirmation receipt page without clicking on the button.)
IMPORTANT NOTE:
If Silent Post Callback is enabled the Simple Continue Button is replaced by Instant Silent
Post’s ‘Dynamic Custom receipt message’ as returned from a listening script on your server.
Version 1.3
For public release
Page 11 of 38
Step 4d: Confirmation Receipt Page (Instant Silent Post
Mode)
TIP: When ‘Silent Post Callback’ is enabled, with a silent post password set, the DalPay server
POSTs order related fields set in ‘Silent Post Fields’ in realtime to a listening script on your
server for successfully charged accepted orders only (not declined transactions).
Your script validates the response, then performs its actions (for example
starting a process for service delivery) and returns a dynamic custom receipt
message. (See p. 27.)
TIP: If you require notification of all transaction status changes to a listening script on
your server, including declines, chargebacks, accepted/declined rebillings, and other
exceptions, please refer to the Merchant Server Notifications Integration Guide.
Version 1.3
For public release
Page 12 of 38
Getting Started Implementation Notes
The DalPay Checkout APIs are a subset of the DalPayAPI which is a RESTful
web service using HTTP post over SSL.
POST payment type, customer contact and address information securely to
DalPay Checkout and achieve single page checkout (showing page 3, payment
card details only).
If you pass in any name-value pairs incorrectly, the DalPay Checkout system
ignores the variables incorrectly posted and displays to the customer all three
DalPay Checkout pages; Page 1: payment type and customer country,
followed by Page 2: customer contact details and cardholder address (email
and phone are mandatory), then Page 3: payment card details.
On success, transaction details are posted back to your server via Instant
Silent Post with callback to display a dynamic custom receipt message at the
bottom of the DalPay Confirmation Receipt page.
Order Pages Initially Blocked
When issued a fresh DalPay account, up to five order pages can
be setup within it free of charge, and all will be initially blocked.
Only orders placed using the Visa internal test card from self-whitelisted IPs
are permitted when an order page is blocked.
You must complete your website content (including terms and conditions;
delivery policy, refund policy and privacy policy) and then run test orders.
Only after demonstrating full line item detail being passed in item descriptions,
and completed website content, can the Risk Department sign you off to go
live, and set the order page(s) active:
Version 1.3
For public release
Page 13 of 38
Enabling the Internal Test Card
The internal test Visa card is enabled from the Merchant Menu, ‘Run test
order’. Click on 'New' to get a fresh {{Name on Card Code}} such as FhXgiByJ
and then enable it (‘no’ to ‘yes') for 360 minutes of use.
(You can re-use each Name on Card Code, enabling for 360 minutes each
time. Clicking to enable a Name on Card Code automatically adds your IP to
the AllowedIPs whitelist for that Name on Card Code.)
Once a Name on Card Code is enabled, you select Visa and use the test card
number and that Name on Card Code:
(pay_type = ‘Visa’)
Card Number = 4222222222222
Name on Card = {{Name on Card Code}}
Expiry Date = 07/12
Card Security Code = ‘999’.
If you wish to receive a decline response from the test card set the Next
action to ‘declined’:
(And to ‘error’ if you wish to receive an error response from the test card.)
Version 1.3
For public release
Page 14 of 38
Transaction Types
Debit (debit)
Transaction debits are authorized and captured immediately and will be
settled within 24 hours, being automatically settled by 06:00 UTC on the
current or following day. Debits may be refunded (or voided if supported).
Void (void)
Transaction voids will cancel an existing debit or captured pre-authorization (if
supported). In addition, non-captured pre-authorizations can be voided to
prevent future capture. Voids can only occur if the transaction has not been
settled. For both unsettled debits and pre-authorizations an authorization
reversal will be attempted first (if supported).
Refund (refund)
Transaction refunds will reverse a previously settled transaction. If the
transaction has not been settled, an authorization reversal (void) will be tried
first automatically instead of a refund.
Only if Approved and Enabled by DalPay Support:
Pre-Authorization (auth_only)
Transaction pre-authorizations (if supported) are authorized immediately but
are not flagged for immediate settlement. These transactions must later
be flagged for settlement using the capture transaction type.
Pre-authorizations remain active for three to thirty days depending on the card
issuing bank.
Capture (capture)
Transaction captures (if supported) flag existing pre-authorizations for
settlement. Only pre-authorizations can be captured. Captures can be
submitted for an amount equal to, or less than the original pre-authorization.
Version 1.3
For public release
Page 15 of 38
Transaction States
Accepted
State accepted transactions have been successfully charged to a customer’s
debit or credit card, or a refund successfully credited.
Declined
State declined are transactions not charged to a customer’s payment card or
bank account, either due to a hard decline by the card issuer, or a block due to
a fraud scrubbing reason.
Error
State error are transaction attempts that passed gateway validation but were
rejected either by the DalPay processor or one of our upstream providers
before authorization could be attempted with the issuing bank.
Pending or Posted
State pending or posted are transactions posted by the DalPay gateway but
waiting for confirmation due to a delayed or batch-oriented settlement model.
Redirected
State redirected is where a customer has been temporarily redirected away
from DalPay Checkout either to their bank for an online ePayment transfer, or
payment card issuer for 3-D Secure authentication.
Suspended
State suspended is where an event such as a confirmation receipt email
bouncing back from the customer, as detected by DalPay, has caused the
transaction to be put on hold pending possible refund.
Voided
State voided are transactions refunded before being settled with the acquiring
bank, so the customer’s payment card was not charged the amount, only
authorized.
Version 1.3
For public release
Page 16 of 38
Transaction Post API
To initiate a DalPay Checkout transaction, the following HTTP name/value pairs
should be HTTP posted to our gateway web service under SSL.
QUICK TIP: Input should be percent encoded and correctly
escaped (using htmlentities encoding for example). Default character
encoding is UTF-8 but legacy encoding can be set per pageID as
needed. Legacy encodings are stored internally as UTF-8.
At least one line item entry (for order information) must be posted.
Post each individual line item that makes up an order using item1_desc, item2_desc, etc;
posting of aggregate total invoice/cart amounts is strongly discouraged and may result in your
account not being approved to go live by the Risk Department. (See p. 19.)
Web service Location: https://secure.dalpay.is/cgi-bin/order2/processorder1.pl
Transaction Post API input parameters
Name
Type
Size
MinMax
Example Value
Notes
mer_id
TEXT
6-6
999994
6 digit merchant number.
pageid
TEXT
1-3
1
next_phase*
TEXT
1-20
paydata
pay_type
TEXT
1128
Visa
Visa Electron
Mastercard
Maestro
American Express
Discover
Carte Blanche
JCB
China Unionpay
OR
Bank Epayment
The order page sub-account
within the merchant account
specified by mer_id. Each
selling URL or currency should
have its own order page.
Initiate single page checkout if
all required fields are present.
Payment type for correct
routing. Some merchants will
have a subset of the full set of
card types enabled.
Transaction
Setup Fields
valuta_code*
TEXT
3
USD, GBP, EUR, ISK
langcode*
TEXT
2-5
en, es, is,
en-GB, en-US, en-CA
Version 1.3
When targeting US customers
do not offer Visa Electron,
Maestro, Cart Blanche or China
Unionpay as they are not
issued/familiar in the US.
For pay_type icons see end
note+
ISO 4217 code for checkout
currency. (Will be converted
using a rate favourable to the
cardholder if different from
order page valuta setting.)
ISO 639-1 code for checkout
language.
For public release
Page 17 of 38
Customer
Contact Details
cust_name
TEXT
1-40
Ms Secretary
Customer’s name (can be
different from cardholder
name).
Customer’s company name.
cust_company*
TEXT
1-40
Acme Inc
cust_email
TEXT
5-80
name@domain.tld
cust_phone
TEXT
7-20
+3544122600
cust_fax*
TEXT
7-20
4661935
cust_address1
TEXT
1-60
100 Jump Street
Billing address line 1.
cust_address2*
TEXT
1-30
Second Floor
cust_city
TEXT
1-30
Some City
Billing city.
cust_state
TEXT
1-20
cust_zip
TEXT
1-10
cust_country_code
TEXT
2-3
FL, AE, BC, Lincolnshire,
Biscay
OR
N/A if no state
33101,
SE1 9LT OR
99999 if no postal codes
US, GB, IS
USA, GBR, ISL
Billing state, county or
province.
If cust_country_code = ‘CA’ or
‘US’ see end note++
Billing ZIP or Postcode. Refer
to the International Postal
Codes Integration Guide.
Billing country ISO 3166-1
alpha-2 or alpha-3. See end
note+++
ship_address1**
TEXT
1-60
100 Jump Street
Shipping address line 1.
ship_address2**
TEXT
1-30
Second Floor
ship_city**
TEXT
1-30
Some City
Shipping city.
ship_state**
TEXT
1-20
ship_zip**
TEXT
1-10
Biscay
OR
N/A if no state
33101,
SE1 9LT OR
ship_country_code**
TEXT
2-3
US, GB, IS
USA, GBR, ISL
ship_phone**
TEXT
7-20
+3544122600
Shipping state, county or
province.
If ship_country_code = ‘CA’ or
‘US’ see end note++
Shipping ZIP or Postcode.
Refer to the International
Postal Codes Integration
Guide.
Shipping country ISO 3166-1
alpha-2 or alpha-3. See end
note+++
Numeric with or without +
prefix.
Must be in valid email address
format.
prefix.
prefix.
Customer Billing
Address
Customer
Shipping
Address
Version 1.3
For public release
Page 18 of 38
Order
Information
Details
num_items
TEXT
1-20
1
item1_desc
TEXT
1256
Some Widgets,
Service (1 year),
Online Widget delivered in
1-2 weeks
item1_price
TEXT
1-10
129.00
item1_qty
TEXT
1-20
1
item2_desc*
TEXT
1128
item2_price*
TEXT
1-10
Some Widgets,
Service (1 year),
Online Widget delivered in
1-2 weeks
500.00
item2_qty*
TEXT
1-20
1
…
Shipping/
Delivery Fields
item7_desc*
TEXT
item7_price*
item7_qty*
TEXT
TEXT
1256
1-10
1-20
USPS Priority Mail,
FedEx Express Saver, ...
20.07, 40.56
1
The maximum number of line
items posted. For example: if
your last product is
item7_desc, item7_price and
item7_qty, num_items value
has to be 7.
Line item description. If a
service specify time that
service purchase covers. If
delivery time varies specify
timeframe in the line item
description.
Value in the currency set as
valuta_code for this pageID.
The multiplier for item1_price.
Line item description as above.
Value in the currency set as
valuta_code for this pageID.
The multiplier for item2_price.
You can send in as many
additional optional line items
up to the num_items. Only the
first is mandatory.
Only ship to the billing address
with a full AVS match unless
you have performed secondary
screening on the ship address.
Ship with signature on delivery
recommended.
Send a line item for the
shipping cost as the last item
posted (for example item7).
Use sales_discount_exclude
and/or sales_tax_exclude to
exclude shipping from discount
or tax as applicable.
Discount Fields
sales_discount_amou
nt*
TEXT
1-10
19.95
sales_discount_factor
*
sales_discount_exclud
e*
TEXT
1-10
0.05 (5%) , 0.25 (25%)
TEXT
1-20
2,4,5 (exclude items 2, 4 and
5 from the discount
calculation)
Version 1.3
Fixed discount amount (will be
subtracted from the total
calculated for the item fields).
Will be displayed as a % as
well.
Discount multiplier based on
the item fields totalled.
Exclude items, such as line
item for shipping/delivery cost,
from the discount.
For public release
Page 19 of 38
Taxation Fields
sales_tax_amount*
TEXT
1-10
10.00
sales_tax_factor*
TEXT
1-10
0.10 (10%) , 0.175 (17.5%)
sales_tax_exclude*
TEXT
1-20
2,4,5 (exclude items 2, 4 and
5 from the tax calculation)
user1*
TEXT
1256
User2*
TEXT
1256
This is an order note
field. Don’t deliver
before 10am. Thank you.
{3a768eea-cbda-4926-a82d831cb89092aa}
Rebilling Fields
Fixed taxation amount (will be
added to the total calculated
for the item fields). Will be
displayed as a % as well.
Taxation multiplier based on
the item fields totalled.
Exclude items, such as line
item for shipping/delivery cost,
from taxation.
For automatic pre-authorized
recurring billing for
subscriptions please refer to
the DalPay Checkout Recurring
Billing Integration Guide.
User Fields
Fields you set and wish passed
through to you such as GUIDS
or other data.
Not visible to customers during
checkout. Included in the
merchant confirmation email.
and stored in the transaction
database.
User fields can be posted back
via Instant Silent Post and can
be included in Merchant Server
Notifications.
Maximum of 256 characters
per user field.)
(You can pass in up to 10 user
fields, i.e. user1, user2, user3,
user4, user5, ... , etc.
Fields marked with * in the table above are optional.
Fields marked with ** are optional until one in their group is passed in when they become
mandatory within that group.
End Notes
+For single page checkout customers must, choose the pay_type on your website prior to
redirect to DalPay Checkout. Icons to use are here:
https://www.dalpay.com/en/dalpayapi/checkout/icons_for_dalpay_checkout.zip
++If cust_country_code or ship_country_code is:
'CA' then validate against this list:
http://www.dalpay.com/en/dalpayapi/DalPay_CA_abbr_provinces_en.csv
'US' then validate against this list:
http://www.dalpay.com/en/dalpayapi/DalPay_US_abbr_states_en.csv
+++The alpha-2 to send in for each country is shown in the list here:
(The CSV file is UTF-8 to preserve the correct names of some of the more exotic countries.)
Version 1.3
For public release
Page 20 of 38
Example Input Minimum Mandatory Fields
https://secure.dalpay.is/cgibin/order2/processorder1.pl?mer_id=999994&pageid=2&next_phase=paydata&pay_type=V
isa&cust_name=Ms Secretary&cust_address1=100 Jump Street&cust_city=Some
City&cust_state=FL&cust_zip=33101&cust_country_code=US&cust_email=name@domain.tl
d&cust_phone=+354 412 2600&num_items=1&item1_desc=8Gb iPod Nano
Green&item1_price=129.00&item1_qty=1
Example Input Adding Shipping Fields
d&cust_phone=+354 412 2600&ship_address1=Another Address&ship_city=New York
City&ship_state=NY&ship_zip=10001&ship_country_code=US&ship_phone=+354 665
3142&num_items=1&item1_desc=8Gb iPod Nano Green&item1_price=129.00&item1_qty=1
Example Input Adding Discount Field
3142&num_items=1&item1_desc=8Gb iPod Nano
Green&item1_price=129.00&item1_qty=1&sales_discount_amount=19.95
Example Input Adding Sales Tax Field
3142&&num_items=1&item1_desc=8Gb iPod Nano
Green&item1_price=129.00&item1_qty=1&sales_tax_amount=10.00
Version 1.3
For public release
Page 21 of 38
Most Frequent Account Setting-Related Errors
The order page (pageid) specified is currently blocked from live orders. This is
usual during testing, prior to go live approval from the Risk Department.
TIP: Use the Visa test card and, an enabled Name on Card Code with your IP whitelisted.
The merchant account (mer_id) is currently set as inactive. This is usually
because you have had no transactions for 90 days and/or have not logged in
to the Merchant Menu for 90 days. Contact DalPay Support.
Both Common when testing. A transaction was posted from localhost or
other local device with no referer in the HTTP header being sent.
If testing contact DalPay Support to temporarily disable referer checking for this order page.
TIP: Do not include DalPay Checkout transaction post links directly in e-mail as they will fail
the referer check. Contact DalPay Support regarding invoicing solutions.
Common when testing. The webpage that the transaction post request is
coming from is not the same as set in the ‘Order page location’ for this order
page. If testing contact DalPay Support to request the referer check be temporarily disabled,
or permanently changed from ‘strict’ to ‘domain only’.
Version 1.3
For public release
Page 22 of 38
Common Error Messages
Error Message:
Explanation:
This merchant account has been
deactivated
Account is set as inactive. Contact DalPay
Support.
Check format of input fields, and form
submission method (i.e. must be POST not GET
or PUT).
Please use POST method only,
Missing POST data,
Too much POST data,
Error reading POST data
Internal Server Error
The selected paytype is not activated
for this merchant account, please
choose another paytype
Sorry, we cannot accept new orders
for this merchant account at the
moment
moment. Additionally, test code
FhXgiByJ is not enabled!
moment. Additionally, your IP
194.144.200.200 is not in the
AllowedIP list to use Name on Card
test code FhXgiByJ
moment. Additionally, your IP
194.144.200.200 is not in the
AllowedIP list to use Name on Card
test code FhXgiByJ AND is it is not
enabled
Sorry, we cannot accept this card
number
Sorry, we cannot accept orders from
IP number 194.144.200.200
Sorry, we cannot accept email address
name@domain.tld
Version 1.3
You sent malformed or incorrectly delimited
input fields.
pay_type sent in is not enabled for this account
or order page.
The order page (page_id) is blocked from
accepting new orders. Usual during testing.
The Name on Card Code is not enabled.
Re-enable this Name on Card Code, for 360
minutes at a time, from ‘Run Test Order’.
The IP you used to place the Test Order is not
in the AllowedIPs list for the Name on Card
Code used (although the code is enabled).
Add IP to the AllowedIPs list for that Name on
Card Code from ‘Run Test Order’ at the
Merchant Menu.)
The Name on Card Code is not enabled. The IP
you used to place the Test Order is not in the
AllowedIPs list for the Name on Card Code
used.
Enable the Name on Card Code, and ensure IP
is added to the AllowedIPs list for that Name
on Card Code.
Payment card number entered is blocked due
to chargeback, order attempt from commercial
or open proxy, or for other fraud-loss reason.
Contact DalPay Support.
IP of the computer used to place the order is
blocked due to chargeback, order attempt from
commercial or open proxy, or for other fraudloss reason. Contact DalPay Support.
cust_email blocked due to chargeback, order
attempt from commercial or open proxy, or for
other fraud-loss reason. Contact DalPay
Support.
For public release
Page 23 of 38
This merchant does not supply
products to Iceland, from where your
order seems to originate (determined
from your IP address 194.144.200.200)
Order attempt was identified as coming from a
country or state currently blocked for this
order page.
Your order could not be processed
because our fraud detection system
flagged your order as high risk.
See ‘blocking’ from the Merchant Menu to
unblock the country temporarily.
The transaction fraud score after fraud
scrubbing exceeded the currently set fraud
score threshold or attribute for this order page.
Order quantity and amount must be
greater than zero
Choose ‘Accept future transactions for this
card’ from the Transaction details screen’ to
whitelist this card number, then try again.
Check for missing item1_qty, item1_price and
item1_desc fields.
Due to security issues we can only
accept single transactions to a
minimum of 5.00 USD
99:Test order decline info
333:Test order test error text
Version 1.3
Check that the discount sent in via
sales_discount_amount or sales_discount_factor is
not more than the total value of all item fields.
You are sending in a total amount lower than
The Minimum Order Amount set for this order
page. Contact DalPay Support to raise or lower
this. (Will not generally be lowered below USD
1, GBP 1, EUR 1, or equivalent.)
You have the Name on Card Code set to
ResultCode ‘declined’ (see p. 14).
You have the Name on Card Code set to
ResultCode ‘error’ (see p. 14).
For public release
Page 24 of 38
Internationalization
DalPay supports full internationalization to allow you to sell internationally,
across borders, to expand your market reach.
Despite English being ‘the global language’ approximately seventy percent of
the world’s population can't use an English-only website, so DalPay’s language
localisation helps you to sell to an international audience.
International Language Support
Your can override the default order page setting for the checkout language
(which could be any of the supported languages) by sending in the langcode
name-value pair. The value should be the ISO 639-1 two or four letter code for
that language.
Example langcode values:
en
es
fr
de
pt
ar
ja
ko
US English
Standard
Spanish
French
German
Portuguese
Standard
Arabic
Japanese
Korean
(Please note that the ISO 639-1 two letter code for language sometimes
differs from the ISO 3166-1 two letter code for the country in which that
language is spoken.)
Version 1.3
For public release
Page 25 of 38
International Currency Support
If you are using a multicurrency shopping cart or otherwise want to allow
customers to checkout in their own currency you can override the default
order page setting for the checkout currency by sending in the valuta_code
name-value pair. The value should be the ISO 4217 three letter code for that
currency.
Example valuta_code values:
USD United States dollars
GBP
Great British pounds
EUR
European Union euros
JPY
Japanese Yen
CAD
Canadian dollars
AUD Australian dollars
ZAR
South African rands
ISK
Icelandic crowns
Please note that, 'Allow Post Valuta Override'
must be set to ‘yes’ for each order page. Contact DalPay Support if ‘no’.
>
Version 1.3
>
For public release
Page 26 of 38
Instant Silent Post
DalPay’s Instant Silent Post is for receiving a POST of order related fields to a
listening script on your server, as soon as the order was successfully charged.
Instant Silent Post is equivalent to Authorize.net's Silent Post feature with
Relay Response in their Server Integration Method (SIM) or Simple Checkout,
PayPal's Payment Data Transfer (PDT), 2Checkout's Direct Return feature, or
CCBill's Background Post Postback. It is for accepted orders only.
TIP: If you require notification of all transaction status changes to a listening script on
your server, including declines, chargebacks, accepted/declined rebillings, and other
exceptions, please refer to the Merchant Server Notifications Integration Guide.
Order Page Silent Post Settings
>
When ‘Silent Post Callback’ is enabled, with a silent post password set, the
DalPay server POSTs order related fields set in ‘Silent Post Fields’ in realtime
to a listening script on your server. It only posts for successfully charged,
accepted orders (not declined transactions).
Your script validates the response, then initiates its actions (for example
starting a process for service delivery) and returns a dynamic custom receipt
message for display to the customer on the DalPay Confirmation Receipt Page.
Version 1.3
For public release
Page 27 of 38
Silent Post Fields
You may include any combination of the following fields in ‘Silent Post Fields’.
By default the Silent Post fields are set to:
user1,user2,total_amount,order_num
The order of the fields does not matter, provided correctly separated by a
comma, as they are HTTP POSTed to your listening script as name-value pairs.
Silent Post Field
Size
MinMax
Example Value
Notes
SilentPostPassword
8128
ThUj73dw
order_num
14
999994.5282761
As set in ‘Silent Post Password’
per order page, from the
DalPay Merchant Menu.
Always posted.
DalPay order number.
order_datetime
19
2010-01-19 14:41:37
(YYYY-MM-DD HH:MM:SS)
pageid
1-3
1
orderpage_url
2083
pay_type
1128
masked_card_num
1219
http://www.icelandicshop.com/history.php
Visa
Visa Electron
Mastercard
Maestro
American Express
Discover
Carte Blanche
JCB
China Unionpay
OR
Bank Epayment
422222XXX2222,
550000XXXXXX0004,
340000XXXXX0009,
601100XXXXXX0004,
300000XXXX0004,
308800XXXXXX0008,
490300XXXX0004
622888XXXXXX8888
last4
4
2222, 0004, 0009, 0004,
0004, 0008, 0004
8888
card_name
40
MR JON JONSSON
Transaction
Fields
Version 1.3
Date and time order was
accepted by DalPay in
timezone set for the merchant
account. (Default is US Central
Standard Time.)
The order page where this
order originates.
The URL of the order page.
where this order originates.
The payment type used.
First six and last four digits of
payment card number used.
Length 13 or 16 for Visa, 16
for MasterCard, 15 for AMEX,
16 for Discover, 14-16 for
Diners/Carte Blanche, 16 for
JCB, 12-19 for Maestro (UK
and International), 16 for
China UnionPay.
Last four digits of payment
card number used.
Cardholder name on the card.
For public release
Page 28 of 38
remote_addr
IP of device used to place
order.
Hostname of device used to
place order.
Value of order in currency of
valuta_code posted.
ISO 4217 code posted or
valuta setting for order page.
The currency exchange rate
used to convert from the
posted valuta_code into the
currency set in the order page.
(fxdaily rate from oanda.com
is used.)
Amount of discount in
currency of valuta_code
posted.
Discount as a percentage of
total_amount.
Amount of tax added in
currency of valuta_code
posted.
Tax as a percentage of
total_amount.
ISO 639-1 code of language
used for checkout.
194.144.200.200
total_amount
1115
1255
1-10
valuta_code
3
USD, GBP, EUR, ISK
xrate
9
1.0000000 (no conversion)
1.5446000 (from GBP to
USD),
1.2886000 (from EUR to USD)
sales_discount_amou
nt
1-10
19.95
sales_discount_perc
1-10
15.47
sales_tax_amount
1-10
10.00
sales_tax_perc
1-10
7.75
langcode
2-5
en, es, is,
en-GB, en-US, en-CA
cust_name
1-40
Ms Secretary
cust_company
1-40
Acme Inc
Customer’s name (may be
different from card_name).
Customer’s company name.
cust_email
5-80
name@domain.tld
Customer’s email.
cust_phone
7-20
+3544122600
cust_fax
7-20
4661935
Numeric with or without a +
prefix.
prefix.
cust_address1
1-60
100 Jump Street
cust_address2
1-30
Second Floor
cust_city
1-30
Some City
Billing city.
cust_state
1-20
Billing state, county or
province.
cust_zip
1-10
cust_country_code
2
Biscay
OR
N/A if no state
33101,
SE1 9LT OR
US, GB, IS
avs_response
2
B, R, G, U, S, N, ...
remote_host
194-144-200-200.xdsl.com
139.00
Customer
Contact Details
Customer Billing
Address
Version 1.3
Billing ZIP or Postcode. Refer
to the International Postal
Codes Integration Guide.
Billing country ISO 3166-1
alpha-2.
Refer to the Address
Verification Integration Guide.
For public release
Page 29 of 38
Customer
Shipping
Address
ship_address1
1-60
100 Jump Street
ship_address2
1-30
Second Floor
ship_city
1-30
Some City
Shipping city.
ship_state
1-20
Shipping state, county or
province.
ship_zip
1-10
Biscay
OR
N/A if no state
33101,
SE1 9LT OR
ship_country_code
2
US, GB, IS
ship_phone
7-20
+3544122600
Shipping ZIP or Postcode.
Refer to the International
Postal Codes Integration
Guide.
Shipping country ISO 3166-1
alpha-2.
prefix.
All fields are optional except SilentPostPassword which is always included.
Example Silent Post for default fields:
SilentPostPassword = ThUj73dw
total_amount = 139.00
order_num = 999994.5282761
user1 = This is an order note field. Don’t deliver
user2 = {3a768eea-cbda-4926-a82d-831cb89092aa}
before 10am. Thank you.
(The DalPay Silent Post server always sends the SilentPostPassword namevalue pair based on the setting in the order page. If any silent post field is set
in ‘Silent Post Fields’, but has no value at silent post time, it will not be
posted.)
After receiving the Silent Post fields your listening script must then return also in realtime - a dynamic custom receipt message on standard output.
The DalPay Silent Post server will wait for up to 20 seconds for the dynamic
custom receipt message response from your script.
The dynamic custom receipt message returned can be up to 2048 characters
long, and include basic HTML tags for formatting the message within the
DalPay Confirmation Receipt Page.
Version 1.3
For public release
Page 30 of 38
Dynamic Custom Receipt Message
The response from your listening script is displayed at the bottom of the
confirmation receipt page presented to the customer.
If your script does not respond correctly, or if there is a timeout,
the customer will see the following:
i.e. “Your order has been accepted, however we were not able to
redirect you back to the merchant. The merchant has been informed
about this problem. You can reach the merchant at [OrderEmail].”
Version 1.3
For public release
Page 31 of 38
You can view details of silent posts in the transaction details screen, and
manually retry a failed silent post from ‘Silent Post Errors’ in the Merchant
Menu.
Response From Your Listening Script
If the validation you performed is successful (i.e. in the example it would be
based on the user2 field GUID or hash sent in, and SilentPostPassword)
including basic sanity checking (such as the format of order_num and amount
in total_amount), then your listening script should return similiar to this:
<a
href="http://www.some_website.com/orderaccepted.php">CLICK
HERE to return to your account</a>
if validation fails, then return at a minimum this type of response:
<a href="http://www.
some_website.com/orderfailed.php">Order was not completed. PLEASE
CONTACT SITE SUPPORT. Click here to return to your account</a>
Note the specific  comment tags which must be used. The returned
links must be on the same website as set in the order page location settings
for this order page.
(If you want the customer to be returned automatically to a particular page
you may in addition to the static link include an auto refresh tag:
<meta HTTP-EQUIV="REFRESH" CONTENT="10;URL=
http://www.some_website.com/orderaccepted.php">
However, it must go to the same page as included in the link, and be delayed
from activating for a minimum of 10 seconds as in the example given.)
Inclusion of such a delayed auto redirect must be signed off by
DalPay Support. Merchants implementing an automatic redirect
without specific sign-off by DalPay may have their order page
suspended without notice. Check with us before putting it live.
Version 1.3
For public release
Page 32 of 38
Responding With a Login or Custom Download Link
Generated On-The-Fly
As you generate the output for the dynamic custom receipt message on your
server, and the Silent Post is always for a successfully charged transaction,
you can include a site login or customer specific download link, such as:
 Site Username: your_site_generated Site
Password: xyz12abc_your_site_generated <a
HERE to return to Test Page website</a>
The output of the dynamic custom receipt message is not included in the
confirmation receipt emails, only on the confirmation receipt page, so make
sure to send logins or download links via email or SMS, or other method your
customers prefer if you send them in the dynamic custom receipt message.
The separate fixed confirmation page/email message in the order page
settings should include any https:// links to your logo and link to permanent
items such as a link to your terms and conditions. It IS included in the
confirmation receipt email sent to the customer.
Version 1.3
For public release
Page 33 of 38
Affiliate Marketing Features
Confirmation Page Affiliate Code Settings
>
The confirmation page affiliate code setting in each order page is for your
affiliate tracking code(s). As the confirmation receipt page is only displayed
after the customer has successfully paid, you can safely include your
JavaScript and static script tags here to track conversions. (They are included
invisibly at the top of the page as shown below.)
You must use only the SSL (https:) versions of any affiliate tracking codes.
Version 1.3
For public release
Page 34 of 38
Website Compliance
Website Content
Your website must include at a minimum a delivery policy, refund policy, and site privacy
policy.
There must be conspicuous links to these and your terms and conditions on the site.
The DalPay Risk Department must sign off your website content before allowing you to go
live.
You must be in compliance with DalPay and card association rules for website content.
DalPay has specific acceptance and compliance policies for different account and
business types.
Please refer to the compliance guidelines here:
https://www.dalpay.com/en/compliance/
Minimum Test Plan
You must have completed the minimum test plan for your account and business type to
the satisfaction of DalPay Support before going live.
Test Plans vary between sites, but an example of a minimum test plan would be:
1. The correct customer information fields are being passed to DalPay Checkout resulting
in single page checkout (Step 3 asking for payment card details).
2. In the case of a low-cost service with pre-authorized recurring billing, the order is routed
to pageid = '01'; in the case of a high value one-off purchase, the order is routed to pageid
= '02'.
3. The Instant Silent Post dynamic custom receipt message is returned to us, based on
the following cases:
3.1 DalPay accepted order fields (order_num, total_amount) plus user1 or user2 sanity
checking passes your end returning:
Version 1.3
For public release
Page 35 of 38
<a
HERE to return to your account</a>
In this case the service delivery started by the DalPay Silent Post in updating the purchase
at your site’s end is clearly visible as being completed when we click through using that
link on the DalPay confirmation receipt page.
3.2 The sanity check of the order_num and total_amount plus user1 or user2 field sent in
to us with the order, as silent posted back to you, fails validation your end:
<a href="http://www.
some_website.com/orderfailed.php">Order was not completed. PLEASE
CONTACT SITE SUPPORT. Click here to return to your account</a>
In this case when we click the link to view our account, it is clear that the purchase was
NOT completed and that your listening script did not start service delivery.
Internal Visa test orders (see p. 14) must have been run demonstrating both of these
cases, as viewable from the Silent Post response for the test transactions. from ‘search
transactions’.
(Of course the return URL syntax and specific response and destination links will be
different for your implementation, but the test orders must show the clear difference
between a successfully validated silent post starting service delivery, and a silent post
failing validation your end and informing the customer even though their card was
successfully charged by DalPay.)
Please contact DalPay Support for further guidance.
Version 1.3
For public release
Page 36 of 38
Payment Card Industry Data Security Standard Compliance
DalPay operates its own PCI DSS Level 1 certified platform (the highest level
of payment service provider compliance) as gateway and front-end processor.
What Must Never Be Stored
Please note that under the Payment Card Industry Data Security Standard
(PCI DSS), Cardholder Data must be stored encrypted and Sensitive
Authentication Data must NOT be stored.
At the time of writing, Cardholder Data in the context of Card-Not-Present
transactions is defined as Primary Account Number (PAN) AKA card number,
Cardholder Name, and Expiration Date.
Sensitive Authorization Data in the context of Card-Not-Present transactions is
defined as the CVV2/CVC2/CID/CAV2 (the three digit or four digit Card
Security Code):
https://www.dalpay.com/en/support/card_security_code.html
You must never store the CVV2/CVC2/CID/CAV2, and it is prohibited to store
the full Primary Account Number yourself if you are posting transactions to the
DalPay Gateway via either DalPay Checkout, as DalPay performs PCI DSS
compliant storage of this sensitive information.
Storage of a truncated card number (i.e. the first 6 and last 4 digits of the
card number only) is permitted if it is based on the DalPay Checkout Instant
Silent Post, or DalPay Merchant Server Notification response fields.
If a merchant collects customer information via mail order or telephone
order and is authorized to use the DalPay Virtual Terminal feature via the
DalPay Merchant Menu to self-key the transaction then the merchant must at a
minimum have returned to the DalPay Risk Department a Payment Card
Industry Data Security Standard Self-Assessment Questionnaire A or C-VT
and Attestation of Compliance, including attestation that they do not store
the CVV2/CVC2/CID/CAV2 after authorization by the issuing bank or stand-in
processor, on any media, including on any paper form.
Version 1.3
For public release
Page 37 of 38
DalPay Checkout and Compliance
Using DalPay Checkout may simplify compliance with the Payment Card
Industry Data Security Standard (PCI-DSS), and Payment Application Data
Security Standard (PA-DSS) if a third-party shopping cart is used*.
This however is only true if you DO NOT collect, transmit or store sensitive
cardholder or bank account information.
Your shopping cart must be configured NOT TO collect or store any cardholder
data (i.e. name on card, card number, expiry date, card security code, 3-D
Secure password, or PIN) or bank account information, instead being
configured to redirect to DalPay Checkout when it is time for customers to
enter their payment card or bank account information.
Your operating jurisdiction may require specific protection of other cardholder
or transaction data as well, or proper disclosure of your company's practices if
consumer-related personal data is being collected during the course of
business.
(In Iceland for example DalPay is subject to, and compliant with the
requirements of Act no. 77/2000 on The Protection of Privacy as regards the
Processing of Personal Data.)
*Please consult a Qualified Security Assessor regarding PCI DSS and PA-DSS
compliance.
FIGURE 2: Extract from the PCI DSS Version 2.0
https://www.pcisecuritystandards.org/
Version 1.3
For public release
Page 38 of 38

DalPay Checkout Integration Guide

Transcription

Similar documents

Xstamper Instructions Email - Pay

www.milfordhavenschool.co.uk

2011 catalog - Emmons Guitar Company by Lashley, Inc.

Industrial Brochure

SyncroFlo Online Printing System Instructions

CreditDebit Card Dispute Form

RE/MAX vs. THE INDUSTRY

PCI Compliance Instructions

Atlantis Energy Systems Inc.

PCI Compliance Instructions