Google Pay™

Overview

Google Pay is a payment method that allows customers to perform one-time purchase in one or two steps and COF purchase through Google Pay and bank services in Kazakhstan. With Google Pay, you can perform purchases by using Payment Page, Gate and Dashboard. You can perform refunds by using Gate and Dashboard.

Download the logo in vector format here.
Payment method type
  • Payments by using token
  • Card payments
Countries and regions Kazakhstan
Payment currencies KZT
Currency conversion On the JetPay side
One-step purchase
Two-step purchase
COF purchase
Payouts
Full refunds
Partial refunds
Chargebacks
Special considerations
Onboarding and access fee Refer to your key account manager at JetPay.

Interaction diagram

Payment processing by using the Google Pay payment method requires the merchant web service, one of the JetPay interfaces, the JetPay payment platform and the Google Pay service, as well as the service of one of the banks supported in this payment method.

Figure: An overall interaction diagram



Figure: Workflow 1



Figure: Workflow 2



Figure: Workflow 3



Figure: Workflow 4



Operations support

  Interfaces Amounts, KZT Times
Payment Page CMS Plug-ins Gate Dashboard minimum maximum basic threshold
One-step purchase 10.00 1 minute 48 hours
Authorization hold within two-step purchase 10.00 1 minute 48 hours
Settlement or authorization hold removal within two-step purchase 10.00 1 minute 48 hours
Registering COF purchase 10.00 1 minute 48 hours
Debiting within registered COF purchase 10.00 1 minute 48 hours
Refunds 10.00 1 minute 24 hours

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

In the Google Pay method, to perform a one-step purchase or the authorization hold within two-step purchase as well as to register a COF purchase, you need to redirect the customer to the Google Pay service. Settlement within the two-step purchase and the registered COF purchase are performed without customer participation.

Figure: One-step purchase by using Payment Page



Figure: One-step purchase by using Gate



Figure: Authorization hold within two-step purchase by using Payment Page



Figure: Authorization hold within two-step purchase by using Gate



Figure: Settlement within two-step purchase by using Gate



Figure: Removing authorization hold within two-step purchase by using Gate



Figure: COF purchase by using Gate



The sections that follow provide more information about what you need to perform payments and how you can analyze payments and operations information.

One-step purchase by using Payment Page

General information

In the Google Pay method, when processing a purchase by using Payment Page, the merchant web service sends a request with all the required parameters and signature to the JetPay URL and accepts the callback with the payment result from the payment platform.

When opening Payment Page, you can have Payment Page opened with the Google Pay method pre-selected. (For more information about pre-selecting payment methods, see Preselecting payment methods.)

The full sequence of the purchase workflow is provided below.



Figure: Purchase workflow when using Payment Page

  1. The customer initiates a purchase on the merchant's web service.
  2. The web service sends the request for the Payment Page opening to the JetPay URL.
  3. The request for opening Payment Page is redirected to the payment platform.
  4. The payment platform performs the initial request processing that includes validation whether all the required parameters are available and signature is correct.
  5. The requested Payment Page is generated by the JetPay payment platform as specified in the project settings and request parameters.
    Note: At this point, the payment platform determines the type of the purchase to perform (one-step or two-step purchase) based on the project settings.
  6. Payment Page is displayed to the customer.
  7. The customer selects Google Pay as the payment method.
  8. Payment Page sends the purchase request to the Google Pay service.
  9. The Google Pay service processes the request and generates the payment form.
  10. The Google Pay service displays the payment form to the customer.
  11. The customer chooses one of the cards registered at the Google Pay service. If the customer wants to use another card, they enter its credentials.
    Note: If the customer enters credentials of a card that is not registered with the Google Pay service, the payment will be performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2. With it the value of the method parameter will change from etoken-google to card in the final callback.
  12. The Google Pay service processes the payment.
  13. The Google Pay service sends the purchase token to the Payment Page.
  14. Payment Page sends the request for the purchase performing by using the Google Pay payment method to the JetPay payment platform.
  15. The payment platform performs the internal payment request processing and redirects the request to the bank service.
  16. The payment is processed on the bank side.
    Note: If the customer entered credentials of a card that is not registered with the Google Pay service, the payment is performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2.
  17. The bank service sends the result notification to the payment platform.
  18. The payment platform sends callback with the payment result to the web service.
  19. The payment platform sends the result to Payment Page.
  20. The page with the payment result information is displayed to the customer on Payment Page.

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

