Integration
Apple Pay
Bluecode
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal
Tools
Error codes
Result codes
Test data
Apple Pay
Bluecode
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal
Tools
Error codes
Result codes
Test data
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!
You do not need any test data to test Apple Pay. You do require a valid Apple Account, which you will use for the payment.
Detailed information about transaction types.
Apple Pay allows:
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.
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.
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
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.
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 |
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 |
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) | Apple Pay interprets “title” as the customer's salutation, e.g., Mr., Mrs., etc. |
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. |
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) | Apple 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). |
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”. 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. |
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" } ] } } }
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
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.
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. |
{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/de_DE/R.po?n=iNJGcJ4M2LZASZ-swXO5urRQntxOxb92NFiITsP60GcIhP","rc":"0","msg":""}
{"reference":null,"redirect":null,"rc":5030,"msg":"Invalid amount"}
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
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. |
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. |
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
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. |
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
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.
A refund is to be used when a previous payment is to be returned fully or partially to the customer.
Void is to be used when an already accepted transaction is not to be executed.
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. |
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. |
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
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.
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 |
referenceParent | Yes | 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. |
{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/de_DE/R.po?n=iNJGcJ4M2LZASZ-swXO5urRQntxOxb92NFiITsP60GcIhP","rc":"0","msg":""}
{"reference":null,"redirect":null,"rc":5030,"msg":"Invalid amount"}