User Tools

Site Tools


Translations of this page:
en:girocheckout:googlepay:start

Google Pay

Google Pay is a mobile payment service developed by Google that allows users to make contactless payments in stores, online, and within apps using their Android phones, tablets, or watches. It enables users to store payment information securely in their Google Account, facilitating faster and easier transactions.

Test Data

You do not need any test data to test Google Pay. You do need a valid Google Account to use for the payment.

Transaction Types

Detailed information about transaction types.

Google Pay allows:

  • Sales (SALE) - direct payments without prior reservation.
  • Authorizations (AUTH), also called Pre-Authorization, to reserve an amount upfront and charge it later either fully or partially.
  • Capture - charging a previously authorized amount, where Google Pay also allows partial captures that must not exceed the full authorized amount. Only one capture is permitted, whether for the full or partial amount.
    Example: Authorization for 20.00 EUR, 1 Capture for 5.00 EUR OR 1 Capture for 20.00 EUR. Additional captures are not allowed.
    Generally, the full authorized amount doesn't need to be captured. Any remaining amount can be released via Void.
  • Void or Reversal (cancellation) - releases a reserved amount or remaining balance so it becomes available to the customer again. As shown in the Capture example, partial release of the authorized amount is possible.
  • Refund - allows returning a charged amount or partial amount to the customer. Like with Capture, partial refunds are possible but only once. The refund amount must not exceed the original transaction amount. Authorizations cannot be refunded, only voided.

Authorization (AUTH)

A reservation is to be used when the actual fulfillment of an order takes place at a later time, but the order amount for the presented card (for credit card transactions) or the given account information (for Paydirekt payments and others) needs to be authorized beforehand at the time of the order. Once the reservation period has expired, the reservation is either booked or voided.

  • initial Transaction

AUTHCAPTUREVOIDREFUND

Sale (SALE)

Use sale when the business case is complete, e.g. a shopping cart was offered, ordered and delivered to the customer. The customer's payment method is debited with the amount of the sale.

  • initial Transaction

SALEREFUND

Initializing a Google Pay Payment

Successful initialization creates a reference number and provides the merchant with a redirect link to the payment form. The customer must be redirected to this URL, which can be done via HTTP redirect header, HTML page with meta tag, or JavaScript.

Provided by: GiroCheckout
Called by: Merchant

Workflow

CustomerShopGiroCheckoutData CenterCustomerShopGiroCheckoutData Center1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 (c)2025 by S-Management Service GmbH

  1. Buyer selects Google Pay as payment method
  2. Shop initiates Google Pay transaction (Initialization)
  3. GiroCheckout initializes transaction with data center
  4. Data center sends result to GiroCheckout
  5. Shop receives initialization result (transaction ends if error occurs)
  6. Shop sends redirect URL to customer browser
  7. Customer browser redirects to data center
  8. Data center displays payment form
  9. Customer authorizes transaction
  10. Data center processes transaction
  11. Data center sends result to GiroCheckout
  12. Notification: GiroCheckout informs shop about transaction outcome (Notification)
  13. Notification: Shop processes transaction result
  14. Notification: Shop sends HTTP status code to GiroCheckout
  15. Customer clicks “Back to Shop” at data center or waits for automatic redirect (Redirect)
  16. GiroCheckout redirects customer back to shop

API Functions

Overview

As seen in the workflow, different API calls occur during a Google Pay transaction. The form that the customer completes after redirection to the data center is partially provided by the data center and partially by Google Pay, and may vary in content and flow depending on browser and device.

  1. Initialize transaction
  2. Customer completes Google Pay forms
  3. Notification of payment result to merchant
  4. Redirecting customer back to merchant pages (triggered by customer or automatic)

Authorization/Sale

POST Parameters