Request format

There are several things you need to consider when dealing with purchase requests in the Google Pay method:

  1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are required for any payment method:
    • project_id—project ID you obtained from JetPay
    • payment_id—payment ID unique within the project
    • customer_id—the unique ID of the customer within your project
    • customer_email—customer email
    • customer_first_name—customer first name
    • customer_last_name—customer last name
    • payment_currency—payment currency in ISO-4217 alpha-3 format
    • payment_amount—payment amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.
  2. If you need to have the payment form displayed with the Google Pay method pre-selected, set the force_payment_method parameter to the code on the google_pay_host payment method.
  3. If you need to register the COF purchase, add the recurring parameter 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.

  4. You can also add any other additional parameters Payment Page supports. For more information about parameters supported by Payment Page, see Payment Page invocation parameters.
  5. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign payment requests, see Signature generation and verification.

Here is an example of the data from a request for Payment Page opening:

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

Callback format

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

If the purchase request to the JetPay payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback from the JetPay 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 10,000.00 KZT purchase.

Figure: Example of data from a successful purchase callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "recurring": {
        "id": 12345
    },
    "operation": {
        "id": 833,
        "type": "sale",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "0",
        "message": "Success",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

Figure: Example of data from a declined purchase callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "sale",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "20000",
        "message": "General decline",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Related topics

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

One-step purchase by using Gate

General information

In the Google Pay method, your web service is required to do the following when processing a one-step purchase by using Gate:

  1. Send the request for opening the payment form to the Google Pay service.
  2. Accept the callback with the purchase token from the Google Pay service.
  3. Send the request with all the required parameters and signature to the JetPay URL.
  4. Accept the callback with the payment result from the payment platform.
Note: Before performing a one-step purchase by using the Google Pay method through Gate, you need to set up the interaction between your service and the Google Pay service as described in Google Pay Web developer documentation. Make sure you comply with Google Pay Brand Guidelines and follow Google Pay Web integration checklist.

The following diagram provides the detailed picture of the one-step purchase processing procedure.



Figure: One-step purchase by using Gate

  1. The customer initiates a purchase with Google Pay on the merchant's web service side.
  2. Your web service sends the purchase request to the Google Pay service.
  3. The Google Pay service processes the request and generates the payment form.
  4. The Google Pay service displays the payment form to the customer.
  5. The customer chooses one of the cards registered with the Google Pay service. If the customer wants to use another card, they enter its credentials.
    Note: If the customer enters credentials of a card that is not registered with the Google Pay service, the payment will be performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2. With it the value of the method parameter will change from etoken-google to card in the final callback.
  6. The Google Pay service processes the payment.
  7. The Google Pay service sends the purchase token to your web service.
  8. The web service sends a request for processing the one-step purchase by using Gate to the JetPay URL.
  9. The payment platform receives the request for processing the purchase from Gate.
  10. The payment platform performs the initial request processing that includes validation whether all the required parameters are available and signature is correct.
  11. The payment platform sends the response with request receipt confirmation and validation result to the web service. For more information about the response format, see Response structure.
  12. The payment platform performs the internal payment request processing and forwards the request to the bank service.
  13. The bank processes the purchase.
    Note: If the customer entered credentials of a card that is not registered with the Google Pay service, the payment is performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2.
  14. The bank service sends the payment result notification to the payment platform.
  15. The payment platform sends the callback with the payment result to the web service.
  16. The web service sends the payment result to the customer.

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

The format of the request to the Google Pay service

When performing a purchase by using the Google Pay method through Gate, you need to set up the interaction between your service and the Google Pay service as described in Google Pay Web developer documentation.

In the request to the Google Pay service, along the other objects and parameters, you need to pass the allowedPaymentMethods array consisting of a single JSON object with information about the current payment method. This JSON object must contain the following objects and parameters:

Here is an example of the allowedPaymentMethods array:

"allowedPaymentMethods": [
    {
        "type": "CARD",
        "parameters": {
            "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
            "allowedCardNetworks": ["MASTERCARD", "VISA"]
        },
        "tokenizationSpecification": {
            "type": "PAYMENT_GATEWAY",
            "parameters": {
                "gateway": "jetpay", 
                "gatewayMerchantId": "project_id" // Set the gatewayMerchantId
                                                  // parameter to the project ID
                                                  // you obtained from JetPay
            }
        }
    }
]

Set values of all the parameters as shown in the example above, except for parameters gatewayMerchantId and gateway. Set gatewayMerchantId to the project ID you obtained from JetPay. Ask your account manager what value to use for the gateway parameter.

The format of a request to the JetPay service

There are several things you need to consider when dealing with one-step purchase requests in the Google Pay method:

  1. You initiate a purchase by submitting a purchase request to the /v2/payment/googlepay/sale endpoint by using the HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • general—object with general request identification information:
      • project_id—the project ID you obtained from JetPay
      • payment_id—payment ID unique within the project
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
    • customer—object with customer information:
      • id—the unique ID of the customer within your project
      • ip_address—IP address of the customer's device
      • email—customer email
      • first_name—customer first name
      • last_name—customer last name
    • etoken—object with the token obtained from the Google Pay service after customer authentication:
      • token—token obtained from the Google Pay service after customer authentication
    • payment—object with purchase information:
      • amount—purchase amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.
      • currency—code of purchase currency in the ISO-4217 alpha-3 format
  3. If you need to register the COF purchase, add to the request the recurring object with the register parameter set to true. For more information on how to register the COF purchase through Gate, see Registering COF purchase.
  4. If required, you can add any other additional (optional) parameters Gate supports.

Here is an example of the data from a purchase request in the Google Pay method.

Figure: Example of data from an one-step purchase request with COF purchase registration

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "etoken": {
        "token": "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"
    },
    "recurring": {
        "register": true
    },
    "payment": {
        "amount": 1000000,
        "currency": "KZT"
    }
}

