Girocheckout API

User Tools

Site Tools

Trace: • Apple Pay

Sidebar

Introduction

Integration

Basics

Apple Pay
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal
WERO

Tools

Error codes
Result codes
Test data

SDK

PHP SDK
Java SDK
.NET SDK

Others

API Change log
Plugins Changelog

Imprint
Privacy policy
S-Public Services GmbH

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

Table of Contents

Apple Pay

Apple Pay is a mobile payment service by Apple that allows users to make secure, contactless payments in stores, apps, and online using their iPhones, iPads, Apple Watches, or Macs.

Currently, Apple Pay is only supported on Safari browsers or Apple devices!

Test Data

To test Apple Pay, you'll need an Apple sandbox account, which we will create for you. During onboarding, please provide us with an email address that is not yet associated with any Apple ID (Apple account), as well as the internet domain from which you wish to perform your tests.

Card Setup Instructions

To set up test cards in your sandbox account mentioned above, please follow these instructions:

Setup Sandbox Cards for Apple Pay (in German)

Apple Pay Test Credit Cards

Remember that you need to add these cards to your sandbox account before you can use them.

Card Type Card Number Expiration Date CVV/CVC
Mastercard 5204 2452 5046 0049 01/30 111
Mastercard 5204 2452 5052 2095 01/30 111
Visa Credit 4051 0693 0220 0121 01/27 340
Visa Credit 4761 2297 0015 0465 01/27 175
Visa Debit 4761 1200 1000 0492 01/27 480
Visa Debit 4761 3497 5001 0326 01/27 982

Transaction Types

Detailed information about transaction types.

Apple 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 Apple 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 an Apple 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 Apple Pay as payment method
  2. Shop initiates Apple 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 an Apple Pay transaction. The form that the customer completes after redirection to the data center is partially provided by the data center and partially by Apple Pay, and may vary in content and flow depending on browser and device.

  1. Initialize transaction
  2. Customer completes Apple 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 an Apple Pay project