URL https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Name Required Type Description
merchantId Yes Integer Merchant ID of a Google Pay project
projectId Yes Integer Project ID of a Google Pay project
merchantTxId Yes String(255) Unique merchant transaction ID. Allowed characters: any letters (including language-specific special characters), 0-9, characters & = + , : ; . _ ! ? # /. GiroCheckout passes this information to Google Pay via the merchant_information.merchant_data_1 field.
amount Yes Integer For decimal currencies, specify amount in smallest currency unit, e.g., cents, pennies
currency Yes String(3) Transaction currency per ISO 4217.
EUR = Euro
purpose Yes String(40) Transaction purpose. Since Google Pay doesn't natively have this field, GiroCheckout stores the information under basket.soft_descriptor if not provided by the shop.
type Optional String(4) Transaction type (see Transaction types)
SALE = Immediate sale (default)
AUTH = Amount reservation
urlNotify Yes String(2048)URL to notify payment outcome.
urlRedirect Yes String(2048)URL to redirect customer after payment.
billingAddress Optional JSON-String Optional field containing buyer's billing address. For individual fields, see listing below.
shippingAddress Optional JSON-String Optional field containing buyer's shipping address. If missing, billing address will be used as shipping address. For individual fields, see listing below.
customerInfo Optional JSON-String Optional field containing additional customer information. For individual fields, see listing below.
basket Yes JSON-String Required field describing the shopping basket. For individual fields, see listing below.
kassenzeichen Optional String(255)Optional field for passing a cash register identifier. This will be displayed in GiroCockpit transaction details (and soon exportable) and can be searched for there. All UTF-8 characters allowed.
hash Yes String(32)HMAC MD5 hash over all call values. See generate hash

JSON Object for Addresses

This object structure applies to both the billing address (billingAddress) and the shipping address (shippingAddress).

Name Required Type Description
first_name Yes String(50) First name of the billing recipient.
last_name Yes String(50) Last name of the billing recipient.
title No String(20) Google Pay interprets “title” as the customer's salutation, e.g., Mr., Mrs., etc.
email Yes String(254) Email address of the billing recipient.
phone_contact No Sub-object Phone number of the billing recipient (see below).
company_name No String(100) Company name if the billing recipient is a company.
address_line_1 Yes String(100) Main street and house number of the billing address.
address_line_2 No String(100) Additional address line of the billing address (optional).
address_line_3 No String(100) Further additional address line of the billing address (optional).
postal_code Yes String(10) Postal code of the billing address.
city Yes String(50) City of the billing address.
state No String(50) State or region of the billing address.
country Yes String(2) Two-letter country code of the billing address (ISO 3166).

phone_contact Object:

Name Required Type Description
phone_type No String(10) Type of phone number: `HOME`, `WORK`, or `MOBILE`.
phone_number No String(20) Phone number of the billing recipient.

JSON Object customerInfo

Name Required Type Description
customer_id No String(50) Unique customer ID.
date_of_birth No String(10) Customer's date of birth in `YYYY-MM-DD` format.
gender No String(10) Customer's gender: `MALE`, `FEMALE`, `DIVERSE`.
title No String(100) Google Pay interprets “title” as the customer's salutation, e.g., Mr., Mrs., etc.
personal_identifications No Sub-object List of identification documents (see below).
contacts No Sub-object List of customer contact methods (see below).

contacts Object:

Within the phone_contacts object, an array with multiple elements containing the following fields can be specified:

Name Required Type Description
phone_type No String(10) Type of phone number: `FAX`, `HOME`, `MOBILE`, `OTHER`, `PAGER`, `WORK`.
phone_number No String(16) Phone number in E.164 format (e.g., `+442071838750`).

personal_identifications Object:

An array with multiple elements containing the following fields can be specified:

Name Required Type Description
type No String(20) Type of identification: `PASSPORT`, `NATIONAL`, `CPF`, `CNPJ`, `CURP`, `SSN`, `DRIVERS_LICENSE`.
id No String(26) Customer's identification number.
issued_by No String(50) For `DRIVERS_LICENSE`: Issuing authority or region; for others: Country (ISO 3166-1 Alpha-2 code).

