dalpay checkout integration guide 13 · pdf filetransaction post api input parameters 17 ......

Version 1.3 Last revision: 01/07/2011 of 38 For public release

Copyright © 2011 Snorrason Holdings ehf

DalPay Internet Billing

Checkout Integration Guide Online Payments



REVISION HISTORY 4 INTRODUCTION 5

HOW DOES DALPAY CHECKOUT WORK? 5 FIGURE 1: Transaction Flow 5

WHAT THE CUSTOMER SEES 6 Payment Card Details Screen Only (Single Page Checkout) 6 Step 1: Payment Type and Customer Country 7 Step 2: Customer Information (Contact Details, Billing Address) 8 Step 2a: Customer Information (Different Shipping Address) 9 Step 3: Payment Card Details 10 Step 4c: Confirmation Receipt Page (Simple Continue Button Mode) 11 Step 4d: Confirmation Receipt Page (Instant Silent Post Mode) 12

GETTING STARTED IMPLEMENTATION NOTES 13 ORDER PAGES INITIALLY BLOCKED 13 ENABLING THE INTERNAL TEST CARD 14 TRANSACTION TYPES 15 TRANSACTION STATES 16

TRANSACTION POST API 17 Transaction Post API input parameters 17 Example Input Minimum Mandatory Fields 21 Example Input Adding Shipping Fields 21 Example Input Adding Discount Field 21 Example Input Adding Sales Tax Field 21 Most Frequent Account Setting-Related Errors 22 Common Error Messages 23

INTERNATIONALIZATION 25 INTERNATIONAL LANGUAGE SUPPORT 25 INTERNATIONAL CURRENCY SUPPORT 26

INSTANT SILENT POST 27 Order Page Silent Post Settings 27 Silent Post Fields 28 Dynamic Custom Receipt Message 31 Response From Your Listening Script 32 Responding With a Login or Custom Download Link Generated On-The-Fly 33

AFFILIATE MARKETING FEATURES 34 CONFIRMATION PAGE AFFILIATE CODE SETTINGS 34

WEBSITE COMPLIANCE 35 Website Content 35 Minimum Test Plan 35

PAYMENT CARD INDUSTRY DATA SECURITY STANDARD COMPLIANCE 37 What Must Never Be Stored 37 DalPay Checkout and Compliance 38 FIGURE 2: Extract from the PCI DSS Version 2.0 38



Revision History Version Date

Released Change Notice Pages

Affected Remarks

1.0 July 1, 2007 First release All PCI DSS 1.1 applies

1.1 July 1, 2009 Introduction, pay_type update, Screen shot changes

p. 5, 6-12, 15

PCI DSS 1.2 applies

1.2 Jan 1, 2010 Screen shot changes 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

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



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.



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



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: https://www.dalpay.com/en/dalpayapi/DalPay_ISO_3166-1_country_list_en.csv



Step 2: Customer Information (Contact Details, Billing Address) TIP: alpha-2 lists for cust_state; Canada, and the United States: https://www.dalpay.com/en/dalpayapi/DalPay_CA_abbr_provinces_en.csv https://www.dalpay.com/en/dalpayapi/DalPay_US_abbr_states_en.csv



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): https://www.dalpay.com/en/dalpayapi/DalPay_CA_abbr_provinces_en.csv https://www.dalpay.com/en/dalpayapi/DalPay_US_abbr_states_en.csv



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.



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.



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.



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:



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



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.



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.



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

Min-Max

Example Value Notes

Transaction Setup Fields

mer_id TEXT 6-6 999994 6 digit merchant number. pageid TEXT 1-3 1 The order page sub-account

within the merchant account specified by mer_id. Each selling URL or currency should have its own order page.

next_phase* TEXT 1-20 paydata Initiate single page checkout if all required fields are present.

pay_type TEXT 1-128

Visa Visa Electron Mastercard Maestro American Express Discover Carte Blanche JCB China Unionpay OR Bank Epayment

Payment type for correct routing. Some merchants will have a subset of the full set of card types enabled. 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+

valuta_code* TEXT 3 USD, GBP, EUR, ISK ISO 4217 code for checkout currency. (Will be converted using a rate favourable to the cardholder if different from order page valuta setting.)

langcode* TEXT 2-5 en, es, is, en-GB, en-US, en-CA