Callback format

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

If the purchase request to the JetPay payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback returned by the JetPay 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 10,000.00 KZT purchase.

Figure: Example of data from a successful purchase callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "auth",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "recurring": {
        "id": 12345
    },
    "operation": {
        "id": 833,
        "type": "sale",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "0",
        "message": "Success",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

Figure: Example of data from a declined purchase callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "auth",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "sale",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "20000",
        "message": "General decline",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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 Google 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 The format of the settlement request to the JetPay service.

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

When opening Payment Page, you can have Payment Page opened with the Google Pay method pre-selected. (For more information about pre-selecting payment methods, see Preselecting payment methods.)

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



Figure: Authorization hold within two-step purchase workflow when using Payment Page

  1. The customer initiates a purchase on the merchant's web service.
  2. The web service sends the request for the Payment Page opening to the JetPay URL.
  3. The request for opening Payment Page is redirected to the payment platform.
  4. The payment platform performs the initial request processing that includes validation whether all the required parameters are available and signature is correct.
  5. The requested Payment Page is generated by the JetPay payment platform as specified in the project settings and request parameters.
    Note: At this point, the payment platform determines the type of the purchase to perform (one-step or two-step purchase) based on the project settings.
  6. Payment Page is displayed to the customer.
  7. The customer selects Google Pay as the payment method.
  8. Payment Page sends the purchase request to the Google Pay service.
  9. The Google Pay service processes the request and generates the payment form.
  10. The Google Pay service displays the payment form to the customer.
  11. The customer chooses one of the cards registered at the Google Pay service. If the customer wants to use another card, they enter its credentials.
    Note: If the customer enters credentials of a card that is not registered with the Google Pay service, the authorization hold will be performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2. With it the value of the method parameter will change from etoken-google to card in the final callback.
  12. The Google Pay service processes the payment.
  13. The Google Pay service sends the purchase token to the Payment Page.
  14. Payment Page sends the request for the authorization hold by using the Google Pay payment method to the JetPay payment platform.
  15. The payment platform performs the internal payment request processing and forwards the request to the bank service.
  16. The bank processes the purchase.
    Note: If the customer entered credentials of a card that is not registered with the Google Pay service, the authorization hold is performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2.
  17. The bank service sends the result notification to the payment platform.
  18. The payment platform sends callback with the result to the web service.
  19. The payment platform sends the result to Payment Page.
  20. The 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 Google Pay payment method and provide the information about format of callbacks with payment results. For the general information about how to use the Payment Page API, see Payment Page API Description.

Request format

There are several things you need to consider when dealing with authorization hold requests in the Google Pay method:

  1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are required for any payment method:
    • project_id—project ID you obtained from JetPay
    • payment_id—payment ID unique within the project
    • customer_id—the unique ID of the customer within your project
    • customer_email—customer email
    • customer_first_name—customer first name
    • customer_last_name—customer last name
    • payment_currency—payment currency in ISO-4217 alpha-3 format
    • payment_amount—payment amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.
  2. If you need to have payment form displayed with the Google Pay method pre-selected, set the force_payment_method parameter to the code on the google_pay_host payment method.
  3. If you need to register the COF purchase, add the recurring parameter 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.

  4. You can also add any other additional parameters Payment Page supports. For more information about parameters supported by Payment Page, see Payment Page invocation parameters.
  5. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign payment requests, see Signature generation and verification.

Here is an example of the data from a request for Payment Page opening:

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

Callback format

The Google Pay method uses the standard format for callbacks to deliver authorization hold result. For more information about callbacks, see Callbacks in Payment Page.

If the purchase request to the JetPay payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback from the JetPay 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 10,000.00 KZT authorization hold.

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "auth",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "recurring": {
        "id": 12345
    },
    "operation": {
        "id": 833,
        "type": "sale",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "0",
        "message": "Success",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "auth",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "sale",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "20000",
        "message": "General decline",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Related topics

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

Two-step purchase by using Gate

General information

In the Google Pay method, the merchant web service is required to do the following when processing a two-step purchase by using Gate:

  1. Send a request for opening the payment form to the Google Pay service.
  2. Accept the callback with the purchase token from the Google Pay service.
  3. Send the request with all the required parameters and signature to the JetPay URL to perform the authorization hold.
  4. Accept the callback with the authorization hold result from the JetPay payment platform.
  5. Send the request with all the required parameters and signature to the JetPay URL to perform the settlement.
  6. Accept the callback with the payment result from the payment platform.
Note: Before performing a two-step purchase by using the Google Pay method through Gate, you need to set up the interaction between your service and the Google Pay service as described in Google Pay Web developer documentation. Make sure you comply with Google Pay Brand Guidelines and follow Google Pay Web integration checklist.

The two-step purchase is performed in two steps:

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

Following diagrams provide the detailed picture of the two-step purchase processing procedure.

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 with Google Pay on the merchant's web service side.
  2. Your web service sends the purchase request to the Google Pay service.
  3. The Google Pay service processes the request and generates the payment form.
  4. Google Pay service displays the payment form to the customer.
  5. The customer chooses one of the cards registered with the Google Pay service. If customer wants to use another card, they enter its credentials.
    Note: If the customer enters credentials of a card that is not registered with the Google Pay service, the authorization hold will be performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2. With it the value of the method parameter will change from etoken-google to card in the final callback.
  6. The Google Pay service processes the request.
  7. The Google Pay service sends the purchase token to your web service.
  8. The web service sends an authorization hold request within the two-step purchase procedure by using Gate to the JetPay URL.
  9. The payment platform receives the authorization hold request from Gate.
  10. The payment platform performs the initial request processing that includes validation whether all the required parameters are available and signature is correct.
  11. The payment platform sends the response with request receipt confirmation and validation result to the web service. For more information about the response format, see Response structure.
  12. The payment platform performs the internal payment request processing and forwards the request to the bank service.
  13. The bank service processes the request.
    Note: If the customer entered credentials of a card that is not registered with the Google Pay service, the authorization hold is performed with the use of the 3-D Secure 2 authentication. For more information, see Authentication by using 3‑D Secure 2.
  14. The bank service sends the authorization hold result notification to the payment platform.
  15. The payment platform sends the callback with the authorization hold result to the web service.
  16. The web service sends the authorization hold result to the customer.

Figure: Step 2. Settlement by using Gate

  1. The web service sends a request for performing the settlement within the two-step purchase by using Gate to the JetPay URL.
  2. The payment platform receives the settlement request from Gate.
  3. The payment platform performs the initial request processing that includes validation whether all the required parameters are available and signature is correct.
  4. The payment platform sends the response with request receipt confirmation and validation result to the web service. 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 the web service.

Figure: Step 2. Removing the authorization hold through Gate

  1. The web service sends a request for removing the authorization hold within the two-step purchase by using Gate to the JetPay 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 includes validation whether all the required parameters are available and signature is correct.
  4. The payment platform sends the response with request receipt confirmation and validation result to the web service. 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 the web service.

The sections that follow discuss in more details the request formats and the Gate parameters to use in the Google Pay payment method and provide the information about the format of callbacks with two-step purchase results. For the general information on how to use the Gate API, see API Description.

The format of the request to the Google Pay service

When performing a purchase by using the Google Pay method through Gate, you need to set up the interaction between your service and the Google Pay service as described in Google Pay Web developer documentation.

In the request to the Google Pay service, along the other objects and parameters, you need to pass the allowedPaymentMethods array consisting of a single JSON object with information about the current payment method. This JSON object must contain the following objects and parameters:

Here is an example of the allowedPaymentMethods array:

"allowedPaymentMethods": [
    {
        "type": "CARD",
        "parameters": {
            "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
            "allowedCardNetworks": ["MASTERCARD", "VISA"]
        },
        "tokenizationSpecification": {
            "type": "PAYMENT_GATEWAY",
            "parameters": {
                "gateway": "jetpay", 
                "gatewayMerchantId": "project_id" // Set the gatewayMerchantId
                                                  // parameter to the project ID
                                                  // you obtained from JetPay
            }
        }
    }
]

Set values of all the parameters according to the example above, except for the gatewayMerchantId parameter. Set gatewayMerchantId to the project ID you obtained from JetPay.

The format of authorization hold request to the JetPay service

There are several things you need to make when dealing with customer's authorization hold requests in the Google Pay method:

  1. Initiate the authorization hold by submitting a request to the /v2/payment/googlepay/auth endpoint by using the HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • general—object with general request identification information:
      • project_id—the project ID you obtained from JetPay
      • payment_id—payment ID unique within the project
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
    • customer—object with customer information:
      • id—the unique ID of the customer within your project
      • ip_address—IP address of the customer's device
      • email—customer email
      • first_name—customer first name
      • last_name—customer last name
    • etoken—object with the token obtained from the Google Pay service after customer authentication:
      • token—token obtained from the Google Pay service after customer authentication
    • payment—object with purchase information:
      • amount—purchase amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.
      • currency—code of purchase currency in the ISO-4217 alpha-3 format
  3. If you need to register the COF purchase, add to the request the recurring object with the register parameter set to true. For more information on how to register the COF purchase through Gate, see Registering COF purchase.
  4. If required, you can add any other additional (optional) parameters Gate supports.

Here is an example of the data from an authorization hold request in the Google Pay method.

Figure: Example of data from an authorization hold request with COF purchase registration

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "etoken": {
        "token": "{\"paymentData\":{...},\"paymentMethod\":{...},\"transactionIdentifier\":\"...\"}"
    },
    "recurring": {
        "register": true
    },
    "payment": {
        "amount": 1000000,
        "currency": "KZT"
    }
}

The format of the settlement request to the JetPay service

Use this request to perform the settlement for the authorization hold previously applied through Payment Page or Gate.

There are several things you need to consider when dealing with the settlement requests in the Google Pay method:

  1. You initiate the settlement by submitting a request to the /v2/payment/googlepay/capture endpoint by using the HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • general—object with general request identification information:
      • project_id—the project ID you obtained from JetPay
      • payment_id—payment ID unique within the project. Specify the payment ID used in the initial authorization hold request.
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
    • payment—object with settlement information:
      • amount—settlement amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency have no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.
      • currency—code of the settlement currency in the ISO-4217 alpha-3 format
  3. If required, you can add any other additional (optional) parameters Gate supports.

Here is an example of the data from a settlement request in the Google Pay method.

Figure: Example of data from a settlement request

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
        "amount": 1000000,
        "currency": "KZT"
    }
}

