Apple Pay

Overview

Apple Pay is a payment method to buy goods and services in iOS apps or on your web service. With Apple Pay, customers authorize payments using Face ID, Touch ID or passcode to release tokenized credit and debit card payment credentials stored securely on their devices. They can also use Wallets to store their billing, shipping, and contact information, which can be provided along with payment credentials. You can perform one-time purchases and COF purchases through this method by using Payment Page and Gate, refunds, and customer's card verification by using Gate.

General information

Payment method type digital wallet payments
Payment instruments payments cards
Countries and regions The list is available at the link
Payment currencies All currencies supported by American Express, Maestro, Mastercard and Visa payment systems in supported regions
Currency conversion On ecommpay side
Purchases +
Payouts –
Stored credentials payments +
Full refunds +
Partial refunds +
Card verification +
Chargebacks +
Notes
Onboarding and access fee Refer to the ecommpay key account manager

Interaction diagram

Payment processing by using the Apple Pay payment method requires merchant's web service, one of ecommpay interfaces, and the ecommpay payment platform, as well as provider's the technical facilities.



Operations support

  Interfaces Amounts Times**
Payment Page CMS Plug-ins Gate Dashboard minimum maximum basic threshold
Purchases + – + – * * * *
Stored credentials payments + – + – * * * *
Full refunds – – + – – – * *
Partial refunds – – + – – – * *

* For more information refer to the ecommpay key account manager.

** The basic and threshold times are defined as follows:
  • The basic time is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the initiator. The basic time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour (if any input from customer is required). Use the basic time to estimate when to react to the absence of payment result notifications or when to check payment status.
  • The threshold time is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the initiator receives the callback with the payment result. A payment is automatically declined, if its waiting time exceeds the threshold time. For individual setting of the threshold time limit, contact ecommpay technical support.

Processing scenarios

To perform payments via Apple Pay, a customer needs to register their payment card on Apple device once and use Touch ID, Face ID, password or double-click the side button on Apple Watch to confirm the purchase.

Figure: Purchase by using Payment Page procedure



Figure: Purchase by using Gate procedure



Figure: Refund by using Gate procedure



The sections that follow provide detailed information about what you need to perform payments and how you can analyse the information on payments and operations.

Purchases by using Payment Page

General information

In the Apple Pay methods, when processing a purchase by using Payment Page, the merchant web service should send a request with all the required parameters and signature to the ecommpay URL and get the callback with the payment result from the payment platform. When opening Payment Page, you can have Payment Page opened with one of the Apple Pay methods selected. For more information about preselecting payment methods, see in Preselecting payment methods. The full sequence and particularities of the purchase process are provided below.



Figure: Purchase sequence in the Payment Page method:

  1. A customer initiates a purchase on the merchant's web service.
  2. The web service sends the request for Payment Page opening to the specified ecommpay URL.
  3. The request for the Payment Page opening is redirected to the payment platform.
  4. The payment platform performs the initial request processing that involves validation of the required parameters and signature.
  5. Requested Payment Page is generated into the ecommpay payment platform as specified in the project settings and the request parameters.
  6. Payment Page is displayed to the customer.
  7. The customer selects the Apple Pay method.
  8. The payment platform receives the request for starting payment session from Payment Page.
  9. The payment platform sends the request for starting payment session to the Apple Pay service.
  10. The request for starting payment session is processed and the session data is generated on the Apple Pay side.
  11. The payment platform receives the payment session data from the Apple Pay.
  12. The Payment Page receives the payment session initialization data from the payment platform.
  13. The Payment Page initiates the payment session and displays the Apple Pay app or interface for purchase confirmation to the customer.
  14. The customer completes all required steps and confirms the purchase.
  15. The customer data is processed on the Apple Pay service side.
  16. The customer is redirected to the Payment Page waiting page.
  17. The payment platform receives encrypted customer data from the Apple Pay service.
  18. The payment platform performs the initial request processing and sends request to the card organisation service.
  19. The purchase request is processed on the card organisation side.
  20. The card organisation sends the result notification to the payment platform.
  21. The payment platform sends a callback with the payment result to the web service.
  22. The payment platform sends the result to Payment Page.
  23. A page with the payment result information is displayed to the customer on Payment Page.

The sections that follow discuss in more details the request format and the Payment Page parameters to use in the Apple Pay payment method and provide the information on the format of callbacks with payment results. For the general information on how to use the API, see Payment Page API Description.

Request format