ISO 639-1 code for checkout language.



Customer Contact Details

cust_name TEXT 1-40 Ms Secretary Customer’s name (can be different from cardholder name).

cust_company* TEXT 1-40 Acme Inc Customer’s company name. cust_email TEXT 5-80 [email protected] Must be in valid email address

format. cust_phone TEXT 7-20 +3544122600 Numeric with or without +

prefix. cust_fax* TEXT 7-20 4661935 Numeric with or without +

prefix. Customer Billing Address

cust_address1 TEXT 1-60 100 Jump Street Billing address line 1. cust_address2* TEXT 1-30 Second Floor Billing address line 2. cust_city TEXT 1-30 Some City Billing city.

cust_state TEXT 1-20 FL, AE, BC, Lincolnshire, Biscay OR N/A if no state

Billing state, county or province. If cust_country_code = ‘CA’ or ‘US’ see end note++

cust_zip TEXT 1-10 33101, SE1 9LT OR 99999 if no postal codes

Billing ZIP or Postcode. Refer to the International Postal Codes Integration Guide.

cust_country_code TEXT 2-3 US, GB, IS USA, GBR, ISL

Billing country ISO 3166-1 alpha-2 or alpha-3. See end note+++

Customer Shipping Address

ship_address1** TEXT 1-60 100 Jump Street Shipping address line 1.

ship_address2** TEXT 1-30 Second Floor Shipping address line 2. ship_city** TEXT 1-30 Some City Shipping city. ship_state** TEXT 1-20 FL, AE, BC, Lincolnshire,

Biscay OR N/A if no state

Shipping state, county or province. If ship_country_code = ‘CA’ or ‘US’ see end note++

ship_zip** TEXT 1-10 33101, SE1 9LT OR 99999 if no postal codes

Shipping ZIP or Postcode. Refer to the International Postal Codes Integration Guide.

ship_country_code** TEXT 2-3 US, GB, IS USA, GBR, ISL

Shipping country ISO 3166-1 alpha-2 or alpha-3. See end note+++

ship_phone** TEXT 7-20 +3544122600 Numeric with or without + prefix.



Order Information Details

num_items TEXT 1-20 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.

item1_desc TEXT 1-256

Some Widgets, Service (1 year), Online Widget delivered in 1-2 weeks

Line item description. If a service specify time that service purchase covers. If delivery time varies specify timeframe in the line item description.

item1_price TEXT 1-10 129.00 Value in the currency set as valuta_code for this pageID.

item1_qty TEXT 1-20 1 The multiplier for item1_price.

item2_desc* TEXT 1-128

Some Widgets, Service (1 year), Online Widget delivered in 1-2 weeks

Line item description as above.

item2_price* TEXT 1-10 500.00 Value in the currency set as valuta_code for this pageID.

item2_qty* TEXT 1-20 1 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.

Shipping/ Delivery Fields

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.

item7_desc* item7_price* item7_qty*

TEXT

TEXT TEXT

1-256 1-10 1-20

USPS Priority Mail, FedEx Express Saver, ... 20.07, 40.56 1

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_amount*

TEXT 1-10 19.95 Fixed discount amount (will be subtracted from the total calculated for the item fields). Will be displayed as a % as well.

sales_discount_factor*

TEXT 1-10 0.05 (5%) , 0.25 (25%) Discount multiplier based on the item fields totalled.

sales_discount_exclude*

TEXT 1-20 2,4,5 (exclude items 2, 4 and 5 from the discount calculation)

Exclude items, such as line item for shipping/delivery cost, from the discount.



Taxation Fields sales_tax_amount* TEXT 1-10 10.00 Fixed taxation amount (will be

added to the total calculated for the item fields). Will be displayed as a % as well.

sales_tax_factor* TEXT 1-10 0.10 (10%) , 0.175 (17.5%) Taxation multiplier based on the item fields totalled.

sales_tax_exclude* TEXT 1-20 2,4,5 (exclude items 2, 4 and 5 from the tax calculation)

Exclude items, such as line item for shipping/delivery cost, from taxation.

Rebilling Fields For automatic pre-authorized recurring billing for subscriptions please refer to the DalPay Checkout Recurring Billing Integration Guide.

User Fields