Request format for removing authorization hold to the JetPay service

Use this request to remove the authorization hold previously applied through Payment Page or Gate.

There are several things you need to consider when dealing with removing authorization hold requests in the Google Pay method:

  1. You initiate removing authorization hold by submitting a request to the /v2/payment/googlepay/cancel endpoint by using the HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • general—object with general request identification information:
      • project_id—the project ID you obtained from JetPay
      • payment_id—payment ID unique within the project. Specify the payment ID used in the initial authorization hold request.
      • 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 add any other additional (optional) parameters Gate supports.

Here is an example of the data from an authorization hold removal request in the Google Pay method.

Figure: Example of data from a request for removing authorization hold 

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    }
}

Callback format

The Google Pay method uses the standard format for callbacks to deliver results of the authorization hold application, settlement, or authorization hold removal. For more information about callbacks, see Callbacks in Gate.

If the purchase request to the JetPay payment platform contains a COF registration parameter and the bank service processes this request successfully, the final callback returned by the JetPay 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 10,000.00 KZT authorization hold.

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "auth",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "recurring": {
        "id": 12345
    },
    "operation": {
        "id": 833,
        "type": "sale",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "0",
        "message": "Success",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 31,
        "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": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 15923,
            "payment_id": "0cf4215c-8978",
            "auth_code": ""
        }
    },
    "signature": "J7W15rkqrLzTCD4HkoM4qoEnlVlfqz8155QSlXJKR4m8C4z2iFYv58P4VnHANu445/jmY+g=="
}

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "capture",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "0",
        "message": "Success",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "awaiting_capture",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "capture",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "20000",
        "message": "General decline",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "canceled",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "cancel",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "0",
        "message": "Success",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "awaiting_capture",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "cancel",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "20000",
        "message": "General decline",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Related topics

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

