Apple Pay integration
- Introduction
- Basic Workflow
- Compatible operations and options
- Server to server integration
- Sandbox test card numbers
Introduction
Apple Pay is a wallet which allows Apple users to pay with an Apple terminal.
The end-user saves a card in the application and then can pay with the device online.
It involves redirecting the cardholder to finalize its transaction.
info
Upon receipt of
EXECCODE = 0002
in the synchronous response, you must redirect the cardholder to the URL pointed by the REDIRECTURL parameter.
After validating the payment, the cardholder is redirected to the REDIRECT_URL
.
The result of the transaction will also be transmitted by HTTP notification. (See the specifics of the notification)
Basic Workflow
- End-user orders on merchant website and chooses
Apple Pay
payment method; - An order will be created in Dalenys;
- The end-user will be redirected to the payment page;
- To validate the payment, the end-user only has to authenticate on his device and a token will be sent to Dalenys;
- Dalenys processes the transaction with
Apple Pay
by sending a request to the bank network and waits for the result; - You receive the result with the response redirection request;
- The transaction result is confirmed by a notification request sent to the merchant’s
NOTIFICATION_URL
, containing the transaction’s parameters (of whichEXECCODE
andTRANSACTIONID
).
Compatible operations and options
- Compatible operations:
Server to server integration
Payment / authorization
Example
Here is an Apple Pay
http POST request example:
$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=payment" \
--data "params[AMOUNT]=1000" \
--data "params[BILLINGFIRSTNAME]=John" \
--data "params[BILLINGLASTNAME]=Doe" \
--data "params[BILLINGTITLE]=mr" \
--data "params[BILLINGADDRESS]=285 Fulton Street" \
--data "params[BILLINGPOSTALCODE]=10007" \
--data "params[BILLINGCITY]=New York" \
--data "params[BILLINGCOUNTRY]=US" \
--data "params[BILLINGMOBILEPHONE]=33666666666" \
--data "params[BILLINGPHONE]=33111111111" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTIP]=10.1.1.1" \
--data "params[CLIENTUSERAGENT]=Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=payment" \
--data "params[ORDERID]=1234" \
--data "params[SHIPTOTITLE]=mr" \
--data "params[SHIPTOFIRSTNAME]=John" \
--data "params[SHIPTOLASTNAME]=Doe" \
--data "params[SHIPTOADDRESS]=55 rue de la liberté" \
--data "params[SHIPTOPOSTALCODE]=10007" \
--data "params[SHIPTOCITY]=New York" \
--data "params[SHIPTOCOUNTRY]=US" \
--data "params[SHIPTOMOBILEPHONE]=33666666666" \
--data "params[SHIPTOPHONE]=33111111111" \
--data "params[VERSION]=3.0" \
Request parameters
-
AMOUNT integer
The transaction amount in the smallest money decimal (e.g. cents for euro).
Example: 1000
-
BILLINGADDRESS string(1-50)
The billing address. Be careful not to integrate any line breaks.
Example: 285 Fulton Street
-
BILLINGCITY string(1-255)
The billing city.
Example: New York
-
BILLINGCOUNTRY string(2)
The country code (ISO_3166-1_alpha-2).
Example: US
-
BILLINGFIRSTNAME string(1-15)
The first name part of the billing address.
Example: John
-
BILLINGLASTNAME string(1-15)
The last name part of the billing address.
Example: Doe
-
BILLINGMOBILEPHONE string(1-32)
Billing mobile phone number in international (E.164) format.
Example: 33666666666
-
BILLINGPHONE string(1-32)
Billing phone number in international (E.164) format.
Example: 33111111111
-
BILLINGPOSTALCODE string(1-9)
The billing postal code.
Example: 10007
-
BILLINGTITLE
mr
,miss
,mrs
The title used for the billing address name.
Example: mr
-
CARDFULLNAME string(1-255)
The holder’s full name (as described on the payment method).
Example: JOHN SNOW
-
CART[X][BRAND] string(1-100)
Article brand.
Example: Micropple
-
CART[X][CATEGORY]
computersandsoftware
,electronics
,appliances
,homeandgarden
,fashion
,healthandbeauty
,jewellery
,sport
,leisureandhobbies
,carsandmotorbikes
,furniture
,kidsandbaby
,videogamesandconsoles
,toysandgames
,pets
,foodanddrink
,giftandflowers
,entertainment
,travel
,auctionsandgroupbuying
,servicesforindividuals
,servicesforprofessionals
Article category.
Example: electronics
-
CART[X][DELIVERYEXPECTEDDATE] date(YYYY-MM-DD)
Delivery Date.
Example: 2017-06-20
-
CART[X][DELIVERYEXPECTEDDELAY] int (1-3)
Number of days for delivery; must be greater than 0.
Example: 2
-
CART[X][DELIVERYLABEL] string(1-100)
Delivery method name or description.
Example: Micropple store
-
CART[X][DELIVERYSPEED]
standard
,express
Speed of the delivery method. (Specify EXPRESS if under 48h).
Example: express
-
CART[X][DELIVERYTYPE]
storepickup
,networkpickup
,travelpickup
,carrier
,edelivery
,other
Delivery method:
storepickup
: collection of the goods in the merchant store
networkpickup
: collection in a third party point (like ups, alveol, etc.)
travelpickup
: collection in an airport, train station or travel agency
carrier
: carrier such as La Poste, Colissimo, UPS, DHL…or any private carrier
edelivery
: electronic ticket issuance, download, etc.Example: storepickup
-
CART[X][DISCOUNT] float
Applied discount in percentage. The decimal separator is the dot symbol.
Example: 10.5
-
CART[X][MERCHANTITEMID] string
Item ID in the merchant system.
Example: REF-123456
-
CART[X][NAME] string
Item name.
Example: Laser printer
-
CART[X][PRICE] int
Unit price in cents, including potential taxes and discounts.
Example: 20000
-
CART[X][QUANTITY] integer
Quantity of this item.
Example: 3
-
CART[X][SUBMERCHANTEXTERNALID] string
Submerchant account identifier in the marketplace. This field allow a special value “OPERATOR” when the item is sold by the marketplace itself (and not a sub-merchant).
Example: shop1.com
-
CART[X][TAX] float
Applied taxes in percentage. The decimal separator is the dot symbol.
Example: 19.5
-
CART[X][TOTALAMOUNT] integer
Total amount based on PRICE and QUANTITY.
Example: 60000
-
CLIENTADDRESS string(1-510)
The user’s address.
Example: 285 Fulton Street.
-
CLIENTDOB date(YYYY-MM-DD)
The user’s date of birth.
Example: 1982-06-20
-
CLIENTEMAIL email(5-255)
The user’s email.
Example: john.snow@example.com
-
CLIENTIDENT string(1-255)
Unique identifier of the user in your application (e.g. a login or a primary key).
Example: john.snow
-
CLIENTIP ipv4
The user’s public IP address.
Example: 10.1.1.1
-
CLIENTUSERAGENT string(1-255)
The HTTP user agent.
Example: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0
-
DESCRIPTION string(1-510)
A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.
Example: Knows nothing
-
EXTRADATA string(1-255)
Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).
Example: referrer=myshop.com;order=premium
-
HASH string(64)
The transaction’s hash as described in the dedicated section.
Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4
-
IDENTIFIER string(1-32)
Your processing account technical identifier.
Example: YOUR_IDENTIFIER
-
METADATA string(1-255)
Additional transactional data. Contact your account manager for more informations.
Example: @METADATA-MYWEBSITE
-
OPERATIONTYPE
payment
,authorization
The action you want to process.
Example: payment
-
ORDERID string(1-40)
Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)
Example: 1234
-
SHIPTOADDRESS string(1-50)
The shipping address.
Example: 55 rue de la liberté
-
SHIPTOCITY string(1-255)
The shipping city.
Example: New York
-
SHIPTOCOUNTRY string(2)
The country code (ISO_3166-1_alpha-2 format)
Example: US
-
SHIPTOFIRSTNAME string(1-15)
Holder’s first name in the shipping address.
Example: John
-
SHIPTOLASTNAME string(1-30)
Holder’s last name in the shipping address.
Example: Doe
-
SHIPTOMOBILEPHONE string(1-32)
Shipping mobile phone number in international (E.164) format.
Example: 33666666666
-
SHIPTOPHONE string(1-32)
Shipping phone number in international (E.164) format.
Example: 33111111111
-
SHIPTOPOSTALCODE string(1-9)
The shipping postal code.
Example: 10007
-
SHIPTOTITLE
mr
,miss
,mrs
Holder’s title in the shipping address.
Example: mr
-
VERSION
3.0
The API protocol version.
Example: 3.0
Request result
Here is the request result from the platform:
-
DESCRIPTOR string
The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.
Example: myshop.com
-
EXECCODE string(4)
The operation result code. (See the complete list of execution code)
Example: 0000
-
MESSAGE string(no length limit)
The operation result description linked to
EXECCODE
.Example: The transaction has been accepted
-
OPERATIONTYPE
payment
,authorization
The action you want to process.
Example: payment
-
REDIRECTURL string(no length limit)
The url to redirect the user to continue the processing.
Example: http://some_url?p1=v1
-
TRANSACTIONID string(1-32)
Unique Dalenys transaction ID. Make sure to store this ID in your database.
Example: A1123456
Redirection
You will retrieve the following GET
parameters on your REDIRECT_URL
:
-
AMOUNT integer
The transaction amount in the smallest money decimal (e.g. cents for euro).
Example: 1000
-
CLIENTEMAIL email(5-255)
The user’s email.
Example: john.snow@example.com
-
CLIENTIDENT string(1-255)
Unique identifier of the user in your application (e.g. a login or a primary key).
Example: john.snow
-
CURRENCY string(3)
Currency code (ISO 4217 format).
Example: EUR
-
DESCRIPTOR string
The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.
Example: myshop.com
-
EXECCODE string(4)
The operation result code. (See the complete list of execution code)
Example: 0000
-
EXTRADATA string(1-255)
Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).
Example: referrer=myshop.com;order=premium
-
HASH string(64)
The transaction’s hash as described in the dedicated section.
Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4
-
IDENTIFIER string(1-32)
Your processing account technical identifier.
Example: YOUR_IDENTIFIER
-
LANGUAGE
fr
,en
,de
,es
,it
,nl
,zh
,ru
,pt
,sk
Configure the hosted form display language.
Example: en
-
MESSAGE string(no length limit)
The operation result description linked to
EXECCODE
.Example: The transaction has been accepted
-
OPERATIONTYPE
payment
,authorization
The action you want to process.
Example: payment
-
ORDERID string(1-40)
Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)
Example: 1234
-
TRANSACTIONID string(1-32)
Unique Dalenys transaction ID. Make sure to store this ID in your database.
Example: A1123456
-
VERSION
3.0
The API protocol version.
Example: 3.0
security
You have to check the received
HASH
against the one you generate, to confirm the request’s origin and integrity before redirecting the user. See this section for more information. Other parameters relating to the original request asAMOUNT
andORDERID
must be verified.
Notification result parameters
Here is the request result from the platform:
-
AMOUNT integer
The transaction amount in the smallest money decimal (e.g. cents for euro).
Example: 1000
-
CLIENTEMAIL email(5-255)
The user’s email.
Example: john.snow@example.com
-
CLIENTIDENT string(1-255)
Unique identifier of the user in your application (e.g. a login or a primary key).
Example: john.snow
-
CURRENCY string(3)
Currency code (ISO 4217 format).
Example: EUR
-
DESCRIPTOR string
The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.
Example: myshop.com
-
EXECCODE string(4)
The operation result code. (See the complete list of execution code)
Example: 0000
-
EXTERNALENTITYID int (1-10)
Merchant account’s reference
Example:
-
EXTERNALREFERENCE int (9)
Transaction’s reference (string left padded with 0 of 9 digits)
Example: 19
-
EXTRADATA string(1-255)
Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).
Example: referrer=myshop.com;order=premium
-
HASH string(64)
The transaction’s hash as described in the dedicated section.
Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4
-
IDENTIFIER string(1-32)
Your processing account technical identifier.
Example: YOUR_IDENTIFIER
-
LANGUAGE
fr
,en
,de
,es
,it
,nl
,zh
,ru
,pt
,sk
Configure the hosted form display language.
Example: en
-
MESSAGE string(no length limit)
The operation result description linked to
EXECCODE
.Example: The transaction has been accepted
-
OPERATIONTYPE payment
The action you want to process.
Example: payment
-
ORDERID string(1-40)
Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)
Example: 1234
-
TRANSACTIONID string(1-32)
Unique Dalenys transaction ID. Make sure to store this ID in your database.
Example: A1123456
-
VERSION
3.0
The API protocol version.
Example: 3.0
Capture
Authorizations have to be captured by a server to server request.
info
You can only
capture
a succeededauthorization
transaction and anauthorization
can only be captured once.
warning
A
capture
must be triggered within 7 days of an authorization, otherwise capture success is no longer guaranteed.
tips
The capture
AMOUNT
may be lower but cannot exceed the initial authorization’sAMOUNT
.
Example
Here is a server to server request example:
$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=capture" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=capture" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
Parameters
-
AMOUNT integer
When not specified, 100% of the
authorization
amount is captured. Could not be higher than theauthorization
amount.Example: 1000
-
DESCRIPTION string(1-510)
A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.
Example: Knows nothing
-
EXTRADATA string(1-255)
Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).
Example: referrer=myshop.com;order=premium
-
HASH string(64)
The transaction’s hash as described in the dedicated section.
Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4
-
IDENTIFIER string(1-32)
Your processing account technical identifier.
Example: YOUR_IDENTIFIER
-
OPERATIONTYPE
capture
The action you want to process.
Example: payment
-
ORDERID string(1-40)
Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)
Example: 1234
-
TRANSACTIONID string(1-32)
The
authorization
’sTRANSACTIONID
you want tocapture
.Example: A1123456
-
VERSION
3.0
The API protocol version.
Example: 3.0
Request result
Here is the request result from the platform:
-
DESCRIPTOR string
The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.
Example: myshop.com
-
EXECCODE string(4)
The operation result code. (See the complete list of execution code)
Example: 0000
-
MESSAGE string(no length limit)
The operation result description linked to
EXECCODE
.Example: The transaction has been accepted
-
OPERATIONTYPE
capture
The action you want to process.
Example: payment
-
TRANSACTIONID string(1-32)
Unique Dalenys transaction ID. Make sure to store this ID in your database.
Example: A1123456
Notification result parameters
Here is the request result from the platform:
-
AMOUNT integer
The transaction amount in the smallest money decimal (e.g. cents for euro).
Example: 1000
-
CLIENTEMAIL email(5-255)
The user’s email.
Example: john.snow@example.com
-
CLIENTIDENT string(1-255)
Unique identifier of the user in your application (e.g. a login or a primary key).
Example: john.snow
-
CURRENCY string(3)
Currency code (ISO 4217 format).
Example: EUR
-
DESCRIPTOR string
The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.
Example: myshop.com
-
EXECCODE string(4)
The operation result code. (See the complete list of execution code)
Example: 0000
-
EXTRADATA string(1-255)
Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).
Example: referrer=myshop.com;order=premium
-
HASH string(64)
The transaction’s hash as described in the dedicated section.
Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4
-
IDENTIFIER string(1-32)
Your processing account technical identifier.
Example: YOUR_IDENTIFIER
-
LANGUAGE
fr
,en
,de
,es
,it
,nl
,zh
,ru
,pt
,sk
Configure the hosted form display language.
Example: en
-
MESSAGE string(no length limit)
The operation result description linked to
EXECCODE
.Example: The transaction has been accepted
-
OPERATIONTYPE capture
The action you want to process.
Example: payment
-
ORDERID string(1-40)
Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)
Example: 1234
-
TRANSACTIONID string(1-32)
Unique Dalenys transaction ID. Make sure to store this ID in your database.
Example: A1123456
-
VERSION
3.0
The API protocol version.
Example: 3.0
Refund
Refunds can either be processed through server-to-server request or Dalenys Extranet.
Example
Here is a server to server request example:
$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=refund" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=refund" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
Parameters
-
AMOUNT integer
The amount to refund. When not specified, refund 100% of the initial transaction resting amount. Could not be higher than the resting amount.
Example: 1000
-
DESCRIPTION string(1-510)
A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.
Example: Knows nothing
-
EXTRADATA string(1-255)
Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).
Example: referrer=myshop.com;order=premium
-
HASH string(64)
The transaction’s hash as described in the dedicated section.
Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4
-
IDENTIFIER string(1-32)
Your processing account technical identifier.
Example: YOUR_IDENTIFIER
-
OPERATIONTYPE refund
The action you want to process.
Example: payment
-
ORDERID string(1-40)
Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)
Example: 1234
-
TRANSACTIONID string(1-32)
The
capture
’sTRANSACTIONID
you want torefund
.Example: A1123456
-
VERSION
3.0
The API protocol version.
Example: 3.0
Request result
Here is the request result from the platform:
-
DESCRIPTOR string
The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.
Example: myshop.com
-
EXECCODE string(4)
The operation result code. (See the complete list of execution code)
Example: 0000
-
MESSAGE string(no length limit)
The operation result description linked to
EXECCODE
.Example: The transaction has been accepted
-
OPERATIONTYPE refund
The action you want to process.
Example: payment
-
TRANSACTIONID string(1-32)
Unique Dalenys transaction ID. Make sure to store this ID in your database.
Example: A1123456
Notification result parameters
Here is the request result from the platform:
-
AMOUNT integer
The transaction amount in the smallest money decimal (e.g. cents for euro).
Example: 1000
-
CLIENTEMAIL email(5-255)
The user’s email.
Example: john.snow@example.com
-
CLIENTIDENT string(1-255)
Unique identifier of the user in your application (e.g. a login or a primary key).
Example: john.snow
-
CURRENCY string(3)
Currency code (ISO 4217 format).
Example: EUR
-
DESCRIPTOR string
The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.
Example: myshop.com
-
EXECCODE string(4)
The operation result code. (See the complete list of execution code)
Example: 0000
-
EXTERNALENTITYID int (1-10)
Merchant account’s reference
Example:
-
EXTERNALREFERENCE int (9)
Transaction’s reference (string left padded with 0 of 9 digits)
Example: 19
-
EXTRADATA string(1-255)
Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).
Example: referrer=myshop.com;order=premium
-
HASH string(64)
The transaction’s hash as described in the dedicated section.
Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4
-
IDENTIFIER string(1-32)
Your processing account technical identifier.
Example: YOUR_IDENTIFIER
-
LANGUAGE
fr
,en
,de
,es
,it
,nl
,zh
,ru
,pt
,sk
Configure the hosted form display language.
Example: en
-
MESSAGE string(no length limit)
The operation result description linked to
EXECCODE
.Example: The transaction has been accepted
-
OPERATIONTYPE refund
The action you want to process.
Example: payment
-
ORDERID string(1-40)
Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)
Example: 1234
-
TRANSACTIONID string(1-32)
Unique Dalenys transaction ID. Make sure to store this ID in your database.
Example: A1123456
-
VERSION
3.0
The API protocol version.
Example: 3.0
Sandbox test card numbers
You can use the bankcard sandbox test card numbers to trigger specific execution codes in the sandbox environment.