JSON Object basket

Name Required Type Description
basket_id Yes String(140) Unique basket identifier, e.g., “basket123456”.
invoice_id No String(127) External invoice number of the API caller.
soft_descriptor No String Dynamic text appearing on the buyer's bank statement, e.g., “800-123-1234”. This stores the “purpose” (intended use) if the field is not used otherwise.
shipping_costs see Desc. Sub-object Shipping costs of the shopping cart (see below). This field is mandatory, if basket_type is not “DIGITAL”.
basket_discount No Sub-object Discount on the entire basket (see below).
basket_type Yes String(10) Basket type: `DIGITAL`, `MIXED`, or `PHYSICAL`.

shipping_costs and basket_discount

Name Required Type Description
amount Yes Integer Amount in the smallest currency unit (e.g., cents).
currency Yes String(3) Currency per ISO 4217 (e.g., `EUR`).

basket_items Array:

An array with the following fields:

Name Required Type Description
name Yes String(127) Item name, e.g., “A fine shirt”.
description No String(127) Item description.
reference No String(64) Item number, SKU, or other merchant reference.
quantity Yes Object Item quantity and unit (see below).
unit_price Yes Object Item price details (see below).
item_discount No Object Discounts for this item (see below).

quantity Object:

Name Required Type Description
quantity_amount Yes Integer Number of units purchased.
quantity_unit Yes String(8) Item unit of measure (e.g., `pcs`, `kg`).

unit_price Object:

Name Required Type Description
net Yes Integer Net price of the item in the smallest currency unit.
gross Yes Integer Gross price of the item in the smallest currency unit.
currency Yes String(3) Currency per ISO 4217 (e.g., `EUR`).
tax Yes Integer Tax amount in the smallest currency unit or tax rate (with two decimal places).

item_discount Object:

Name Required Type Description
net No Integer Discount excluding taxes in the smallest currency unit.
gross No Integer Discount including taxes in the smallest currency unit.
currency No String(3) Currency per ISO 4217 (e.g., `EUR`).
tax No Integer Tax amount in the smallest currency unit or tax rate.
Examples of the Above Structures
  basket:
  {
    "basket_id": "basket123456",
    "basket_type": "DIGITAL",
    "basket_items": [
      {
        "name": "Item 1",
        "quantity": {
          "quantity_amount": 3,
          "quantity_unit": "pcs"
        },
        "unit_price": {
          "net": 500,
          "gross": 600,
          "currency": "EUR",
          "tax": 2000
        }
      }
    ]
  }
  
  billing_address: 
  {
    "title": "Mr.",
    "first_name": "Max",
    "last_name": "Mustermann",
    "company_name": "Acme GmbH",
    "email": "maxi.muster@example.com",
    "phone_contact": {
      "phone_type": "MOBILE",
      "phone_number": "+491701234567"
    },
    "address_line_1": "Mustergasse 123",
    "address_line_2": "Building A",
    "address_line_3": "Apartment 12",
    "postal_code": "88888",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE"
  }
  
  shipping_address: 
  {
    "title": "Mr.",
    "first_name": "Max",
    "last_name": "Mustermann",
    "company_name": "Acme GmbH",
    "email": "maxi.muster@example.com",
    "phone_contact": {
      "phone_type": "HOME",
      "phone_number": "+49755283492987"
    },
    "address_line_1": "Musterstr. 1a",
    "postal_code": "88888",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE"
  }
  
  customer_information: 
  {
    "customer_id": "CUST123456",
    "date_of_birth": "1985-06-15",
    "gender": "MALE",
    "title": "Mr.",
    "personal_identifications": [
      {
        "type": "PASSPORT",
        "id": "A1234567",
        "issued_by": "DE"
      },
      {
        "type": "DRIVERS_LICENSE",
        "id": "DL78901234",
        "issued_by": "Bavarian Ministry of Transport"
      }
    ],
    "contacts": {
      "phone_contacts": [
        {
          "phone_type": "HOME",
          "phone_number": "+442071838750"
        }
      ]
    }
  }
}

