Apple Pay

Overview

Apple Pay is a payment method to buy goods and services in iOS apps or in your system. 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. Perform one-time purchases and COF purchases through this method by using Payment Page and Gate, as well as refunds and customer's card verification by using Gate.

Download the logo in vector format here.
Payment method type Contactless payments
Countries and regions See here the list of supported countries.
Payment currencies All currencies supported by American Express, Maestro, Mastercard, and Visa payment systems in supported regions
Currency conversion On Rocketpay side
One-step purchase
Two-step purchase
COF payments
Payouts
Full refunds
Partial refunds
Card verification
Notes
  • Devices—from the list of supported Apple devices
  • Browser—Safari
  • Payment cards—American Express, Maestro, Mastercard, Visa
  • The way of Payment Page opening—any way except opening a Payment Page embedded into a web page
  • Chargebacks are available, contact your Rocketpay key account manager for more details.
  • Requirements for your system for purchases via Gate support:
    • The site domain should be registered in the Apple services. For registration follow step-by-step instructions provided on Apple developer portal
    • The site supports scripting functionality to start an Apple session according to documentation.
Onboarding and access fee Refer to the Rocketpay key account manager

Interaction diagram

Payment processing by using the Apple Pay payment method requires your system, one of the interfaces, and the Rocketpay payment platform, as well as provider's technical facilities.



Operations support

  Interfaces Amount Times
Payment Page Gate Dashboard minimum maximum basic threshold
One-step purchase * * * *
Authorization hold within two-step purchase * * * *
Settlement or authorization hold removal within two-step purchase * *
Registering COF purchase * *
Debiting within registered COF purchase * *
Refunds * *

* For more information, refer to the Rocketpay key account manager.

You can check the payment amount limits in your project by using Dashboard. To check your payment amount limits, go to Dashboard, select the Projects section and click the Payment methods tab.

Processing scenarios

To perform payments via Apple Pay, a customer needs to just register their payment card once using their Apple device and then 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 analyze the information on payments and operations.

One-step purchase by using Payment Page

General information

To perform a purchase by using Payment Page with the Apple Pay payment method:

  1. Send a request with all the required parameters and a signature to the Rocketpay URL.
  2. Accept the callback with the purchase result from the Rocketpay payment platform.

The following figure shows the complete purchase processing flow in the Apple Pay payment method.



Figure: Purchase sequence by using Payment Page:

  1. The customer initiates a purchase in your system.
  2. Your system sends a purchase request through Payment Page to the Rocketpay URL.
  3. The Rocketpay payment platform receives the request.
  4. The payment platform processes the request and checks whether it contains all the required parameters and that the signature is correct.
  5. The payment platform creates the checkout page based on the project settings and request parameters.
    Note: At this point, the payment platform determines the type of purchase to perform (a one-step or a two-step purchase) based on the project settings.
  6. The checkout page is displayed to the customer.
  7. The customer chooses to make a purchase with the Apple Pay payment method.
  8. The Payment Page forwards the purchase request to the payment platform.
  9. The payment platform sends the request for starting a payment session to the Apple Pay service.
  10. The request for starting a payment session is processed and the session data is generated on the Apple Pay side.
  11. The payment platform receives payment session data from the Apple Pay.
  12. The Payment Page receives payment session initialization data from the payment platform.
  13. The Payment Page initiates a payment session and displays the Apple Pay app or interface to the customer for purchase confirmation.
  14. The customer completes all required steps and confirms the purchase.
  15. 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 initial request processing and sends a request to the card organisation service.
  19. The purchase request is processed on the card organisation side.
  20. The Apple Pay service sends the payment result information to the payment platform.
  21. The payment platform sends a callback with the payment result to your system.
  22. The payment platform sends the payment result to Payment Page.
  23. Payment Page displays the payment result to the customer on the checkout page.

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

Request for opening the payment form

This section provides instructions on how to build the request for opening the payment form with the Apple Pay payment method.

Table 1. Basic parameters of requests for opening the payment form by using Payment Page

strictly required—the parameter must be in the initial request.

optional—the parameter is optional but adding it to the request either makes the payment process more customer-friendly or helps to increase the percentage of successful payments.
Parameter Description

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

customer_id
string
strictly required

 Unique ID of the customer within your project.

Example: customer_123

customer_first_name
string
strictly required

 Customer's first name.

Example: John

customer_last_name
string
strictly required

 Customer's last name.

Example: Doe

customer_email
string
strictly required

 Customer's email.

Example: johndoe@example.com

card_holder
string
strictly required

 Customer's last name.

Example: Doe

payment_currency
string
strictly required

 Code of the purchase currency in the ISO-4217 alpha-3 format.

Example: KZT

payment_amount
integer
strictly required

 Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 1000.00 KZT must be sent as 100000

signature
string
strictly required

 Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

force_payment_method
string
optional

 Parameter that allows you to enforce the Apple Pay payment method for your customer and skip the page with payment method selections.
To enforce the Apple Pay payment method and skip the page with payment method selection, add the force_payment_method parameter to the request and set its value to either of the following:
  • apple_pay_core—to open Payment Page with preselected payment method Apple Pay
  • card—to make payment by using either a payment card or Apple Pay. In this case customer can chose the payment method on Payment Page.
For more information about enforcing payment methods, see Preselecting payment methods.

Example: force_payment_method: 'apple_pay_core'

