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!

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.

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

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

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)

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

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

phone_contact Object:

contacts Object:

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

personal_identifications Object:

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

shipping_costs and basket_discount

basket_items Array:

An array with the following fields:

quantity Object:

unit_price Object:

item_discount Object:

  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"
        }
      ]
    }
  }
}

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.

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.

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

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

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.

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

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

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)

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

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.