projectId Yes Integer Project ID of an Apple 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 Apple 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 Apple 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
urlRedirect Yes String(2048)URL to redirect customer after payment.
urlNotify Yes String(2048)URL to notify payment outcome.
billingAddress Yes JSON-String Mandatory field containing buyer's billing address used for 3D Secure. 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 No String(50) First name of the billing recipient. Allowed are at least two characters consisting of letters (all languages), digits (not exclusively), spaces, the normal hyphen (-), apostrophe, period, as well as the symbols °, º, ª and ᵃ.
last_name No String(50) Last name of the billing recipient. Same format rules as `first_name`.
title No String(20) Apple Pay interprets title as the customer’s salutation (e.g., Mr, Ms, etc.). Allowed are titles up to 20 characters, starting with a letter (all languages), containing only letters/diacritics, spaces, the normal hyphen (-), apostrophe ('/’) and period; it must end with a letter or a period (no digits or other special characters, no leading/trailing separators).
email No String(254) Email address of the billing recipient.
phone_contact No Object Phone number of the billing recipient (see below).
company_name No String(60) Company name, if the billing recipient is a company. Same format rules as `first_name`.
address_line_1 Yes String(60) Street and house number of the billing address. For all 3 street fields: allowed are at least two characters consisting of letters (all languages), digits, spaces, the normal hyphen, apostrophe and accent marks, quotation marks, comma, period, colon and semicolon, hash (#), ampersand (&), slash (/), parentheses, plus and at sign, as well as the symbols °, º, ᵃ, ª and underscore.
address_line_2 No String(60) Additional address line for the billing address (optional). Same format rules as `address_line_1`.
address_line_3 No String(60) Further additional address line for the billing address (optional). Same format rules as `address_line_1`.
postal_code Yes String(10) Postal code of the billing address. Allowed are postal values with 2–10 characters that start and end with a letter or digit and in between may contain only letters, digits, spaces, hyphens, periods, or slashes.
city Yes String(50) City of the billing address. Same format rules as the street fields.
state No String(50) State/region of the billing address. Same format rules as the street fields.
country Yes String(2) Two-letter country code (ISO 3166).

phone_contact object:

Name Required Type Description
phone_type No String(10) Type of phone number: `FAX`, `HOME`, `MOBILE`, `OTHER`, `PAGER`, `WORK`.
phone_number No String(20) Phone number of the billing recipient. Allowed are phone numbers with an optional leading plus sign, followed by a digit 1–9 and up to 14 further digits, optionally grouped by spaces, hyphens, or parentheses, and an optional extension with “ext”, “x”, or “ext.” plus up to five digits.
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 format `YYYY-MM-DD`.
gender No String(10) Customer’s gender: `MALE`, `FEMALE`, `DIVERSE`.
title No String(100) Apple Pay interprets title as the customer’s salutation (e.g., Mr, Ms, etc.). Format rules see `title` in addresses.
personal_identifications No Object List of identification documents (see below).
contacts No Object, see phone_contacts above. List of the customer’s contact options (see below).

contacts object:

Within the element `phone_contacts`, you can provide an array with multiple `phone_contact` elements (see above).

personal_identifications object:

You can provide an array with multiple elements using the following fields:

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 administrative authority or region; for all others: country (ISO 3166-1 alpha-2 code).
JSON object basket
Name Required Type Description
basket_id Yes String(140) Unique identifier of the basket, e.g., “basket123456”. IDs consist of letters/digits and the separators space, normal hyphen (-), underscore (_), and period (.), must not begin or end with a separator, and must not contain double separators/spaces.
invoice_id No String(127) External invoice number of the API caller. Same format rules as `basket_id`.
soft_descriptor No String(27) Dynamic text shown on the buyer’s statement, e.g., “800-123-1234”. The purpose is stored here if the field is not used otherwise. Formatting rules therefore see purpose.
shipping_costs see desc. Object Shipping costs of the basket (see below). This field is required if the `basket_type` is not “DIGITAL”.
basket_discount No Object Discount on the entire basket (see below).
basket_type Yes String(10) Type of basket: `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 according to ISO 4217 (e.g., `EUR`).

basket_items list:

An array with the following fields:

Name Required Type Description
name Yes String(127) Item name, e.g., “A fine shirt”. Same format rules as `first_name` in address.
description No String(127) Item description. Same format rules as `first_name` in address.
reference No String(64) Item number, SKU, or another merchant reference. Same format rules as `basket_id`.
quantity Yes Object Quantity and unit of the item (see below).
unit_price Yes Object Price details for the item (see below).
item_discount No Object Discounts for this item (see below).

quantity object:

Name Required Type Description
quantity_amount Yes Integer Number of purchased units.
quantity_unit Yes String(8) Unit of measure of the item (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 according to 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 tax in the smallest currency unit.
gross No Integer Discount including tax in the smallest currency unit.
currency No String(3) Currency according to 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": "Herr",
    "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": "Haus A",
    "address_line_3": "Wohnung 12",
    "postal_code": "88888",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE"
  }
  
  shipping_address: 
  {
    "title": "Herr",
    "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": "Herr",
    "personal_identifications": [
      {
        "type": "PASSPORT",
        "id": "A1234567",
        "issued_by": "DE"
      },
      {
        "type": "DRIVERS_LICENSE",
        "id": "DL78901234",
        "issued_by": "Bayrisches Verkehrsministerium"
      }
    ],
    "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 transaction" \
     -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/applepay/redirect" \
     -d "urlNotify=http://www.my-domain.de/applepay/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 Apple 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 Apple 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 an Apple Pay project
projectId Yes Integer Project ID of an Apple 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, 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 Apple Pay doesn't natively have this field, GiroCheckout stores the information under basket.soft_descriptor if not 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 exportable) 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/applepay/start.txt · Last modified: 2025/10/08 02:02

Page Tools