recurring
string
optional

 Add this parameter if you need to register the COF purchase and set its value to the URL-encoded JSON object with the COF purchase parameters. Here is an example of such a JSON object (before URL-encoding): 
{"register":true}
For more information on how to register COF purchase through Payment Page, see COF purchase registration.
You can also add any other optional parameters to the request, if necessary. For the list of all the parameters possible in requests to Payment Page, see Payment Page invocation parameters.

Here is an example of the data from a request to open the payment form by using EPayWidget:

EPayWidget.run(
    { 
        project_id: 123, 
        payment_id: 'payment_47', 
        customer_id: 'customer_123',
        customer_first_name: 'John',
        customer_last_name: 'Doe',
        card_holder: 'Doe',    
        customer_email: 'johndoe@example.com',
        payment_currency: 'KZT', 
        payment_amount: 100000,
        force_payment_method: 'apple_pay_core',
        recurring: '%7B%22register%22%3Atrue%7D',
        signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO\/RLUkDJrOcZzUCwX6R'
    }
)

Callback

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

If the purchase request to the payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback from the payment platform will contain a recurring object with the identifier of the registered COF purchase in the id parameter.

The following is an example of a callback with information about a successful 1000.00 KZT purchase made in the 123 project.

Figure: Example of a successful purchase callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "recurring": {
        "id": 12345
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "date": "2022-03-25T11:08:45+0000",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The following is an example of a callback for a declined purchase.

Figure: Example of data from a declined purchase callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "created_date": "2022-03-25T11:19:53+0000",
        "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb",
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "date": "2022-03-25T11:20:30+0000",
            "auth_code": ""
        }
    },
    "signature": "J7W15rkqrLzTCD4HkoM4qoEnlVlfqz8155QSlXJKR4m8C4z2iFYv58P4Vn/jmY+g=="
}

Related topics

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

One-step purchase by using Gate

General information

To perform a purchase by using Gate with the Apple Pay payment method:

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

The following figure provides the details of a one-step purchase processing flow in the Apple Pay payment method.



Figure: Purchase by using Gate

  1. The customer initiates a purchase in your system.
  2. Your system sends a request to start the payment session to Gate.
  3. The Rocketpay payment platform receives the request.
  4. The payment platform checks whether the request contains all the required parameters and a correct signature.
  5. The request for starting a payment session is redirected to the Apple Pay service.
  6. Apple Pay processes the request for starting a payment session.
  7. The payment platform receives payment session data from the Apple Pay.
  8. The payment platform sends a callback with the data for starting a payment session to your system.
  9. Your system 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. Apple Pay service processes customer data.
  12. The customer is redirected to the your system's waiting page.
  13. Your system receives encrypted customer data from the Apple Pay service.
  14. Your system sends the request for purchase processing to the specified Rocketpay URL.
  15. The payment platform receives the request for purchase processing.
  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 your system. For more information, see Response structure.
  18. The payment platform processes the request and sends it to the card organisation service.
  19. Card organisation processes the purchase request.
  20. Card organisation sends the payment result notification to the payment platform.
  21. The payment platform sends the callback with the payment result to your system.
  22. Your system sends the payment result to the customer.

The sections that follow discuss in more details the format of requests and parameters of a Gate request when working with the Apple Pay payment method, as well as the format of callbacks with the payment results. For the general information on how to use the Gate API, see API Description.

Request for starting a payment session

This section provides instructions on how to build a request for starting a payment session with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/session/applepay
Full API endpoint specification /v2/session/applepay
Table 2. Basic parameters of a request for starting a payment session by using Gate

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

validation_url
string
strictly required

 URL for validation.

Example: apple-pay-gateway.apple.com/paymentservices/startSession

domain_name
string
strictly required

 Domain name of your web service.

Example: appay.en.ngrok.io

display_name
string
strictly required

 Project name to be displayed, max. 64 characters.

Example: test payment

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.
You can also add any other optional parameters to the request, if necessary. For the list of all the parameters possible in requests to Gate, see Registering COF purchase.

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

Figure: Example of a request for starting a payment session

{
  "general": {
    "project_id": 123,
    "signature": "VJ/h5ogVuQ6oMNLLxvvKe3Ef6Jw7wV8bt1cPYZcSQduYBT6o+Se5",
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain_name": "appay.eu.ngrok.io",
    "display_name": "test payment"
  }
}

Request for a purchase

This section provides the instructions on how to build a purchase request with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/sale
Full API endpoint specification /v2/payment/applepay/sale
Table 3. Basic parameters of a purchase request

strictly required—the parameter must be in the initial request.

optional—the parameter is optional but adding it to the request either makes the payment process more customer-friendly or helps to increase the percentage of successful payments.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

id
string
strictly required

 Unique ID of the customer within your project.

Example: customer_123

ip_address
string
strictly required

 IP address of the customer's device.

Example: 198.51.100.47

first_name
string
strictly required

 Customer's first name.

Example: John

last_name
string
strictly required

 Customer's last name.

Example: Doe

email
string
strictly required

 Customer's email.

Example: johndoe@example.com

payment
object
strictly required

amount
integer
strictly required

 Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 1000.00 KZT must be sent as 100000

currency
string
strictly required

 Code of the payment currency in the ISO-4217 alpha-3 format.

Example: KZT

etoken
object
strictly required

token
string
strictly required

 Token that represents card details received from the Apple Pay service.

Example: "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"

recurring
object
optional

register
boolean
optional

 COF purchase registration flag; use true value to have a COF purchase registered. For more information on how to register a COF purchase through Gate, see Registering COF purchase.

Example: true