There are several things you need to consider when opening the payment form to perform a purchase by using the Apple Pay method:

  1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are mandatory for any payment method:
    • customer_id—the unique ID of the customer within your project
    • project_id—the project ID obtained from ecommpay
    • payment_id—payment ID unique within the project
    • payment_currency—payment currency in ISO-4217 alpha-3 format
    • payment_amount—payment amount in minor units
  2. If you need to have payment form displayed with the Apple Pay method selected, set the force_payment_method parameter to:
    • apple_pay_core—to open Payment Page with pre-selected payment method Apple Pay
    • card—for the ability of payment by using either a payment card or Apple Pay. In this case customer can chose the payment method on Payment Page
  3. If required, you can also add any other additional parameters Payment Page supports. For information about all parameters available, see Parameters for opening payment form.
  4. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign a payment request, see Signature generation and verification.

Thus, a correct payment request in the Apple Pay method must include project, customer and payment IDs, the currency and the amount of a payment in the appropriate currency, as shown in the following example:

EPayWidget.run(
    { customer_id: '123',
      payment_id: 'X03936', 
      payment_amount: 100000, 
      payment_currency: 'RUB', 
      project_id: 247, 
      signature: "mcsgn6KHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOc
                                                                ZzUCwX6R\/ekpZhkIQg=="
    }
)

Callback format

The Apple Pay method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 1,000.00 RUB purchase made by using the 480099******9286 card in the 580 project.

Figure: Example of a successful purchase callback

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15671726468667687",
            "type": "purchase",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "method": "etoken",
            "sum": {
                "amount": 100000,
                "currency": "RUB"
            },
            "description": "ECT_TEST_1567172646866"
        },
        "account": {
            "number": "480099******9286"
        },
        "operation": {
            "id": 47478000001698,
            "type": "sale",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "created_date": "2019-08-30T13:58:06+0000",
            "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3",
            "sum_initial": {
                "amount": 100000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "24fb3f30-000f-5000-8000-1c329d900c68",
                "date": "2019-08-30T13:58:09+0000",
                "auth_code": "591748"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67MbzypSxU2KS33RFCKlyphMTlWSNEuhc06gW
                                                       Q7IZpU6i9siv7+WD1u7AyIYdQ=="
    }
}

The following is the example of a callback for a purchase declined due to insufficient funds on card.