Example of Transaction Initialization

curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=1000" \
     -d "currency=EUR" \
     -d "purpose=Sample payment" \
     -d "basket={\"basket_items\":[{\"name\":\"Item 1\",\"quantity\":{\"quantity_amount\":1,\"quantity_unit\":\"pcs\"},\"unit_price\":{\"net\":1000,\"gross\":1200,\"currency\":\"EUR\",\"tax\":2000}}]}" \
     -d "urlRedirect=http://www.my-domain.de/googlepay/redirect" \
     -d "urlNotify=http://www.my-domain.de/googlepay/notify" \
     -d "hash=2ddc45c15307201dca8a50a094c70ab9" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Response

The response consists of a JSON object. The `rc` field returns an error code. If `rc = 0` is returned, the transaction was successfully initialized. You will receive a transaction number and the redirectURL to the Google Pay form in response.

Parameters
Name Required Type Description
rc Yes Integer Error number
msg Yes String(255)Additional information in case of error
reference Optional String(36)Unique GiroCheckout transaction ID
redirect Optional String(2048)Redirect URL to forward the customer to their online banking
HEADER Parameters
hash Yes String(32)HMAC MD5 hash over all values in the response. See response hash.
Success Example
{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/de_DE/R.po?n=iNJGcJ4M2LZASZ-swXO5urRQntxOxb92NFiITsP60GcIhP","rc":"0","msg":""}
Error Example
{"reference":null,"redirect":null,"rc":5030,"msg":"Invalid amount"}

Notification of Payment Outcome

The outcome of a payment is transmitted to the URL specified in the urlNotify parameter. This notification serves to inform the merchant of the transaction outcome. This information can be used to update the transaction status on the merchant side.

The payment outcome of a transaction is indicated in the `gcResultPayment` field.

Request

URL: notifyUrl from transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters

Name Required Type Description
gcReference Yes String(36) GiroCheckout transaction ID
gcMerchantTxId Yes String(255) Merchant transaction ID
gcBackendTxId Yes String(22) Payment processor transaction ID
gcAmount Yes Integer For decimal currencies, the amount in the smallest currency unit, e.g., cents, pennies
gcCurrency Yes String(3) Currency
gcResultPayment Yes Integer Payment result codes
gcHash Yes String(32) HMAC MD5 hash over all values of the call. See generate hash.

Response

The following HTTP status codes are expected as a response to the GET request.

HTTP Status Code Description
200 (OK) The notification was processed correctly.
400 (Bad Request) The merchant did not process the notification but also does not wish to be notified again.
All others The notification will be repeated up to 10 times every 30 minutes until the merchant returns HTTP status code 200 or 400.

Redirecting the Customer Back to the Merchant

After completing the payment, the customer can return to the merchant via a link. The redirection occurs only when the buyer clicks the “Cancel” or “Back to Shop” button or automatically after a few seconds.

Request

URL: redirectUrl from transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters
Name Required Type Description
gcReference Yes String(36) GiroCheckout transaction ID
gcMerchantTxId Yes String(255) Merchant transaction ID
gcBackendTxId Yes String(22) Payment processor transaction ID
gcAmount Yes Integer For decimal currencies, the amount in the smallest currency unit, e.g., cents, pennies
gcCurrency Yes String(3) Currency
gcResultPayment Yes Integer Payment result
gcHash Yes String(32) HMAC MD5 hash over all values of the call. See generate hash.

Additional Transaction Types

These transactions reference a previously completed transaction. The transaction is based on server-to-server communication and does not require customer action (data entry).

Provided by: GiroCheckout
Called by: Merchant

Workflow

ShopGiroCheckoutData CenterShopGiroCheckoutData Center1 2 3 4 (c)2025 by S-Management Service GmbH

  1. Shop sends request with referenced Google Pay transaction
  2. GiroCheckout forwards transaction to data center
  3. Data center transmits result to GiroCheckout
  4. Shop receives direct feedback on transaction outcome (no notification)

Capture

When booking, the customer account is debited with an amount and the merchant account is credited. This model is based on the assumption that the associated business case has been completed, e.g. a shopping cart was offered, ordered and delivered to the customer.

  • Condition: only reserved transactions may be booked
  • Amount ⇐ Reservation amount
  • Partial bookings are possible

Refund

A refund is to be used when a previous payment is to be returned fully or partially to the customer.

  • Condition: may only be applied to the following transaction types:
    • Reservation
    • Reservation/Booking
  • Amount ⇐ Transaction amount of the previous transaction

Void

Void is to be used when an already accepted transaction is not to be executed.

  • Condition: may only be applied to the following transaction types:
    • Reservation (as long as booking has not been done and reservation hasn't expired)
    • Reservation/Booking (only on the same day)
    • Refund (only on the same day)

POST Parameters

URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund
URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Name Required Type Description
merchantId Yes Integer Merchant ID of a Google Pay project
projectId Yes Integer Project ID of a Google Pay project
merchantTxId Yes String(255) Unique merchant transaction ID. Allowed characters: any letters (including language-specific special characters), 0-9, characters & = + , : ; . _ ! ? # /
amount Yes (optional for Void) Integer For decimal currencies, specify the amount in the smallest currency unit, e.g., cents, pennies
currency Yes (optional for Void) String(3) Transaction currency per ISO 4217.
EUR = Euro
purpose Optional String(27) Purpose of the refund or capture. Since Google Pay does not natively have this field, GiroCheckout stores the information under `basket.soft_descriptor` if no information is provided by the shop.
reference Yes String(36) GiroCheckout transaction ID for which a capture or refund should be performed
kassenzeichen Optional String(255) Optional field for passing a cash register identifier. This will be displayed in GiroCockpit in the transaction details (and soon also exported) and can be searched for there.
basket Optional JSON-String Optional field describing the shopping basket. For individual fields, refer to the listing above.
shippingInfo Optional JSON-String Optional field providing shipping information. For individual fields, refer to the listing below.
hash Yes String(32) HMAC MD5 hash over all values of the call. See generate hash.

JSON Object shippingInfo

Name Required Type Description
shipping_company No String Name of the shipping company (as specific as possible).
shipping_method No String Shipping method (e.g., PickUpStore, Home, Postal).
tracking_number No String Tracking number for the shipment.
tracking_uri No String URL for shipment tracking for the customer.
return_shipping_company No String Name of the shipping company for returns.
return_tracking_number No String Tracking number for the return shipment.
shipping_delay No Integer Delay (in days) before shipping the order.
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

Response

The response consists of a JSON object. The `rc` field returns an error code. If `rc = 0` is returned, the transaction was successfully initialized. You will receive a transaction number and further information in response.

Parameters
Name Required Type Description
rc Yes Integer Error number
msg Yes String(255)Additional information in case of error
reference Yes String(36) GiroCheckout transaction ID
referenceParentYes String(36) GiroCheckout transaction ID of the underlying original transaction
merchantTxId Yes String(255) Merchant transaction ID
backendTxId Yes String(22) Payment processor transaction ID
amount Yes Integer For decimal currencies, the amount in the smallest currency unit, e.g., cents, pennies
currency Yes String(3) Currency
resultPayment Yes Integer Transaction result
hash Yes String(32) HMAC MD5 hash over all values of the call. See generate hash.
Success Example
{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/de_DE/R.po?n=iNJGcJ4M2LZASZ-swXO5urRQntxOxb92NFiITsP60GcIhP","rc":"0","msg":""}
Error Example
{"reference":null,"redirect":null,"rc":5030,"msg":"Invalid amount"}
en/girocheckout/googlepay/start.txt · Last modified: 2025/03/31 17:10

Page Tools