type
string
optional

 Type of the COF purchase: R (for Regular payment), C (for OneClick payment), or U (for Autopayment), for more information, refer to Overview.

Example: R

period
string
optional

 Regular payment performing period.
Possible values:
  • D—daily
  • W—weekly
  • M—monthly
  • Q—quarterly
  • Y—yearly.

Example: W

time
string
optional

 Regular payment performing time in the hh:mm:ss (UTC0) format.

Example: 10:00:00

scheduled_payment_id
integer
optional

 Identifier of the next COF purchase.

Example: 567890

start_date
string
optional

 The start date of regular payments, in the DD-MM-YYYY format (must be at least one day later than the date of registration).

Example: 10-10-2020

interval
integer
optional

 Regular payment performing interval. Multiplicator to increase debiting period, for example if you need to run debiting every third week, you can set period to W and interval to 3. Possible values: from 1 to 100.

Example: 3

expiry_year
integer
optional

 Regular payments end year.

Example: 2025

expiry_month
integer
optional

 Regular payments end month.

Example: 5

expiry_day
integer
optional

 Regular payments end day.

Example: 5
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of data from a purchase request.

Figure: Example of a purchase request

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 100000,
        "currency": "KZT"
    },
    "etoken": {
        "token": "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"
    },
    "recurring": {
        "register": true,
        "type": "R",
        "period": "W",
        "interval": 3,
        "time": "10:00:00",
        "scheduled_payment_id": "567890",
        "start_date": "10-10-2020",
        "expiry_year": 2025,
        "expiry_month": 5,
        "expiry_day": 5
    }
}

Callback

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

If the purchase request to the payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback from the payment platform will contain a recurring object with the identifier of the registered COF purchase in the id parameter.

The following is an example of a callback with information about a successful 1000.00 KZT purchase in the 123 project.

Figure: Example of a successful purchase callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2019-08-30T13:58:12+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "account": {
        "number": "123456"
    },
    "recurring": {
        "id": 12345
    },
    "operation": {
        "id": 28,
        "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": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "date": "2019-08-30T13:58:09+0000",
            "auth_code": "591748"
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67MbzypSxU2KS33RFCKlyphMTlWSNEuh"
}

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

Figure: Example of a declined purchase callback

 {
    "project_id": 123,
    "country": "KZ",
    "product_name": "Visa Rewards",
    "issuer_name": "Bank name",
    "account": {
        "number": "123456"
    },
    "customer": {
        "id": "customer_123"
    },
    "payment": {
        "date": "2019-08-06T12:57:03+0000",
        "id": "payment_47",
        "method": "etoken",
        "status": "decline",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "type": "purchase",
        "description": "test"
    },
    "operation": {
        "id": 28,
        "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": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "auth_code": ""
        },
        "code": "10105",
        "message": "Insufficient funds on card"
    },
    "signature": "9CIXvWMsKOcQsWEHKLsSVAyjRoWsamH6wOqYCdXre8kY9rpDi"
}

Related topics

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

Two-step purchase by using Payment Page

General information

When performing a two-step purchase by using the Apple Pay method through Payment Page, you can only apply the authorization hold. To perform the settlement, you need to send another request through the Gate API. For more information on how to request settlements, see Request for removing authorization hold.

In order to apply authorization hold by using Payment Page, your system needs to send a request with all the required parameters and a signature to the Rocketpay URL and accept the callback with the authorization hold result from the payment platform.

The full authorization hold application sequence within two-step purchase workflow is shown below.



Figure: Purchase processing steps for an authorization hold by using Payment Page

  1. The customer initiates a purchase in your system.
  2. Your system sends a purchase request through Payment Page to the Rocketpay URL.
  3. The Rocketpay payment platform receives the request.
  4. The payment platform processes the request and checks whether it contains all the required parameters and that the signature is correct.
  5. The payment platform creates the checkout page based on the project settings and request parameters.
    Note: At this point, the payment platform determines the type of purchase to perform (one-step or two-step purchase) based on the project settings.
  6. The checkout page is displayed to the customer.
  7. The customer chooses to make a purchase with the Apple Pay payment method.
  8. The Payment Page forwards the purchase request to the payment platform.
  9. The payment platform sends the request for starting a payment session to the Apple Pay service.
  10. The request for starting a 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 payment session initialization data from the payment platform.
  13. The Payment Page initiates a 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. 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 initial request processing and sends a request to the card organisation service.
  19. The authorization hold request is processed on the card organisation side.
  20. The Apple Pay service sends the authorization hold result information to the payment platform.
  21. The payment platform sends a callback with the authorization hold result to your system.
  22. The payment platform sends the payment result to the Payment Page.
  23. The Payment Page displays the payment result to the customer on the checkout page.

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

Request for opening the payment form

This section provides instructions on how to build the request for opening the payment form with the Apple Pay payment method.

Table 4. Basic parameters of requests for opening the payment form by using Payment Page

strictly required—the parameter must be in the initial request.

optional—the parameter is optional but adding it to the request either makes the payment process more customer-friendly or helps to increase the percentage of successful payments.
Parameter Description

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

customer_id
string
strictly required

 Unique ID of the customer within your project.

Example: customer_123

customer_first_name
string
strictly required

 Customer's first name.

Example: John

customer_last_name
string
strictly required

 Customer's last name.

Example: Doe

customer_email
string
strictly required

 Customer's email.

Example: johndoe@example.com

card_holder
string
strictly required

 Customer's last name.

Example: Doe