Figure: Example of a declined purchase callback

 {
        "account": {
            "number": "480623******2326"
        },
        "customer": {
            "id": "964282"
        },
        "payment": {
            "date": "2019-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "RU",
        "product_name": "Visa Rewards",
        "issuer_name": "Tinkoff Bank",
        "operation": {
            "id": 45047000000055,
            "type": "sale",
            "status": "decline",
            "date": "2019-08-06T12:57:03+0000",
            "created_date": "2019-08-06T12:57:00+0000",
            "request_id": "f92c3dfdf76133d5e1a9d26279b3b77b7da32e",
            "sum_initial": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVAyjRoWsamH6wOqYCdXre8kY9rpDixPlNKv8yVTP
                                                     5U5SRo8YNjIxHPjEEQSmLAtClQ=="
    }
}

Related topics

The following topics might be useful when implementing payments by using Payment Page:

Purchases by using Gate

General information

In the Apple Pay methods, when processing a purchase by using Gate, the merchant web service is required to do the following:

  1. Send a request for starting payment session with all the required parameters and signature to the ecommpay URL.
  2. Receive customer and payment session data.
  3. Send a purchase request with all the required parameters and signature to the ecommpay URL.
  4. Get the callback with the payment result from the payment platform.

The following diagram provides the detailed picture of the payment processing procedure.



Figure: Purchase by using Gate

  1. A customer initiates a purchase through Apple Pay on the merchant's web service side.
  2. The web service sends the request for starting Apple Pay payment session to the specified ecommpay URL.
  3. The payment platform receives the request for starting the payment session from Gate.
  4. The payment platform performs the initial request processing that includes validation of the required parameters and signature.
  5. The request for starting payment session is redirected to the Apple Pay service.
  6. The request for starting payment session is processed on the Apple Pay side.
  7. The payment platform receives the payment session data from the Apple Pay.
  8. The payment platform sends the callback with the data for starting the payment session to the web service.
  9. The web service initiates the payment session and displays the Apple Pay app or interface for purchase confirmation to the customer.
  10. The customer completes all required steps and confirms the purchase.
  11. The customer data is processed on the Apple Pay service side.
  12. The customer is redirected to the web service waiting page.
  13. The web service receives encrypted customer data from the Apple Pay.
  14. The web service sends the request for purchase processing to the specified ecommpay URL.
  15. The payment platform receives the request for processing the payment.
  16. The payment platform performs the initial request processing that involves validation of the required parameters and signature.
  17. The payment platform sends the response with request receipt confirmation and correctness check result to the web service. For more information, see Response format.
  18. The payment platform processes the request and sends it to the card organisation service.
  19. The purchase request is processed on the card organisation side.
  20. The card organisation sends the payment result notification to the payment platform.
  21. The payment platform sends a callback to the web service.
  22. The customer receives the payment result on the web service.

The sections that follow discuss in more details the request format and the Gate parameters to use in the Apple Pay payment method and provide the information on the format of callbacks with purchase results.

Request format for starting payment session

There are several things you must consider when using requests in the Apple Pay method:
  1. You send requests for starting payment session by sending the /v2/session/applepay request by using HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • general—general purchase information:
      • project_id—project identifier
      • validation_url—URL for validation
      • domain_name—domain name of the merchant web service
      • display_name—the name of the project to display, must contain no more than 64 characters
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification

A correct request in the Apple Pay method for starting payment session is shown in the following example:

Figure: Example of a purchase request

{
  "general" : {
    "project_id": 175,
    "signature": "VJ/h5ogVuQ6oMNLLxvvKe3Ef6Jw7wV8bt1cPYZcSQduYBT6o+Se5mDLXHChlDZrjJXZZ
                                             4Kg2iI0w7/zWHELFnBx1afjhlWmwOGfYK2/tw==",
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain_name": "appay.eu.ngrok.io",
    "display_name": "test payment"
  }
}

Purchase request format

There are several things you must consider when using purchase requests in the Apple Pay method:
  1. You send purchase requests by using HTTP method POST:
  2. The following objects and parameters must be specified in any request:
    • general—general purchase information:
      • project_id—project identifier
      • payment_id—unique purchase identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • customer—customer information:
      • id—the unique ID of the customer within your project
      • ip_address—customer IP address
    • payment—purchase information:
      • amount—purchase amount in the minor currency units
      • currency—purchase currency in the ISO-4217 alpha-3 format
    • etoken— information about token that represents card details received from the Apple Pay service:
      • token—token received from Apple Pay in JSON format after user identification, must be specified as a string. The value of this parameter can contain such information as the payment identifier on the Apple Pay side, the type of the international payment system, and various service data.

        Figure: An example of a JSON structure for a token that should be specified as a string

        {
   "paymentData":{
      "version":"EC_v1",
      "data":"perkYfGgfMXL/lTG DCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==",
      "header":{
         "ephemeralPublicKey":"MWnwEQ==",
         "publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=",
         "transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"
      }
   },
   "paymentMethod":{
      "displayName":"Visa 1005",
      "network":"Visa",
      "type":"debit"
   },
   "transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"
}

        Figure: An example of the value of the token parameter as a string

        "token": "{"paymentData":{"version":"EC_v1","data":"perkYfGgfMXL/lTGDCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==","header":{"ephemeralPublicKey":"MWnwEQ==","publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=","transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"}},"paymentMethod":{"displayName":"Visa 1005","network":"Visa","type":"debit"},"transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"}"
  3. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the Apple Pay method must include project, customer and payment IDs, IP address, currency and amount of the purchase, Apple Pay token, and the signature, as shown in the following example:

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "customer": {
    "ip_address": "83.220.236.84",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "etoken": {
        "token": "..."
    }
}

Two-step purchase capture request format

There are several things you must consider when using capture requests in the Apple Pay method:
  1. You send purchase requests by using HTTP method POST to /v2/payment/applepay/capture.
  2. The following objects and parameters must be specified in any request:
    • general—general purchase information:
      • project_id—project identifier
      • payment_id—purchase identifier to be confirmed
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • payment—purchase information:
      • amount—purchase amount in the minor currency units
      • currency—purchase currency in the ISO-4217 alpha-3 format
  3. The amount and currency must match the values in the auth request.
  4. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the Apple Pay method must include project and payment IDs, currency and amount of the purchase, and the signature, as shown in the following example:

Figure: Example of a purchase capture request

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  }

Two-step purchase cancellation request format

There are several things you must consider when using cancel requests in the Apple Pay method:
  1. You send purchase requests by using HTTP method POST to /v2/payment/applepay/cancel.
  2. The following objects and parameters must be specified in any request:
    • general—general purchase information:
      • project_id—project identifier
      • payment_id—purchase identifier to be cancelled
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
  3. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the Apple Pay method must include project and payment IDs, and the signature:

Figure: Example of a purchase cancellation request

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  }

Callback format

The Apple Pay method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 1,000.00 RUB purchase made by using the 480099******9286 card in the 580 project.

Figure: Example of a successful purchase callback

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15671726468667687",
            "type": "purchase",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "method": "etoken",
            "sum": {
                "amount": 100000,
                "currency": "RUB"
            },
            "description": "ECT_TEST_1567172646866"
        },
        "account": {
            "number": "480099******9286"
        },
        "operation": {
            "id": 47478000001698,
            "type": "sale",
            "status": "success",
            "date": "2019-08-30T13:58:12+0000",
            "created_date": "2019-08-30T13:58:06+0000",
            "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3",
            "sum_initial": {
                "amount": 100000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "24fb3f30-000f-5000-8000-1c329d900c68",
                "date": "2019-08-30T13:58:09+0000",
                "auth_code": "591748"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67MbzypSxU2KS33RFCKlyphMTlWSNEuhc06gW
                                                       Q7IZpU6i9siv7+WD1u7AyIYdQ=="
    }
}

The following is the example of a callback for a purchase declined due to insufficient funds on card.

Figure: Example of a declined purchase callback

 {
        "account": {
            "number": "480623******2326"
        },
        "customer": {
            "id": "964282"
        },
        "payment": {
            "date": "2019-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "RU",
        "product_name": "Visa Rewards",
        "issuer_name": "Tinkoff Bank",
        "operation": {
            "id": 45047000000055,
            "type": "sale",
            "status": "decline",
            "date": "2019-08-06T12:57:03+0000",
            "created_date": "2019-08-06T12:57:00+0000",
            "request_id": "f92c3dfdf76133d5e1a9d26279b3b77b7da32e",
            "sum_initial": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1030000,
                "currency": "RUB"
            },
            "provider": {
                "id": 1187,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVAyjRoWsamH6wOqYCdXre8kY9rpDixPlNKv8yVTP
                                                     5U5SRo8YNjIxHPjEEQSmLAtClQ=="
    }
}

Related topics

The following topics might be useful when implementing payments through Gate:

COF purchases by using Payment Page

General information

The Apple Pay payment method provides the ability to perform COF purchases—regular on-demand payments. For more information about COF purchases, see On-demand COF purchase.

Registration of a COF purchases is also available by using Payment Page. For registration the web service must send a request containing the required parameters and signature, as well as data for registering a COF purchase in the recurring object, to the ecommpay URL and accept a callback with the result. In the callback about registering a COF purchase, you will get its ID, which you need to use to make or cancel regular payments via Gate or Dashboard. For more information, see the section COF purchases by using Gate.

The sections that follow discuss in more detail the request format and the Payment Page parameters to use in the Apple Pay payment method and provide the information on the format of callbacks with payment results. For the general information on how to use the API, see Payment Page API Description.

Request format

There are several things you need to consider when creating requests to open a payment form for registering COF purchases by using the Apple Pay method:

  1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are mandatory for any payment method:
    • customer_id—the unique ID of the customer within your project
    • project_id—the project ID obtained from ecommpay
    • payment_id—payment ID unique within the project
    • payment_currency—payment currency in ISO-4217 alpha-3 format
    • payment_amount—payment amount in minor units
  2. To register a COF purchase, you must pass a recurring object containing the registration attribute and the necessary information. To register regular payments, the request must contain information about the frequency, amount, and beginning and end time of regular payments. The full list of parameters that can be passed in the recurring object is shown in the COF purchase registration section.
  3. If you need to have payment form displayed with the Apple Pay method selected, set the force_payment_method parameter to:
    • apple_pay_core—to open Payment Page with pre-selected payment method Apple Pay
    • card—for the ability of payment by using either a payment card or Apple Pay. In this case customer can chose the payment method on Payment Page
  4. If required, you can also add any other additional parameters Payment Page supports. For information about all parameters available, see Parameters for opening payment form.
  5. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign a payment request, see Signature generation and verification.

Thus, a correct payment request in the Apple Pay method must include project, customer and payment IDs, the currency and the amount of a payment in the appropriate currency, as shown in the following example:

EPayWidget.run(
    { payment_id: 'X03936', 
      payment_amount: 100000, 
      payment_currency: 'RUB', 
      project_id: 208,
      customer_id: '123',
      force_payment_method: 'apple_pay_core',
      recurring={"register":true,"type":"R","expiry_year":2025,"expiry_month":"01","period":"D","time":"10:00:00","start_date":"15-11-2020","scheduled_payment_id":"A2323"},
      signature: "mcsgn6KHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO...=="
    }
)

Callback format

The Apple Pay method uses the standard format for callbacks to deliver COF purchase registration results. For more information, see Callbacks.

The following is the example of a callback with an information about successful COF purchase registration made by a customer in the 208 project.

Figure: Example of a successful COF purchase registration callback

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "purchase",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken",
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "account": {
            "number": "489537******3478"
        },
        "recurring": {
            "id": 1000030038,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

Related topics

The following topics might be useful when implementing payments by using Payment Page:

COF purchases by using Gate

General information

The Apple Pay payment method provides the ability to perform COF purchases—regular on-demand payments. For more information about COF purchases, see On-demand COF purchase.

The sections that follow discuss in more details the requests formats and parameters to use in the Apple Pay payment method and the information about the format of callbacks with payment results. The general information about working with API see in the API Description section.

COF purchase registration

To register a COF purchase by using Gate, the merchant is required to send a request for purchase with all the required parameters, signature, and the COF purchase registration parameter recurring.register: true to the ecommpay URL and get the callback with the payment result from the payment platform. To register a regular payment the request should also contain information about the frequency, amount, start and end dates of the regular payments.

In the COF purchase registration callback you receive its identifier, which you can use to perform or cancel regular payments.

For more information about purchase processing by using Gate, see Purchases by using Gate.

Requests format

There are several things you must consider when performing COF purchases registration in the Apple Pay method:

  1. You send the request by using POST (HTTP) method to the one of the URL: /v2/payment/applepay/sale or /v2/payment/applepay/auth
  2. The following objects and parameters must be specified in the request:
    • Object general—general information:
      • project_id—project identifier
      • payment_id—unique payout identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object customer—customer information:
      • id—the unique ID of the customer within your project
      • ip_address—customer IP address
    • Object payment—payment information:
      • amount—payment amount in the minor currency units
      • currency—payment currency in the ISO-4217 alpha-3 format
    • Object recurring—COF purchase information:
      • register—payment registration as a COF purchase
      • type—type of the COF purchase: R (for Regular payment), C (for OneClick payment), or U (for Autopayment), for more information, refer to Overview
      • scheduled_payment_id—identifier of the next COF purchase
      • start_date—the start date of regular payments, in the DD-MM-YYYY format (must be at least one day later than the date of registration)
      • amount—amount of debiting
      • period—regular payment performing period
      • interval— regular payment performing interval
      • time—regular payment performing time in the hh:mm:ss (UTC0) format
  3. If required, you can also add any other additional parameters Gate supports.

A correct COF purchase registration request through the Apple Pay method must include project, customer and payment IDs, customer IP-address, signature, currency and amount of the purchase, as well as the registration parameter and the conditions for regular payments, as shown in the following example:

Figure: COF purchase registration request example

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "id": "123",
    "ip_address": "1.1.1.1"
  },
  "payment": {
    "amount": 1000,
    "currency": "RUB"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

COF purchase performing

After the payment is registered, the funds are debited according to the specified regular payment conditions. You initiate COF purchase by sending a recurring request to the payment platform.

Request format

There are several things you must consider when performing COF purchases performing in the Apple Pay method:

  1. You can perform COF purchases by sending the request by using POST (HTTP) method to the /v2/payment/applepay/recurring.
  2. The following objects and parameters must be specified in the request:
    • Object general—general purchase information:
      • project_id—project identifier
      • payment_id—unique payout identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object customer—customer information:
      • ip_address—customer IP address
    • Object payment—payment information:
      • amount—payment amount in the minor currency units
      • currency—payment currency in the ISO-4217 alpha-3 format
    • Object recurring—COF purchase information:
      • id—registered COF purchase identifier
  3. If required, you can also add any other additional parameters Gate supports.

So that a correct COF purchase request through the Apple Pay method must include project and payment IDs, customer IP-address, signature, currency and amount of the payment, as shown in the following example:

Figure: COF purchase performing request example

 {
  "general": {
    "project_id": 238,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2v8rmWQV4sbP+4A==",
  },
  "customer": {
    "ip_address": "87.245.207.226"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "recurring": {
    "id": 1234567890
  }
}

Cancellation of the COF purchases performing

Until the expiration date of COF purchases performing, you can cancel it. Also, to change the conditions of COF purchases, you must cancel it and send a request to register a new one.

Request format

There are several things you must consider when performing COF purchases cancellation in the Apple Pay method:

  1. You can perform COF purchases by sending the request by using POST (HTTP) method to the /v2/payment/applepay/recurring/cancel.
  2. The following objects and parameters must be specified in the request:
    • Object general—general purchase information:
      • project_id—project identifier
      • payment_id—unique payout identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object recurring—COF purchase information:
      • id—registered COF purchase identifier
  3. If required, you can also add any other additional parameters Gate supports.
A correct COF purchase cancellation request through the Apple Pay method must include project and payment IDs, customer IP-address, signature, currency and amount of the purchase, as well as the COF purchase identifier, as shown in the following example:

Figure: Regular payment cancellation request example

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2v8rmWQV4sbP+4A==",
  },
  "recurring": {
    "id": 1234567890
  }
}

Callback format

The standard format for callbacks is used to deliver the results of actions with COF purchases. For more information, see Callbacks.

The following is the example of a callback with an information about COF purchase registration for a customer in the 208 project.

Figure: Example of succeed COF purchase registration

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken",
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "account": {
            "number": "489537******3478"
        },
        "recurring": {
            "id": 1000030038,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

The following is the example of a callback after regular payment cancellation.

Figure: Example of regular payment cancellation callback

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken",
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "account": {
            "number": "489537******3478"
        },
        "recurring": {
            "id": 1000030038,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring_cancel",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

The following is the example of a callback with an information about declined COF purchase.

Figure: Example of declined COF purchase registration

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken",
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "errors": [
            {
                "code": "2701",
                "message": "Rules Failed Code",
                "description": "fatal: RULES_FAILED_CODE"
            }
        ],
        "recurring": {
            "id": 1000700,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring",
            "status": "decline",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "2701",
            "message": "Rules Failed Code"
        },
        "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

Related topics

The following topics might be useful when implementing payments through Gate:

Refunds by using Gate

General information

Apple Pay supports full and partial refunds processing. To perform a refund through the Apple Pay method, merchant's web service sends a request with all the required parameters and signature to ecommpay URL, and receives a callback with the payment result. The full sequence of the payout process is provided below.



Figure: Refund sequence by using Gate

  1. A customer orders a refund on the merchant's web service side.
  2. Merchant's web service sends the request for the refund processing by using Gate to the appropriate ecommpay URL.
  3. Gate redirects the request to the ecommpay payment platform.
  4. The payment platform performs all the necessary checks and processes the request.
  5. The reply with the request processing results is sent to the merchant's web service. For more information, see Response format.
  6. The payment platform redirects the refund request to the card organisation service.
  7. The payment is processed on the card organisation side.
  8. The card organisation sends the result notification to the payment platform.
  9. The payment platform sends a callback with the payment result to the web service.
  10. The customer receives the refund result from the web service.

The sections that follow discuss in more details the request format and the Gate parameters to use in the Apple Pay payment method and provide the information on the format of callbacks with refund results.

Request format

There are several things you must consider when using refund requests in the Apple Pay method:
  1. You perform purchase by sending the request by using POST (HTTP) method to /v2/payment/applepay/refund.
  2. The following objects and parameters must be specified in any request:
    • Object general—general refund information:
      • project_id—project identifier
      • payment_id—unique refund identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object customer—customer information:
      • ip_address—customer IP address
    • Object payment—refund information:
      • description—comment or description
      • amount—refund amount in minor units (mandatory for partial refund only)
      • currency—refund currency in ISO-4217 alpha-3 format (mandatory for partial refund only)
  3. If required, you can also add any other additional parameters Gate supports.

Thus, a correct partial refund request in the Apple Pay method must include project and payment IDs, signature, currency and amount of the refund, refund description and customer IP address, as shown in the following example:

Figure: Example of a partial refund request 

{
   "general": {    
    "project_id": 239,    
    "payment_id": "refund_02",   
    "signature": "of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },  
   "customer": {    
     "ip_address": "1.2.3.4" 
  },  
   "payment": {    
     "amount": 50000,    
     "currency": "RUB",
     "description": "refund_02"
 }
}

Callback format

The Apple Pay method uses the standard format for callbacks to deliver refund results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 10,00 RUB partial refund for the customer card number 480114******3791 in the 260 project.

Figure: Example of a successful refund callback

{
        "project_id": 260,
        "payment": {
            "id": "TEST_15792507735",
            "type": "purchase",
            "status": "refunded",
            "date": "2020-01-20T08:31:36+0000",
            "method": "etoken",
            "sum": {
                "amount": 1000,
                "currency": "RUB"
            },
            "description": ""
        },
        "customer": {
            "id": "1888"
        },
        "account": {
            "number": "480114******3791"
        },
        "operation": {
            "id": 69512000019571,
            "type": "refund",
            "status": "success",
            "date": "2020-01-20T08:31:36+0000",
            "created_date": "2020-01-20T08:31:35+0000",
            "request_id": "e0069513"
            "sum_initial": {
                "amount": 1000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RUB"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1911,
                "payment_id": "0000438583",
                "auth_code": ""
                }
            },
        "signature": "beJ1deUiEDd+7zuo6YrfSRxbOn8BYDLI9RR3yliH3B91LcBan4+2VkRrxn2NYOexr7goJzgEQj34sKAStuW8Fg=="
    }

The following is the example of a callback for a refund declined due to the refund amount is more than init amount.

Figure: Example of a declined refund callback

{
        "project_id": 260,
        "payment": {
            "id": "TEST_1579250773501",
            "type": "purchase",
            "status": "success",
            "date": "2020-01-20T08:31:36+0000",
            "method": "etoken",
            "sum": {
                "amount": 100,
                "currency": "RUB"
            },
            "description": ""
        },
        "customer": {
            "id": "1888"
        },
        "account": {
            "number": "480114******3791"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "RUB"
            },
            "code": "3283",
            "message": "Refund amount more than init amount",
            "provider": {
                "id": 1911,
                "payment_id": "0000438582",
                "auth_code": ""
            },
            "id": 69512000019571,
            "type": "refund",
            "status": "decline",
            "date": "2020-01-20T08:31:36+0000",
            "created_date": "2020-01-20T08:31:35+0000",
            "request_id": "e0069142"
        },
        "signature": "beJ1deUiEDd+7zuo6YrfSRxbOn8BYDLI9RR3yliH3B91LcBan4+2VkRrxn2NYOexr7goJzgEQj34sKAStuW8Fg=="
    }
}

Related topics

The following topics might be useful when implementing payments through Gate:

Payment card verification

General information

To perform a payment card verification through the Apple Pay method, merchant's web service sends a request with all the required parameters and signature to ecommpay URL, and receives a callback with the result. Payment card verification processing for this method is the same as standard processing sequence which is provided in the section Payment instrument verification.

Request format

There are several things you must consider when using payout requests in the method:

  1. You send payout requests by sending the request by using HTTP method POST to /v2/payment/applepay/account_verification.
  2. The following objects and parameters must be specified in any request:
    • Object general—general payout information:
      • project_id—project identifier
      • payment_id—unique payout identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object customer—customer information:
      • id—identifier in the project
      • ip_address—IP address
    • Object payment—payment information:
      • amount—payment amount in the minor currency units
      • currency—payment currency in the ISO-4217 alpha-3 format
    • etoken— information about token that represents card details received from the Apple Pay service:
      • token—token received from Apple Pay in JSON format after user identification, must be specified as a string. The value of this parameter can contain such information as the payment identifier on the Apple Pay side, the type of the international payment system, and various service data.

        Figure: An example of a JSON structure for a token that should be specified as a string

        {
   "paymentData":{
      "version":"EC_v1",
      "data":"perkYfGgfMXL/lTG DCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==",
      "header":{
         "ephemeralPublicKey":"MWnwEQ==",
         "publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=",
         "transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"
      }
   },
   "paymentMethod":{
      "displayName":"Visa 1005",
      "network":"Visa",
      "type":"debit"
   },
   "transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"
}

        Figure: An example of the value of the token parameter as a string

        "token": "{"paymentData":{"version":"EC_v1","data":"perkYfGgfMXL/lTGDCSDfR7x4Qz2E/p7WZqBBJJ+/z2iWUIEBNDsovnwhwTeVXAAAAAAAA==","header":{"ephemeralPublicKey":"MWnwEQ==","publicKeyHash":"tl+QgkoijbTvIomdnCLsdfbvwauh5656we9wvth2+1w=","transactionId":"u85785def5ce96a8ada846sre2v6r6yry5htj93e50152"}},"paymentMethod":{"displayName":"Visa 1005","network":"Visa","type":"debit"},"transactionIdentifier":"TFDG767HGSFDSJ7AL4435393E5882652"}"
  3. If required, you can also add any other additional parameters Gate supports.

Thus, a correct card verification request in the Apple Pay method must include project and payment IDs, payment and customer data, and token, as shown in the following example:

Figure: Example of card verification

{
  "general": {
    "project_id": 238,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "customer": {
    "ip_address": "83.220.236.84"
  },
  "payment": {
    "amount": 0,
    "currency": "RUB"
  },  
  "etoken": {
        "token": "..."
    }
}

Callback format

The Apple Pay method uses the standard format for callbacks to deliver results. For more information, see Payment instrument verification.

Related topics

The following topics might be useful when implementing payments through Gate:

Testing

General information

For the Apple Pay method the testing of one-step and two-step purchases by using Payment Page and Gate, as well as payment card verification by using Gate. To avoid errors during purchase testing it is recommended to use a payment card which is already registered in the Apple Pay service. This does not influence the processing of real payments by using such cards, but allows to perform full-fledged testing. When testing purchases by using Gate the web service must adhere to the following requirements:
  • The we service domain should be registered in the Apple services. For registration contact the ecommpay technical support support@ecommpay.com
  • The site supports scripting functionality to start an Apple session according to documentation

Other notes which are specified in the General information table should be taken into account when testing purchases.

Testing can be performed within a test project, to enable and disable the testing availability, contact ecommpay technical support via support@ecommpay.com. When performing a test payment, take into account that you must specify the identifier of the test project in the requests, and the interface of the payment form emulator of Payment Page page may differ from the production environment.

Test payments statuses

When testing one-step and two-step purchases, the final payment status is determined by the amount specified in the request:

  • success status is used with 1000 amount specified.
  • decline status is used with 2000, 5000, or 10001 amount specified.

When testing payment card verification, the final payment status is determined by the amount specified in the request:

  • success status is used with 0 amount specified.
  • decline status is used with any other amount specified.

One-step purchases by using Payment Page

To perform a test one-step purchase by using Payment Page, do the following:

  1. Send a correct test request for Payment Page opening to the payment platform.
  2. If the card or apple_pay_core method was not specified in the request—select the method on the emulator page.
  3. Confirm the purchase.
  4. Accept a callback with information about the payment result.

The full information about purchase process by using Apple Pay through Payment Page is provided in the section Purchases by using Payment Page.

One-step purchases by using Gate

To perform a test one-step purchase by using Gate, do the following:

  1. Send a correct test request for starting a payment session to the payment platform.
  2. Receive customer and payment session data.
  3. Confirm the purchase.
  4. Send a correct test purchase request to the payment platform.
  5. Accept a callback with information about the payment result.

The full information about purchase process by using Apple Pay through Gate is provided in the section Purchases by using Gate.

One-step purchases by performing authorization hold via Payment Page and capture or cancellation via Gate

To perform a test one-step purchase by performing authorization hold via Payment Page and capture or cancellation via Gate, do the following:

  1. Send a correct test request for Payment Page opening to the payment platform.
  2. If the card or apple_pay_core method was not specified in the request—select the method on the emulator page.
  3. Confirm the purchase.
  4. Accept a callback with information about successful authorization hold.
  5. Send a capture or cancellation request.
  6. Accept a callback with information about the result.

The full information about purchase process by using Apple Pay through Payment Page and gate is provided in the sections Purchases by using Payment Page and Purchases by using Gate.

One-step purchases by performing authorization hold and capture or cancellation via Gate

To perform a test one-step purchase by performing authorization hold and capture or cancellation via Gate, do the following:

  1. Send a correct test request for starting a payment session to the payment platform.
  2. Receive customer and payment session data.
  3. Send a correct test purchase request to the payment platform.
  4. Confirm the purchase.
  5. Accept a callback with information about successful authorization hold.
  6. Send a capture or cancellation request.
  7. Accept a callback with information about the result.

The full information about purchase process by using Apple Pay through Gate is provided in the section Purchases by using Gate.

Payment card verification by using Gate

To perform a test payment card verification by using Gate, send a correct test request for payment card verification to the payment platform and accept a callback with information about the verification result.

The full information about payment card verification process by using Apple Pay through Gate is provided in the section Payment card verification.

Analysis of payments results

As with other payment methods ecommpay offers, when using the Apple Pay method, you have several options to analyse the information about payments and operations performed by using the method—alone or in conjunction with other methods.

You can load and analyse all the necessary information in Dashboard, for instance you can use the analytic panels on the Analytics tab to this end.

Also, you can export the information for further analysis by using third party analytical tools. The following options are available:

  • Dashboard allows you to download reports in CSV and XLS formats—by using the tools on the Payments tab. You can perform export as a one-time download to your local computer or have payment data regularly exported and delivered to email addresses you specify.
  • Data API allows you to have payment information exported in JSON format and delivered to a URL you specify. The payment information is exported by using the /operations/get queries.

If you have any further questions regarding payment data analysis, contact ecommpay technical support.