Two-step purchase by using Dashboard

Dashboard allows merchants to manage authorization holds while performing two-step purchases. The authorization hold can be settled (captured) or removed (released).

To settle (in other words, to remove the authorization hold) you need to:

  1. Find the purchase with authorization hold to settle.
  2. Open the payment details tab for the purchase.
  3. Send a capture (settlement) or cancel (authorization removal) request by following these steps:
    1. Click the Capture button to initiate the settlement. (Alternatively, you can click Cancel to remove the authorization hold.)
    2. In the window that opens, specify the total amount of the authorization hold.
    3. Click Capture to complete the operation.
      Note: Disabled Capture and Cancel buttons mean that one the corresponding operation is already being performed. If either of the buttons is missing altogether, then the corresponding operation is not available for the payment.
  4. Make sure that the capture (or, alternatively, cancel) operation is completed.

    If the operation request is declined, its status switches to decline while the payment status remains awaiting capture.

For more information about using Dashboard for managing authorization holds in two-step purchases, see Performing purchases through Dashboard.

COF purchase by using Gate

General information

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 format sections of the topics about one-step and two-step purchases.

In the Google Pay method, the merchant web service 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 signature to the JetPay 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 procedure 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 the merchant's web service side. This step is optional.
  2. The web service sends a request for processing the COF payment by using Gate to the JetPay 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 signature is correct.
  5. The payment platform sends the response with request receipt confirmation and validation result to the web service. 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 the web service.
  10. The web service sends the payment result to the customer.

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