payment_currency
string
strictly required

 Code of the purchase currency in the ISO-4217 alpha-3 format.

Example: KZT

payment_amount
integer
strictly required

 Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 1000.00 KZT must be sent as 100000

signature
string
strictly required

 Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

force_payment_method
string
optional

 Parameter that allows you to enforce the Apple Pay payment method for your customer and skip the page with payment method selections.
To enforce the Apple Pay payment method and skip the page with payment method selection, add the force_payment_method parameter to the request and set its value to either of the following:
  • apple_pay_core—to open Payment Page with preselected payment method Apple Pay
  • card—to make payment by using either a payment card or Apple Pay. In this case customer can chose the payment method on Payment Page.
For more information about enforcing payment methods, see Preselecting payment methods.

Example: force_payment_method: 'apple_pay_core'

recurring
string
optional

 Add this parameter if you need to register the COF purchase and set its value to the URL-encoded JSON object with the COF purchase parameters. Here is an example of such a JSON object (before URL-encoding): 
{"register":true}
For more information on how to register COF purchase through Payment Page, see COF purchase registration.
You can also add any other optional parameters to the request, if necessary. For the list of all the parameters possible in requests to Payment Page, see Payment Page invocation parameters.

Here is an example of the data from a request to open the payment form by using EPayWidget:

EPayWidget.run(
    {
        project_id: 123,
        payment_id: 'payment_47',
        customer_id: 'customer_123',
        customer_first_name: 'John',
        customer_last_name: 'Doe',
        card_holder: 'Doe', 
        customer_email: 'johndoe@example.com',   
        payment_currency: 'KZT',
        payment_amount: 100000,
        force_payment_method: 'apple_pay_core',
        recurring: '%7B%22register%22%3Atrue%7D',
        signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO\/RLUkDJrOcZzUCwX6R'
    }
)

Callback

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

If the purchase request to the payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback from the payment platform will contain a recurring object with the identifier of the registered COF purchase in the id parameter.

The following is an example of a callback with an information about a successful 1000.00 KZT authorization hold for the purchase made in the 123 project.

Figure: Example of the data from a successful authorization hold callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "auth",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "recurring": {
        "id": 12345
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60",
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4"
}

The following is an example of a callback for a declined purchase.

Figure: Example of data from a declined authorization hold callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "created_date": "2022-03-25T11:19:53+0000",
        "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb",
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "auth_code": ""
        }
    },
    "signature": "J7W15rkqrLzTCD4HkoM4qoEnlVlfqz8155QSlXJKR4m8C4z2iFYv58P4VnHANu4"
}

Related topics

Two-step purchase by using Gate

General information

In the Apple Pay method, your system is required to do the following when processing a two-step purchase by using Gate:

  1. Send a request for starting a payment session with all the required parameters and a signature to the Rocketpay URL.
  2. Receive customer and payment session data.
  3. Send a request for an authorization hold with all the required parameters and a signature to the Rocketpay URL.
  4. Accept the callback with the authorization hold result from the Rocketpay payment platform.
  5. Send a request for performing the settlement with all the required parameters and a signature to the Rocketpay URL.
  6. Get the callback with the payment result from the Rocketpay payment platform.
Note: Before performing a two-step purchase by using the Apple Pay method through Gate, you need to set up the interaction between your service and Apple Pay.

The two-step purchase is performed in two steps:

  1. Application of an authorization hold.
  2. Settlement or removal of the authorization hold.

The following figure provides the detailed picture of the two-step purchase processing flow in the Apple Pay payment method.

Figure: Step 1. Authorization hold



Figure: Step 2. Settlement



Figure: Step 2. Removing the authorization hold



Figure: Step 1. Authorization hold by using Gate

  1. The customer initiates a purchase in your system.
  2. Your system sends the purchase request to Gate.
  3. The Rocketpay payment platform receives the request.
  4. The payment platform checks whether the request contains all the required parameters and a correct signature.
  5. The request for starting a payment session is redirected to the Apple Pay service.
  6. Apple Pay processes the request for starting a payment session.
  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 a payment session to your system.
  9. Your system 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. Apple Pay service processes customer data.
  12. the customer is redirected to the your system's waiting page.
  13. Your system receives encrypted customer data from the Apple Pay.
  14. Your system sends the request for purchase processing to the specified Rocketpay URL.
  15. The payment platform receives the request for purchase processing.
  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 your system. For more information, see Response structure.
  18. The payment platform processes the request and sends it to the card organisation service.
  19. Card organisation processes the purchase request.
  20. Card organisation sends the payment result notification to the payment platform.
  21. The payment platform sends the callback with the payment result to your system.
  22. Your system sends the payment result to the customer.

Figure: Step 2. Settlement by using Gate

  1. Your system sends a request for performing the settlement within the two-step purchase by using Gate to the Rocketpay URL.
  2. The payment platform receives the settlement request from Gate.
  3. The payment platform performs the initial request processing that involves validation of the required parameters and signature.
  4. The payment platform sends the response with request receipt confirmation and validation result to your system. For more information about the response format, see Response structure.
  5. The payment platform performs the internal payment request processing and forwards the request to the bank service.
  6. The bank service processes the request.
  7. The bank service sends the settlement result notification to the payment platform.
  8. The payment platform sends the callback with the settlement result to your system.