user1* TEXT 1-256

This is an order note field. Don’t deliver before 10am. Thank you.

Fields you set and wish passed through to you such as GUIDS or other data.

User2* TEXT 1-256

{3a768eea-cbda-4926-a82d-831cb89092aa}

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:

https://www.dalpay.com/en/dalpayapi/DalPay_ISO_3166-1_country_list_en.csv (The CSV file is UTF-8 to preserve the correct names of some of the more exotic countries.)



Example Input Minimum Mandatory Fields https://secure.dalpay.is/cgi-bin/order2/processorder1.pl?mer_id=999994&pageid=2&next_phase=paydata&pay_type=Visa&cust_name=Ms Secretary&cust_address1=100 Jump Street&cust_city=Some City&cust_state=FL&cust_zip=33101&cust_country_code=US&[email protected]&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 https://secure.dalpay.is/cgi-bin/order2/processorder1.pl?mer_id=999994&pageid=2&next_phase=paydata&pay_type=Visa&cust_name=Ms Secretary&cust_address1=100 Jump Street&cust_city=Some City&cust_state=FL&cust_zip=33101&cust_country_code=US&[email protected]&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 https://secure.dalpay.is/cgi-bin/order2/processorder1.pl?mer_id=999994&pageid=2&next_phase=paydata&pay_type=Visa&cust_name=Ms Secretary&cust_address1=100 Jump Street&cust_city=Some City&cust_state=FL&cust_zip=33101&cust_country_code=US&[email protected]&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&sales_discount_amount=19.95

Example Input Adding Sales Tax Field https://secure.dalpay.is/cgi-bin/order2/processorder1.pl?mer_id=999994&pageid=2&next_phase=paydata&pay_type=Visa&cust_name=Ms Secretary&cust_address1=100 Jump Street&cust_city=Some City&cust_state=FL&cust_zip=33101&cust_country_code=US&[email protected]&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&sales_tax_amount=10.00



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’.



Common Error Messages Error Message: Explanation:

This merchant account has been deactivated

Account is set as inactive. Contact DalPay Support.

Please use POST method only, Missing POST data, Too much POST data, Error reading POST data

Check format of input fields, and form submission method (i.e. must be POST not GET or PUT).

Internal Server Error You sent malformed or incorrectly delimited input fields.

The selected paytype is not activated for this merchant account, please choose another paytype

pay_type sent in is not enabled for this account or order page.

Sorry, we cannot accept new orders for this merchant account at the moment

The order page (page_id) is blocked from accepting new orders. Usual during testing.

Sorry, we cannot accept new orders for this merchant account at the moment. Additionally, test code FhXgiByJ is not enabled!

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’.

Sorry, we cannot accept new orders for this merchant account at the moment. Additionally, your IP 194.144.200.200 is not in the AllowedIP list to use Name on Card test code FhXgiByJ

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

Sorry, we cannot accept new orders for this merchant account at the 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

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.

Sorry, we cannot accept this card number

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.

Sorry, we cannot accept orders from IP number 194.144.200.200

IP of the computer used to place the order is blocked due to chargeback, order attempt from commercial or open proxy, or for other fraud-loss reason. Contact DalPay Support.

Sorry, we cannot accept email address [email protected]

cust_email blocked due to chargeback, order attempt from commercial or open proxy, or for other fraud-loss reason. Contact DalPay Support.



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. See ‘blocking’ from the Merchant Menu to unblock the country temporarily.

Your order could not be processed because our fraud detection system flagged your order as high risk.

The transaction fraud score after fraud scrubbing exceeded the currently set fraud score threshold or attribute for this order page. Choose ‘Accept future transactions for this card’ from the Transaction details screen’ to whitelist this card number, then try again.

Order quantity and amount must be greater than zero

Check for missing item1_qty, item1_price and item1_desc fields. 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.

Due to security issues we can only accept single transactions to a minimum of 5.00 USD

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

99:Test order decline info You have the Name on Card Code set to ResultCode ‘declined’ (see p. 14).

333:Test order test error text You have the Name on Card Code set to ResultCode ‘error’ (see p. 14).



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 US English

es Standard Spanish

fr French de German pt Portuguese

ar Standard Arabic

ja Japanese ko 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.)



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’.

> >



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.



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

Min-Max