Request format

There are several things you need to consider when generating a COF payment request in the Google Pay method:

  1. You initiate a COF payment by submitting a request to the /v2/payment/googlepay/recurring endpoint by using the HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • general—object with general request identification information:
      • project_id—the project ID you obtained from JetPay
      • payment_id—payment ID unique within the project
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
    • customer—object with customer information:
      • id—the unique ID of the customer within your project
      • ip_address—IP address of the customer's device
      • email—customer email
      • first_name—customer first name
      • last_name—customer last name
    • recurring—object with registered COF purchase information:
      • id—COF purchase identifier
    • payment—object with purchase information:
      • amount—purchase amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.
      • currency—code of purchase currency in the ISO-4217 alpha-3 format
  3. If required, you can add any other additional (optional) parameters Gate supports.

Here is an example of the data from a request for a COF payment in the Google Pay method.

Figure: Example of the data from a COF payment request

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "recurring": {
        "id": 12345
    },
    "payment": {
        "amount": 1000000,
        "currency": "KZT"
    }
}

Callback format

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

The following is an example of a callback with information about a successful 10,000.00 KZT COF payment.

Figure: Example of data from a successful COF payment callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "recurring",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "recurring",
        "status": "success",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "0",
        "message": "Success",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

Figure: Example of data from a declined purchase callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "recurring",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "method": "etoken-google",
        "sum": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "411111******1111"
    },
    "operation": {
        "id": 833,
        "type": "recurring",
        "status": "decline",
        "date": "2023-03-02T09:13:10+0000",
        "created_date": "2023-03-02T09:12:00+0000",
        "code": "20000",
        "message": "General decline",
        "sum_initial": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "KZT"
        },
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        },
        "request_id": "dabb4660eb711f3774a70a8"
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Related topics

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

Refund by using Gate

General information