Figure: Step 2. Removing the authorization hold through Gate

  1. Your system sends a request for removing the authorization hold within the two-step purchase by using Gate to the Rocketpay URL.
  2. The payment platform receives the request for removing the authorization hold from Gate.
  3. The payment platform performs the initial request processing that involves validation of the required parameters and signature.
  4. The payment platform sends the response with request receipt confirmation and validation result to your system. For more information about the response format, see Response structure.
  5. The payment platform performs the internal payment request processing and forwards the request to the bank service.
  6. The bank service processes the request.
  7. The bank service sends a notification with the result of the authorization hold removal to the payment platform.
  8. The payment platform sends the callback with the authorization hold removal result to your system.

The sections that follow discuss in more details the format of requests and parameters of a Gate request when working with the Apple Pay payment method, as well as the format of callbacks with two-step purchase results. For the general information on how to use the Gate API, see API Description.

Request for starting a payment session

This section provides the instructions on how to build a request for starting a payment session with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/session/applepay
Full API endpoint specification /v2/session/applepay
Table 5. Basic parameters of a request for starting a payment session by using Gate

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

validation_url
string
strictly required

 URL for validation.

Example: apple-pay-gateway.apple.com/paymentservices/startSession

domain_name
string
strictly required

 Domain name of your web service.

Example: appay.en.ngrok.io

display_name
string
strictly required

 Project name to be displayed, max. 64 characters.

Example: test payment

signature
string
strictly required

 Signature is created after you specify all the required parameters.

For more information about signature generation, see Signature generation and verification.
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

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

Figure: Example of a request for starting a payment session

{
  "general": {
    "project_id": 123,
    "signature": "VJ/h5ogVuQ6oMNLLxvvKe3Ef6Jw7wV8bt1cPYZcSQduYBT6o+Se5",
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain_name": "appay.eu.ngrok.io",
    "display_name": "test payment"
  }
}

Request for an authorization hold

This section provides instructions on how to build an authorization hold request with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/auth
Full API endpoint specification /v2/payment/applepay/auth
Table 6. Basic parameters of a request for an authorization hold

strictly required—the parameter must be in the initial request.

optional—the parameter is optional but adding it to the request either makes the payment process more customer-friendly or helps to increase the percentage of successful payments.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

id
string
strictly required

 Unique ID of the customer within your project.

Example: customer_123

ip_address
string
strictly required

 IP address of the customer's device.

Example: 198.51.100.47

email
string
strictly required

 Customer's email.

Example: johndoe@example.com

first_name
string
strictly required

 Customer's first name.

Example: John

last_name
string
strictly required

 Customer's last name.

Example: Doe

payment
object
strictly required

amount
integer
strictly required

 Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. The amount and currency must match the values in the auth request. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 1000.00 KZT must be sent as 100000

currency
string
strictly required

 Code of the purchase currency in the ISO-4217 alpha-3 format.

Example: KZT

etoken
object
strictly required

token
string
strictly required

 Token that represents card details received from the Apple Pay service.

Example: "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"

recurring
object
optional

register
boolean
optional

 COF purchase registration flag; use true value to have the COF purchase registered. For more information on how to register COF purchase through Gate, see Registering COF purchase.

Example: true

type
string
optional

 Type of the COF purchase: R (for Regular payment), C (for OneClick payment), or U (for Autopayment), for more information, refer to Overview.

Example: R

period
string
optional

 Regular payment performing period.
Possible values:
  • D—daily
  • W—weekly
  • M—monthly
  • Q—quarterly
  • Y—yearly.

Example: W

time
string
optional

 Regular payment performing time in the hh:mm:ss (UTC0) format.

Example: 10:00:00

scheduled_payment_id
integer
optional

 Identifier of the next COF purchase.

Example: 567890

start_date
string
optional

 The start date of regular payments, in the DD-MM-YYYY format (must be at least one day later than the date of registration).

Example: 10-10-2020

interval
integer
optional

 Regular payment performing interval. Multiplicator to increase debiting period, for example if you need to run debiting every third week, you can set period to W and interval to 3. Possible values: from 1 to 100.

Example: 3

expiry_year
integer
optional

 Regular payments end year.

Example: 2025

expiry_month
integer
optional

 Regular payments end month.

Example: 5

expiry_day
integer
optional

 Regular payments end day.

Example: 5
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of data from an authorization hold request by using Apple Pay.

Figure: Example of an authorization hold request

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 100000,
        "currency": "KZT"
    },
    "etoken": {
        "token": "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"
    },
    "recurring": {
        "register": true,
        "type": "R",
        "period": "W",
        "interval": 3,
        "time": "10:00:00",
        "scheduled_payment_id": "567890",
        "start_date": "10-10-2020",
        "expiry_year": 2025,
        "expiry_month": 5,
        "expiry_day": 5
    }
}

Request for a settlement

This section provides instructions on how to build a settlement request with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/capture
Full API endpoint specification /v2/payment/applepay/capture
Table 7. Basic parameters of a settlement request

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.

payment
object
strictly required

amount
integer
strictly required

 Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. The amount and currency must match the values in the auth request. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 1000.00 KZT must be sent as 100000

currency
string
strictly required

 Code of the purchase currency in the ISO-4217 alpha-3 format. The currency must match the value passed in the authorization hold request.

Example: KZT
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of data from a settlement request.

Figure: Example of a settlement request

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4"
    },
    "payment": {
        "amount": 100000,
        "currency": "KZT"
    }
}

Request for removing authorization hold

This section provides instructions on how to build the request for removing authorization hold with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/cancel
Full API endpoint specification /v2/payment/applepay/cancel
Table 8. Basic parameters for a request to remove an authorization hold

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of data from a removing an authorization hold request by using Apple Pay.

