Apple Pay integration

APPLE_PAY_LOGO

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

Apple Pay Workflow

  1. End-user orders on merchant website and chooses Apple Pay payment method;
  2. An order will be created in Dalenys;
  3. The end-user will be redirected to the payment page;
  4. To validate the payment, the end-user only has to authenticate on his device and a token will be sent to Dalenys;
  5. Dalenys processes the transaction with Apple Pay by sending a request to the bank network and waits for the result;
  6. You receive the result with the response redirection request;
  7. The transaction result is confirmed by a notification request sent to the merchant’s NOTIFICATION_URL, containing the transaction’s parameters (of which EXECCODE and TRANSACTIONID).

Compatible operations and options

Server to server integration

Payment / authorization

Example

Here is an Apple Pay http POST request example:

$> curl --request POST --url "https://secure-test.be2bill.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

  • 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

  • BILLINGTITLE mr, miss, mrs

    The title used for the billing address name.

    Example: mr

  • BILLINGADDRESS string(1-50)

    The billing address. Be careful not to integrate any line breaks.

    Example: 285 Fulton Street

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • BILLINGCITY string(1-255)

    The billing city.

    Example: New York

  • BILLINGCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2).

    Example: US

  • 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

  • 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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • OPERATIONTYPE payment, authorization

    The action you want to process.

    Example: payment

  • SHIPTOTITLE mr, miss, mrs

    Holder’s title in the shipping address.

    Example: mr

  • 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

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

  • SHIPTOCITY string(1-255)

    The shipping city.

    Example: New York

  • SHIPTOCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2 format)

    Example: US

  • 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

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

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

    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.

    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

  • CARDFULLNAME string(1-255)

    The holder’s full name (as described on the payment method).

    Example: JOHN SNOW

  • 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

  • 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

  • METADATA string(1-255)

    Additional transactional data. Contact your account manager for more informations.

    Example: @METADATA-MYWEBSITE

Request result

Here is the request result from the platform:

  • OPERATIONTYPE payment, authorization

    The action you want to process.

    Example: payment

  • 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

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • 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

  • REDIRECTURL string(no length limit)

    The url to redirect the user to continue the processing.

    Example: http://some_url?p1=v1

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

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • 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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, cs

    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

  • 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

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 as AMOUNT and ORDERID must be verified.

Notification result parameters

Here is the request result from the platform:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • OPERATIONTYPE payment

    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

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, cs

    Configure the hosted form display language.

    Example: en

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • 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

  • 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

  • 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

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • 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

Capture

Authorizations have to be captured by a server to server request.

info

You can only capture a succeeded authorization transaction and an authorization 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’s AMOUNT.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.be2bill.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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • OPERATIONTYPE capture

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

    The authorization’s TRANSACTIONID you want to capture.

    Example: A1123456

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • 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

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • AMOUNT integer

    When not specified, 100% of the authorization amount is captured. Could not be higher than the authorization amount.

    Example: 1000

  • 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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE capture

    The action you want to process.

    Example: payment

  • 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

  • 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

  • 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:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • 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

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, cs

    Configure the hosted form display language.

    Example: en

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • 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

  • 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

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • 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

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

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

    The capture’s TRANSACTIONID you want to refund.

    Example: A1123456

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • 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

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • 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

  • 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

Request result

Here is the request result from the platform:

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • 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

  • 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

  • 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:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • 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

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, cs

    Configure the hosted form display language.

    Example: en

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • 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

  • 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

  • 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

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • 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

Sandbox test card numbers

You can use the bankcard sandbox test card numbers to trigger specific execution codes in the sandbox environment.