Example Value Notes

Transaction Fields

SilentPostPassword 8-128

ThUj73dw As set in ‘Silent Post Password’ per order page, from the DalPay Merchant Menu. Always posted.

order_num 14 999994.5282761 DalPay order number. order_datetime 19 2010-01-19 14:41:37

(YYYY-MM-DD HH:MM:SS) Date and time order was accepted by DalPay in timezone set for the merchant account. (Default is US Central Standard Time.)

pageid 1-3 1 The order page where this order originates.

orderpage_url 2083 http://www.icelandic-shop.com/history.php

The URL of the order page. where this order originates.

pay_type 1-128

Visa Visa Electron Mastercard Maestro American Express Discover Carte Blanche JCB China Unionpay OR Bank Epayment

The payment type used.

masked_card_num 12-19

422222XXX2222, 550000XXXXXX0004, 340000XXXXX0009, 601100XXXXXX0004, 300000XXXX0004, 308800XXXXXX0008, 490300XXXX0004 622888XXXXXX8888

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.

last4 4 2222, 0004, 0009, 0004, 0004, 0008, 0004 8888

Last four digits of payment card number used.

card_name 40 MR JON JONSSON Cardholder name on the card.



remote_addr 11-15

194.144.200.200 IP of device used to place order.

remote_host 1-255

194-144-200-200.xdsl.com Hostname of device used to place order.

total_amount 1-10 139.00 Value of order in currency of valuta_code posted.

valuta_code 3 USD, GBP, EUR, ISK ISO 4217 code posted or valuta setting for order page.

xrate 9 1.0000000 (no conversion) 1.5446000 (from GBP to USD), 1.2886000 (from EUR to USD)

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

sales_discount_amount

1-10 19.95 Amount of discount in currency of valuta_code posted.

sales_discount_perc 1-10 15.47 Discount as a percentage of total_amount.

sales_tax_amount 1-10 10.00 Amount of tax added in currency of valuta_code posted.

sales_tax_perc 1-10 7.75 Tax as a percentage of total_amount.

langcode 2-5 en, es, is, en-GB, en-US, en-CA

ISO 639-1 code of language used for checkout.

Customer Contact Details

cust_name 1-40 Ms Secretary Customer’s name (may be different from card_name).

cust_company 1-40 Acme Inc Customer’s company name. cust_email 5-80 [email protected] Customer’s email. cust_phone 7-20 +3544122600 Numeric with or without a +

prefix. cust_fax 7-20 4661935 Numeric with or without a +

prefix. Customer Billing Address

cust_address1 1-60 100 Jump Street Billing address line 1. cust_address2 1-30 Second Floor Billing address line 2. cust_city 1-30 Some City Billing city. cust_state 1-20 FL, AE, BC, Lincolnshire,


Billing state, county or province.

cust_zip 1-10 33101, SE1 9LT OR 99999 if no postal codes

Billing ZIP or Postcode. Refer to the International Postal Codes Integration Guide.

cust_country_code 2 US, GB, IS Billing country ISO 3166-1 alpha-2.

avs_response 2 B, R, G, U, S, N, ... Refer to the Address Verification Integration Guide.



Customer Shipping Address

ship_address1 1-60 100 Jump Street Shipping address line 1. ship_address2 1-30 Second Floor Shipping address line 2.

ship_city 1-30 Some City Shipping city. ship_state 1-20 FL, AE, BC, Lincolnshire,


Shipping state, county or province.

ship_zip 1-10 33101, SE1 9LT OR 99999 if no postal codes

Shipping ZIP or Postcode. Refer to the International Postal Codes Integration Guide.

ship_country_code 2 US, GB, IS Shipping country ISO 3166-1 alpha-2.

ship_phone 7-20 +3544122600 Numeric with or without a + 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 before 10am. Thank you. user2 = {3a768eea-cbda-4926-a82d-831cb89092aa}

(The DalPay Silent Post server always sends the SilentPostPassword name-value 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.



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].”

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.

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 href="http://www.some_website.com/orderaccepted.php">CLICK 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.



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.



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:

<a href="http://www.some_website.com/orderaccepted.php">CLICK 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.



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.



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/

dalpay checkout integration guide 13 · pdf filetransaction post api input parameters 17 ......

Documents