Figure: Example of a removing an authorization hold request

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4"
    }
}

Callback

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

If the purchase request to the payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback from the payment platform will contain a recurring object with the identifier of the registered COF purchase in the id parameter.

The following is an example of a callback with information about a 1000.00 KZT authorization hold.

Figure: Example of the data from a callback for a successful authorization hold 

{
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "awaiting capture",
        "date": "2025-02-23T09:31:16+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 25656,
            "payment_id": "1234567890",
            "auth_code": "130510"
        },
        "id": 5009268010192904,
        "type": "auth",
        "status": "success",
        "date": "2025-02-23T09:31:16+0000",
        "created_date": "2025-02-23T09:31:13+0000",
        "request_id": "f2c569dcfc8caaad230-d449fed468dc...120188b71513288e5-05009269"
    },
    "signature": "Xwv0+3w+3K4CBlCK2mzNZ7hvSs740DmNYheH...Z4uRUnDNoASiem+Kd7emCOy3A=="
}

The following is an example of a callback for a declined authorization hold.

Figure: Example of the data from a callback for a declined authorization hold

{
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2025-02-24T07:34:35+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "10201",
        "message": "Refer to card issuer",
        "provider": {
            "id": 25656,
            "payment_id": "1234567890",
            "auth_code": ""
        },
        "id": 88969010166206,
        "type": "auth",
        "status": "decline",
        "date": "2025-02-24T07:34:35+0000",
        "created_date": "2025-02-24T07:34:32+0000",
        "request_id": "aa0c10c70169a00eab6ed...f7ed1e4b24e104bfd3001c98-00088970"
    },
    "signature": "JsoAt+YE03GvTxHqlp43kN/Ao...8YZu9PObd3K2E3Syd+AYgwG1Fr8sOqw=="
}

The following is an example of a callback with information about a successful settlement.

Figure: Example of the data from a callback for a successful settlement

{
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2025-02-23T09:31:21+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 25656,
            "payment_id": "1234567890",
            "auth_code": "130510"
        },
        "id": 5009268010192914,
        "type": "capture",
        "status": "success",
        "date": "2025-02-23T09:31:21+0000",
        "created_date": "2025-02-23T09:31:19+0000",
        "request_id": "7574f98f58c447319961af...7d2c84fb999aba28b0da7-05009269"
    },
    "signature": "R9VlffmrKlv0o4f6WyOVfmCeUp...Rtq++cU4RSXAuwwP7qRPJr68MX/XwPw=="
}

The following is an example of a callback for a declined settlement.

Figure: Example of the data from a callback for a declined settlement

{
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "awaiting capture",
        "date": "2025-02-14T11:02:40+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "10000",
        "message": "General decline",
        "provider": {
            "id": 18592,
            "payment_id": "",
            "auth_code": ""
        },
        "id": 5044775010195824,
        "type": "capture",
        "status": "decline",
        "date": "2025-02-14T11:02:40+0000",
        "created_date": "2025-02-13T16:55:17+0000",
        "request_id": "365e5a5c177e49a69635a1e...cb6867da2414f92a5967-05044776"
    },
    "signature": "aFarg/tVTKX8OfrCupyWwfi4y...YhyY8lZEqa2hPjpVt5zo2f8wMZdQ=="
}

The following is an example of a callback with information about the authorization hold removal.

Figure: Example of the data from a callback for a successful authorization hold removal

{
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "canceled",
        "date": "2025-02-22T19:05:16+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 18592,
            "payment_id": "",
            "auth_code": "",
            "date": "2025-02-22T19:05:16+0000"
        },
        "id": 5051368010197754,
        "type": "cancel",
        "status": "success",
        "date": "2025-02-22T19:05:16+0000",
        "created_date": "2025-02-22T19:05:12+0000",
        "request_id": "e591ce7e99b371e034ba167...81ce0f32182620116e622-05051369"
    },
    "signature": "P98J30+t6uApD+Wa7rCUK25OICC...uimTzYoGxFzMPyoHNFaPa5b6g=="
}

The following is an example of a callback for a declined authorization hold removal.

Figure: Example of the data from a callback for a declined authorization hold removal

 {
    "customer_ip": "2.73.213.76",
    "project_id": 84031,
    "payment": {
        "type": "purchase",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "status": "awaiting capture",
        "method": "etoken",
        "id": "payment_47",
        "date": "2025-02-20T11:11:34+0000",
        "description": "TEST_PAYMENT_951914"
    },
    "customer": {
        "id": "customer_123",
        "card_type": "mastercard"
    },
    "account": {
        "number": "123456"
    },
    "issuer_name": "JOINT STOCK COMMERCIAL BANK - TBC BANK",
    "recurring": {
        "valid_thru": "2028-02-29T23:59:59+0000",
        "id": 1696779776,
        "currency": "KZT"
    },
    "operation": {
        "type": "cancel",
        "sum_initial": {
            "currency": "KZT",
            "amount": 100000
        },
        "sum_converted": {
            "currency": "KZT",
            "amount": 100000
        },
        "status": "decline",
        "request_id": "cancel_88358010120206-a9e702a...306b99c45e0dd-00088359",
        "provider": {
            "payment_id": "",
            "id": 18592,
            "auth_code": ""
        },
        "message": "General decline",
        "id": 88358010167846,
        "date": "2025-02-20T11:11:34+0000",
        "created_date": "2025-02-20T11:11:32+0000",
        "code": "20000"
    },
    "signature": "vfDSFTFOYB+h7AuyP6XMWBzTJJa0gXB...ondmQ14w6S2LgJKzWYeSZY9A=="
}

