User Tools

Site Tools


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

Maestro

Test data

Form field Input value
Card number 6799990100000000019
Expiration date any valid future date
Card verification code (CVC2/CVV) any number of 3 or 4 digits (is not validated)

Please note that Maestro transactions in test mode can only be successful for full amounts without cents. Amounts with cents (such as 19,80 EUR) will always be declined.

Transaction types

Detailed information on the transaction types.

Reservation (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

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

SALEREFUNDVOID

Initialize Maestro payment

After a successful initialization the merchant receives a reference number and a redirect link. The redirect link leads to the payment page. The customer (buyer) must be redirected to this link. This can be achieved by an HTTP redirect header, an HTML page with a corresponding meta tag or a JavaScript redirect.

Provided by: GiroCheckout
Called by: merchant

Workflow

CustomerShopGiroCheckoutCard Processor1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 (c)2017 by GiroSolution AG

  1. Buyer selects payment type “Maestro”
  2. Shop initializes credit card transaction (Initialization)
  3. GiroCheckout initializes transaction at card processor
  4. Card processor transmits result to GiroCheckout
  5. Shop receives response about transaction outcome (transaction ends in case of error)
  6. Shop sends redirect URL to customer browser
  7. Customer browser redirects to card processor
  8. Card processor displays payment form
  9. Customer authorizes transaction
  10. Card processor carries out transaction
  11. Card processor transmits result to GiroCheckout
  12. GiroCheckout notifies Shop about transaction outcome (Notification)
  13. Shop processes transaction outcome
  14. Shop sends HTTP status code to GiroCheckout
  15. GiroCheckout sends merchant redirect (return to merchant page) to card processor
  16. Customer clicks “Back to shop” (Return)

API functions

Overview

As shown in the workflow, different API calls are involved in a Maestro card transaction. During the payment process a 3D-Secure check is usually applied as well, but this depends solely on the card issuing institute and does not affect merchant or PSP in any way.

  1. Initialize transaction
  2. 3D-Secure check (optional)
  3. Payment result notification to merchant
  4. Buyer redirection to the merchant (triggered by buyer)

Reservation/Sale

POST parameters

Name Mandatory Type Description
merchantId yes Integer merchant ID
projectId yes integer project ID
merchantTxId yes String(255) unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency yes String(3) currency
EUR = Euro
purpose yes String(27) purpose
type optional String(4) transaction type (see Transaction types)
SALE = Immediate booking (default)
AUTH = Reservation of amount
locale optional String(4) language of the credit card payment page
de = German (default)
en = English
es = Spanish
fr = French
it = Italian
ja = Japanese
pt = Portuguese
nl = Dutch
cs = Czech
sv = Swedish
da = Danish
pl = Polish
spde = German donation
spen = English donation
de_DE_stadtn = German communes
mobile optional Boolean optimised payment page for mobile devices
0 = no (default)
1 = yes
urlRedirect yes String(2048) URL, where the buyer has to be sent after payment
urlNotify yes String(2048) URL, where the notification has to be sent after payment
kassenzeichen optional String(255) Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there. Characters must comply with the UTF-8 character set.
hash yes String(32) HMAC MD5 hash (see hash generation)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
     -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=9fbd406b72b229a386cd65fc1257c9ad" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialized. The response also includes a transaction id and a redirect URL to the payment page.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) additional information about the response code
reference optional String(36) unique GiroCheckout transaction ID
redirect optional String(2048) redirect URL to the payment page
HEADER parameter
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success

hash : eded41a45961bf87b77a5aaf3e9aeb0e

{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=wrlIRO9O30S4NNAO9h6uHwhyWibDFKUWeoWy7mPLDDyZ","rc":"0","msg":""}
Example in case of error

hash : f55ce87e132ebb7eb20004c6b186ce09

{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

Notification about the payment result

The result of an initialized transaction will be submitted to the merchant through URL specified in the urlNotify parameter. This notification should be used to update the order status in the merchant's system.

The result of the payment is contained in the field gcResultPayment.

Request

URL: notifyUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

GET parameters
Name Mandatory Type Description
gcReference yes String(36) unique GiroCheckout transaction ID
gcMerchantTxId yes String(255) merchant transaction ID
gcBackendTxId yes String(22) payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
gcCurrency yes String(3) currency
gcResultPayment yes Integer Payment result codes
gcHash yes String(32) HMAC MD5 hash (see hash generation)

Reply

As a reply to the GET request, one of the following HTTP status codes is expected.

HTTP status code Description
200 (OK) The notification was processed correctly.
400 (Bad Request) The merchant did not process the notification and does not wish to be notified again.
All others The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400.

Redirection of the customer to merchant

After completing the payment, the customer may return to the merchant through a link. This return only happens once the customer clicks the “cancel” or “return to shop” button and is not done automatically.

Request

URL: redirectUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

GET parameters
Name Mandatory Type Description
gcReference yes String(36) unique GiroCheckout transaction ID
gcMerchantTxId yes String(255) merchant transaction ID
gcBackendTxId yes String(22) payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny
gcCurrency yes String(3) Currency
gcResultPayment yes Integer Payment result codes
gcHash yes String(32) HMAC MD5 hash (see hash generation)

Other transaction types

These transactions reference a previous transaction. They are based on a server to server communication and require no customer interaction (data entry).

Provided by: GiroCheckout
Called by: Merchant

Workflow

ShopGiroCheckoutCard Processor1 2 3 4 (c)2017 by GiroSolution AG

  1. Shop sends reference to previous Maestro transaction
  2. GiroCheckout sends transaction to card processor
  3. Card processor transmits result to GiroCheckout
  4. Shop receives reply on transaction outcome (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

POST Parameters

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

Name Mandatory Type Description
merchantId yes Integer Merchant ID
projectId yes Integer Project ID
merchantTxId yes String(255) Unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount yes Integer If a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny
currency yes String(3) Currency according to ISO 4217.
EUR = Euro
purpose optional String(27) Refund purpose that is printed on the card statement
reference yes String(36) GiroCheckout transaction ID from a previous transaction, which the capture or refund is for
kassenzeichen optional String(255) Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there.
hash yes String(32) HMAC MD5 hash on the complete call. See hash generation
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

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialized. The response also includes a transaction id and other information about the transaction.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) Additional information about the response code
reference yes String(36) Unique GiroCheckout transaction ID
merchantTxId yes String(255) Unique transaction id of the merchant
backendTxId yes String(22) Payment processor transaction ID
amount yes Integer If a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny
currency yes String(3) Currency
resultPayment yes Integer Payment result codes
HEADER parameter
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success

hash : eded41a45961bf87b77a5aaf3e9aeb0e

{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=wrlIRO9O30S4NNAO9h6uHwhyWibDFKUWeoWy7mPLDDyZ","rc":"0","msg":""}
Example in case of error

hash : f55ce87e132ebb7eb20004c6b186ce09

{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}
en/girocheckout/maestro/start.txt · Last modified: 2023/05/08 02:22

Page Tools