In the Google Pay method, the merchant web service is required to do the following when processing a refund by using Gate:

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

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



Figure: Refund sequence by using Gate

  1. The customer initiates a refund with Google Pay on the merchant's web service side.
  2. The web service sends a request for processing the refund by using Gate to the JetPay URL.
  3. The payment platform receives the request for processing the refund from Gate.
  4. The payment platform performs the initial request processing that includes validation whether all the required parameters are available and signature is correct.
  5. The payment platform sends the response with the request receipt confirmation and validation result to the web service. For more information about the response format, see Response structure.
  6. The payment platform performs further refund request processing and redirects the request to the provider service.
  7. The provider service processes the refund request.
  8. The provider service sends the refund result notification to the payment platform.
  9. The payment platform sends a callback with the refund result to the web service.
  10. The web service sends the refund result to the customer.

The sections that follow discuss in more details the refund format and the Gate parameters to use in the Google Pay payment method and provide the information about the format of callbacks with refund result. For the general information on how to use the Gate API, see API Description.

Request

There are several things you need to consider when dealing with refund requests in the Google Pay method:

  1. You initiate a refund by sending a request to the /v2/payment/googlepay/refund endpoint by using the HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • general—object with general request identification information:
      • project_id—the project ID you obtained from JetPay
      • payment_id—payment ID unique within the project
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
    • customer—object with customer information:
      • id—the unique ID of the customer within your project
      • ip_address—IP address of the customer's device
      • first_name—customer first name
      • last_name—customer last name
      • email—customer email
    • payment—object with refund information:
      • description—comment or description
      • amount—refund amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units (required only for partial refund). If the currency have no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes. This parameter is required only when performing a partial refund.
      • currency—code of refund currency in the ISO-4217 alpha-3 format. This parameter is required only when performing a partial refund.
  3. If required, you can add any other additional (optional) parameters Gate supports.

Here is an example of the data from a refund request in the Google Pay method.

Figure: Example of the data from a refund request 

{ 
    "general": { 
        "project_id": 1234, 
        "payment_id": "payment_47", 
        "signature": "vVDlp9QFbU76c5Hb2sofs4kypzZtGwJW6+y1CN3AIrirtsTaXXBQvnHxp7j3E1zdmg==" 
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": { 
        "description": "Refund description",
        "amount": 1000000, 
        "currency": "KZT"
    } 
}

Callback format

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

The following is the example of a callback with information about a successful 10,000.00 KZT refund.

Figure: Example of the data from a successful refund callback

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "refunded",
            "date": "20201-09-09T10:02:18+0000",
            "method": "etoken-google",
            "sum": {
                "amount": 0,
                "currency": "KZT"
            },
            "description": "Refund description"
        },
        "operation": {
            "id": 12345677654321,
            "type": "refund",
            "status": "success",
            "date": "2021-09-09T10:02:18+0000",
            "created_date": "2021-09-09T09:46:14+0000",
            "request_id": "6b77b588d77d5c27be31be7b72bf9adf...b1c85eda238b73cac-00090267",
            "sum_initial": {
                "amount": 1000000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 1000000,
                "currency": "KZT"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12345,
                "payment_id": "123abc123-321",
                "auth_code": ""
            }
        },
        "signature": "WUZUy26FHZglsro9PYFr89suJAciQ...5Fev4NtHl56VGTgX9m/g=="
    }

The following is the example of a callback for a declined refund.

Figure: Example of the data from a declined refund callback

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "success",
            "date": "2021-09-09T10:02:18+0000",
            "method": "etoken-google",
            "sum": {
                "amount": 1000000,
                "currency": "KZT"
            },
            "description": "Refund description"
        },
        "operation": {
            "id": 12345677654321,
            "type": "refund",
            "status": "decline",
            "date": "2021-09-09T10:02:18+0000",
            "created_date": "2021-09-09T09:46:14+0000",
            "request_id": "6b77b588d77d5c27be31be7b72bf9adf...b1c85eda238b73cac-00090268",
            "sum_initial": {
                "amount": 1000000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 1000000,
                "currency": "KZT"
            },
            "code": "20000",
            "message": "General decline"
            }
        },
        "signature": "WUZUy26FHZglsro9PYFr89suJAciQ...5Fev4NtHl56VGTgX9m/g=="
    }

Related topics

Analysis of payments results

As with other payment methods JetPay 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.jetpay.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 JetPay technical support.