Related topics

COF purchase 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: workflow and statuses.

This section describes how to perform a new payment within registered a COF purchase. For information on how to register a COF purchase, see the Request sections of the topics about one-step and two-step purchases.

In the Apple Pay method, your system is required to do the following when processing a payment within the registered COF purchase by using Gate:

  1. Send the request with all the required parameters and a signature to the Rocketpay URL to initiate a COF payment.
  2. Accept the callback with the COF payment result from the payment platform.

The following diagram provides the detailed picture of the processing flow of a payment within a registered COF purchase.



Figure: New COF payment by using Gate

  1. The customer initiates a new payment within the registered COF purchase on your system's side. This step is optional.
  2. Your system sends a request for processing the COF payment by using Gate to the Rocketpay URL.
  3. The payment platform receives the request for processing the COF payment.
  4. The payment platform performs the initial request processing that includes validation whether all the required parameters are available and that the signature is correct.
  5. The payment platform sends the response with request receipt confirmation and validation result to the your system. For more information about the response format, see Response structure.
  6. The payment platform performs the internal payment request processing and forwards the request to the bank service.
  7. The bank service processes the request.
  8. The bank service sends the payment result notification to the payment platform.
  9. The payment platform sends the callback with the payment result to your system.
  10. Your system sends the payment result to the customer.

The sections that follow discuss in more details the format of requests and parameters of a Gate request when working with the Apple Pay payment method, as well as the format of callbacks with the payment results, when performing a new payment within the registered COF purchase. For the general information on how to use the Gate API, see API Description.

Request for a COF purchase

This section provides the instructions on how to build a request for a COF purchase with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/recurring
Full API endpoint specification /v2/payment/applepay/recurring
Table 9. Basic parameters of a COF purchase request

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

id
string
strictly required

 Unique ID of the customer within your project.

Example: customer_123

ip_address
string
strictly required

 IP address of the customer's device.

Example: 198.51.100.47

email
string
strictly required

 Customer's email.

Example: johndoe@example.com

first_name
string
strictly required

 Customer's first name.

Example: John

last_name
string
strictly required

 Customer's last name.

Example: Doe

payment
object
strictly required

amount
integer
strictly required

 Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. The amount and currency must match the values in the auth request. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 1000.00 KZT must be sent as 100000

currency
string
strictly required

 Code of the purchase currency in the ISO-4217 alpha-3 format.

Example: KZT

recurring
object
strictly required

id
string
strictly required

 ID of the COF purchase.

Example: 12345
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of data from a COF purchase request.

Figure: Example of a COF purchase request 

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2"
    },
    "customer": {
        "ip_address": "198.51.100.47"
    },
    "payment": {
        "amount": 100000,
        "currency": "KZT"
    },
    "recurring": {
        "id": 12345
    }
}

Request for cancellation of the COF purchase

COF payments can be canceled until the due date. Also, to change the conditions of COF purchases, you must cancel it and send a request to register a new one.

This section provides the instructions on how to build a request for a COF purchase cancellation with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/recurring/cancel
Full API endpoint specification /v2/payment/applepay/recurring/cancel
Table 10. Basic parameters of a COF purchase cancellation request

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.

recurring
object
strictly required

id
string
strictly required

 Registered COF purchase identifier.

Example: 12345
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.
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": 123,
        "payment_id": "payment_47",
        "signature": "DH0v2pZnkK9hwytQ6/ZtDSQh+wwx/OqrWdbltzO5GMSkzd0Iq6lM2v8"
    },
    "recurring": {
        "id": 12345
    }
}

Callback

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

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

Figure: Example of a successful COF purchase 

 {
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "recurring",
        "status": "success",
        "date": "2018-11-20T08:44:46+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": "payment"
    },
    "account": {
        "number": "123456"
    },
    "recurring": {
        "id": 12345,
        "currency": "",
        "valid_thru": "-0001-11-30T00:00:00+0000"
    },
    "operation": {
        "id": 28,
        "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": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "date": "2020-11-20T08:44:45+0000",
            "auth_code": ""
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq=="
}

The following is an example of a callback after a COF payment cancellation.

Figure: Example of a COF payment cancellation

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "recurring",
        "status": "success",
        "date": "2018-11-20T08:44:46+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": "payment"
    },
    "account": {
        "number": "123456"
    },
    "recurring": {
        "id": 12345,
        "currency": "",
        "valid_thru": "-0001-11-30T00:00:00+0000"
    },
    "operation": {
        "id": 28,
        "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": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "date": "2020-11-20T08:44:45+0000",
            "auth_code": ""
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq=="
}

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

