Integration
Credit Card
Direct Debit
Bluecode
eps
giropay
iDEAL
Maestro
PayPal
Payment Page
Tools
Error codes
Result codes
Test data
Sidebar
de
enen:girocheckout:maestro:start
Table of Contents
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
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
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
- Buyer selects payment type “Maestro”
- Shop initializes credit card transaction (Initialization)
- GiroCheckout initializes transaction at card processor
- Card processor transmits result to GiroCheckout
- Shop receives response about transaction outcome (transaction ends in case of error)
- Shop sends redirect URL to customer browser
- Customer browser redirects to card processor
- Card processor displays payment form
- Customer authorizes transaction
- Card processor carries out transaction
- Card processor transmits result to GiroCheckout
- GiroCheckout notifies Shop about transaction outcome (Notification)
- Shop processes transaction outcome
- Shop sends HTTP status code to GiroCheckout
- GiroCheckout sends merchant redirect (return to merchant page) to card processor
- 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.
- Initialize transaction
- 3D-Secure check (optional)
- Payment result notification to merchant
- 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
- Shop sends reference to previous Maestro transaction
- GiroCheckout sends transaction to card processor
- Card processor transmits result to GiroCheckout
- 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