Figure: Example of a declined COF purchase 

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "recurring",
        "status": "success",
        "date": "2018-11-20T08:44:46+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": "payment"
    },
    "errors": [
        {
            "code": "2701",
            "message": "Rules Failed Code",
            "description": "fatal: RULES_FAILED_CODE"
        }
    ],
    "recurring": {
        "id": 12345,
        "currency": "",
        "valid_thru": "-0001-11-30T00:00:00+0000"
    },
    "operation": {
        "id": 28,
        "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": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "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:

Refund by using Gate

General information

To perform a refund by using Gate for a purchase made with the Apple Pay payment method:

  1. Send a request with all the required parameters and signature to the Rocketpay URL.
  2. Accept the callback with the refund result from the payment platform.

The following picture provides all the details of the refund processing flow in the Apple Pay payment method.



Figure: Refund processing flow when performing a refund by using Gate

  1. The customer initiates a refund in your system.
  2. Your system sends the request for refund to Gate.
  3. The Rocketpay payment platform receives the request.
  4. The payment platform checks whether the request contains all the required parameters and a correct signature.
  5. The payment platform sends the response with request receipt confirmation and correctness check result to your system. For more information, see Response structure.
  6. The payment platform processes the request and forwards it to the Apple Pay service.
  7. The Apple Pay service processes the refund request.
  8. The Apple Pay service informs the payment platform about the refund result.
  9. The payment platform sends you the callback with the refund result.
  10. Your system sends the refund result to the customer.

The sections that follow discuss in more details the format of requests and parameters of a Gate request when working with the Apple Pay payment method, as well as the format of callbacks with the refund results. For the general information on how to use the Gate API, see API Description.

Request for a refund

This section provides instructions on how to build a refund request with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/refund
Full API endpoint specification /v2/payment/applepay/refund
Table 11. Basic parameters of a refund request

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

ip_address
string
strictly required

 IP address of the customer's device.

Example: 198.51.100.47

email
string
strictly required

 Customer's email.

Example: johndoe@example.com

first_name
string
strictly required

 Customer's first name.

Example: John

last_name
string
strictly required

 Customer's last name.

Example: Doe

payment
object
strictly required

description
string
strictly required

 Refund description.

Example: refund_02
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of data from a refund request.

Figure: Example of a refund request 

{
    "general": {
        "project_id": 123,
        "payment_id": "refund_02",
        "signature": "of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1"
    },
    "customer": {
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "description": "refund_02"
    }
}

Callback

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

The following is an example of a callback with information about a successful 1000.00 KZT refund in project 123.

Figure: Example of a successful refund callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "refunded",
        "date": "2020-01-20T08:31:36+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "operation": {
        "id": 28,
        "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": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "auth_code": ""
        }
    },
    "signature": "beJ1deUiEDd+7zuo6YrfSRxbOn8BYDLI9RR3yliH3B91LcBan4+2VkRrxn2NYOexr7"
    }

The following is an example of a callback for a refund declined due to the refund amount being larger than the initial payment amount.

Figure: Example of a declined refund callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2020-01-20T08:31:36+0000",
        "method": "etoken",
        "sum": {
            "amount": 100000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456"
    },
    "operation": {
        "sum_initial": {
            "amount": 100000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 100000,
            "currency": "KZT"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 1187,
            "payment_id": "1234567890",
            "auth_code": ""
        },
        "id": 28,
        "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+2VkRrxn2NYO"
}

Related topics

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

Payment card verification

General information

To perform payment card verification through the Apple Pay method, your system sends a request with all the required parameters and a signature to Rocketpay 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 card verification.

Request for a payment card verification

This section provides instructions on how to build the request for a payment card verification with the Apple Pay payment method.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/applepay/account_verification
Full API endpoint specification /v2/payment/applepay/account_verification
Table 12. Basic parameters for a payment card verification

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters.

For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

ip_address
string
strictly required

 IP address of the customer's device.

Example: 198.51.100.47

payment
object
strictly required

amount
integer
strictly required

 Purchase amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 1000.00 KZT must be sent as 100000

currency
string
strictly required

 Code of the purchase currency in the ISO-4217 alpha-3 format.

Example: KZT

etoken
object
strictly required

token
string
strictly required

 Token that represents card details received from the Apple Pay service.

Example: "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here is an example of data from a card verification request in the Apple Pay method.

Figure: Example of a card verification request

{
  "general": {
     "project_id": 123,
     "payment_id": "payment_47",
     "signature": "96c+hWk1zweuGKwDRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4"
    },
    "customer": {
    "ip_address": "198.51.100.47"
    },
  "payment": {
    "amount": 100000,
    "currency": "KZT"
    },
    "etoken": {
        "token": "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"
    }
}

Callback

The Apple Pay method uses the standard format for callbacks to deliver results. For more information, see Payment card 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 you to perform full-fledged testing. When testing purchases by using Gate your system must adhere to the following requirements:
  • The we service domain should be registered in the Apple services. For registration contact the Rocketpay technical support support@rocketpay.kz
  • The site supports scripting functionality to start an Apple session according to documentation

Other notes which are specified in Overview should be taken into account when testing purchases.

Testing can be performed within a test project, to enable and disable the testing availability, contact Rocketpay technical support via support@rocketpay.kz. 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:

  • decline status with 2000, 5000 or 10001 amount
  • success status with any other amount

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

  • decline status with 0 amount
  • success status with any other amount

Testing one-step purchase 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 One-step purchase by using Payment Page.

Testing one-step purchase 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 One-step purchase by using Gate.

Testing one-step purchases by applying authorization hold through Payment Page and capturing or canceling through 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 One-step purchase by using Payment Page and One-step purchase by using Gate.

Testing purchase one-step purchases by applying authorization hold and capturing or canceling through 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 One-step purchase by using Gate.

Testing 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 Rocketpay offers, when using this method, you have several options to analyze the information about payments and operations.

You can load and analyze all the necessary information in Dashboard (dashboard.rocketpay.kz), for instance you can use the analytic panels in the Analytics section for this purpose.

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 format by using the tools in the Reports section. You can perform export as a one-time or regular download of data to your local computer.
  • 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 means of sending requests to the /operations/get endpoint.

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