Integration
Credit Card
Direct Debit
Bluecode
eps
giropay
iDEAL
Maestro
PayPal
Payment Page
Tools
Error codes
Result codes
Test data
This is an old revision of the document!
This document describes all flows and interfaces that are required for an integration of the GiroCheckout Payment Page.
This payment page allows for a much simpler integration of shops with GiroCheckout, without the need to configure each payment method separately within the shop. The GiroCheckout Payment Page offers the customer all payment methods available to the merchant for selection and then initializes the selected payment accordingly.
Example
The following payment methods are currently supported:
A payment page needs to be initialized so that a URL to the payment page can be generated. This payment page URL is the result of a successful payment page initialization. The customer must be redirected to this URL afterwards.
Provided by: GiroCheckout
Called by: Merchant
In case you have the requirement of only offering in your payment or donation page payment methods associated to certain projects in your GiroCockpit, and letting someone choose these methods programmatically, you may use this request to obtain a list of all your projects.
URL: https://payment.girosolution.de/girocheckout/api/v2/paypage/projects
Provided by: GiroSolution
Called by: Merchant
Name | Mandatory | Type | Description |
---|---|---|---|
merchantId | Yes | Integer | Merchant ID of a Paypage project |
projectId | Yes | Integer | Project ID of a Paypage project |
hash | Yes | String | HMAC MD5 hash of all the parameter values in the call. See hash generation |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \ https://payment.girosolution.de/girocheckout/api/v2/paypage/projects
The response consists of a JSON object. The field rc returns an error code. If rc = 0 is returned, the call was successful. In the response, you receive the element “projects” that contains the available projects.
Name | Mandatory | Type | Description |
---|---|---|---|
rc | Yes | Integer | Error codes |
msg | Yes | String | Additional information in case of an error |
projects | Optional | Array | List of the GiroCockpit projects with the elements Project Id (id), Projekt name (name), the number of the corresponding payment method (paymethod, see Payment methods) and the mode (mode) = TEST or LIVE. |
HEADER Parameters | |||
hash | Yes | String | HMAC MD5 hash of all values of the response. See hash on response |
{"projects":[{"id":"12345","name":"iDEAL - ICEPAY","paymethod":"12","mode":"LIVE"},{"id":"12346","name":"giropay","paymethod":"1","mode":"TEST"},{"id":"12347","name":"Kreditkarte","paymethod":"11","mode":"TEST"}],"rc":0,"msg":""}
URL https://payment.girosolution.de/girocheckout/api/v2/paypage/init
Name | Mandatory | Type | Description |
---|---|---|---|
merchantId | Yes | Integer | Merchant ID of a Paypage project |
projectId | Yes | Integer | Project ID of a Paypage project |
merchantTxId | Yes | String(255) | Merchant's unique transaction ID |
amount | Yes | Integer | For currencies with decimals, specify the amount in the smallest currency unit, such as Cent, Penny |
currency | Yes | String(3) | Currency of the transaction, according to ISO 4217. EUR = Euro |
purpose | Yes | String(20) | Purpose of the transaction. This information is displayed on the card settlement or bank statement. Only SEPA compliant characters are allowed (see SEPA compliant characters). If pagetype=2 and projectlist is not empty, the placeholder {SPENDENPROJEKT} may be used, which is then filled with the name of the user-selected project. The content of this field (first 20 characters) is also used to fill the orderid in case of the payment method Paydirekt, if it is not explicitly specified (see parameter orderid). |
description | Optional | String(120) | Description for the payment. Is only displayed on the payment page. Allowed characters see Allowed description characters |
pagetype | Optional | Integer | Type of the payment page to be generated: 0=normal API-Paypage (compatible to previous paymnent pages, default), 1=Payment page, 2=Donation page |
expirydate | Optional | String(10) | Expiration date: Empty=payment page is always valid, 'once'=payment page may only be used for one successful payment, afterwards it will be invalidated, YYYY-MM-DD=Date in format Year-Month-Day, payment page will be valid up to this date. |
type | Optional | String(4) | Transaction type (see Transaction types) SALE = Immediate payment (default) AUTH = Amount reservation (not available for all payment methods) |
locale | Optional | String(4) | Language of the payment page de = German (default) en = English |
paymethods | Optional | String | Comma-separated list of the payment methods to be offered. If parameter is empty or not specified, all methods enabled by the merchant in GiroCockpit will be displayed. Specify each payment method as a number, see Payment methods |
payprojects | Optional | String | Comma-separated list of the project IDs, whose payment methods are to be available on the payment page. If nothing is specified here, all projects of the merchant are used. The project IDs may either be obtained manually through GiroCockpit, or programatically via a call to the function Project Request. |
organization | Optional | String(70) | Name of the organization offering the payment or donation page. If none specified, the merchant name from GiroCockpit is used. |
freeamount | Optional | Integer | Defines whether the payment page user may freely enter an amount (=1) or not (=0, default). |
fixedvalues | Optional | String | JSON-encoded string that contains an array of all the amounts among which the user may select the one to be paid/donated, e.g. '[“10000”,“20000”,“50050”]', all amounts are to be specified in cents. If this field is empty, the content of the amount field is used as a only possible value. If this field contains values, the amount field is ignored! |
minamount | Optional | Integer | Minimum accepted value if free amount entry is allowed, i.e. freeamount=1. If this value is omitted, the default is 100 (meaning 1,00). Amount specified in cents. |
maxamount | Optional | Integer | Maximum accepted value if free amount entry is allowed, i.e. freeamount=1. |
orderid | Optional | String(20) | Only used when payment method is Paydirekt. If empty, the orderid is generated from the purpose field. Only sepa-compliant characters are allowed (see SEPA-compliant characters) |
projectlist | Optional | String | JSON-encoded string, that contains an array of projects (strings=project names), for which the donation page accepts donations. Only makes sense if pagetype=2. |
pkn | Optional | String | This field allows the initialization of a new transaction without having to input the credit card or direct debit data again (recurring payments). create = generate new pseudo card number for the payment data (credit card or bank data) used in this transaction. |
test | Yes | Integer | 1 = Display payment methods that are in test mode 0 = Display payment methods that are in Live mode |
successUrl | Optional | String | URL where the customer is redirected to after successful payment. |
backUrl | Optional | String | URL where the customer is redirected to after clicking the Back button. |
failUrl | Optional | String | URL where the customer is redirected to after a failed payment. |
notifyUrl | Optional | String | URL where the payment notification is sent to via server to server communication. |
hash | Yes | String | HMAC MD5 hash of all the parameter values in the call. See hash generation |
In SEPA payments, according to Annex 3 of this document, only characters of the limited SWIFT Latin characters set are allowed:
The following characters are allowed in the description text (field description):
These are the allowed values for the payment methods specified in the parameter paymethods:
ID | Payment method |
---|---|
1 | giropay |
2 | eps |
6 | direct debit |
7 | direct debit with block file |
8 | direct debit with guarantee |
11 | credit card |
12 | iDEAL |
14 | PayPal |
23 | paydirekt |
27 | Sofort. |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=100" \ -d "currency=EUR" \ -d "purpose=Beispieltransaktion" \ -d "description=Fahrradleuchte klein" \ -d "type=SALE" \ -d "locale=de" \ -d "paymethods=1,2,6,11,14" \ -d "test=1" \ -d "successUrl=http://www.my-domain.de/girocheckout/success" \ -d "backUrl=http://www.my-domain.de/girocheckout/back" \ -d "failUrl=http://www.my-domain.de/girocheckout/fail" \ -d "notifyUrl=http://www.my-domain.de/girocheckout/notify" \ -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \ https://payment.girosolution.de/girocheckout/api/v2/paypage/init
The response consists of a JSON object. The field rc returns an error code. If rc = 0 is returned, the transaction was successfully initialized. As a response, you receive a reference number for the payment page and the redirect URL that leads to the form.
Name | Mandatory | Type | Description |
---|---|---|---|
rc | Yes | Integer | Error codes |
msg | Yes | String | Additional information in case of an error |
reference | Optional | String | Unique payment page ID |
url | Optional | String | URL to the payment page, that the customer is to be redirected to. |
HEADER Parameters | |||
hash | Yes | String | HMAC MD5 hash of all values of the response. See hash on response |
hash : 6c4da0504e8e6a359c7f2df86cb5318d
{"reference":"4f88b6c8-6209-4c96-a450-b6de22633f6b","url":"http:\/\/pay.girosolution.de\/v1\/paypage\/en\/EG-ddvXSrAHmXRClBeamKGAyzXU-uAYbNYFLQ3uz_zj_J4rYCb0GIrWIQ-H_g8h3_-yf3WvSenh2Dg6TLhmTAA","rc":0,"msg":""}
hash : f55ce87e132ebb7eb20004c6b186ce09
{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}
The result of a transaction is transmitted to the URL specified in the parameter notifyUrl. This notification is used to inform the merchant about the result of the transaction, who can use this information to update his transaction status in the shop. The result of the transaction can be found in the field gcResultPayment.
URL: notifyUrl from the payment page initialization
Provided by: Merchant
Called by: GiroCheckout
Method: POST
Name | Mandatory | Type | Description |
---|---|---|---|
gcPaymethod | Yes | Integer | ID of the payment method of the transaction |
gcType | Yes | String | Transaction type: SALE AUTH |
gcProjectId | Yes | String | GiroCheckout project ID used for the transaction. |
gcReference | Yes | String | GiroCheckout transaction ID |
gcMerchantTxId | Yes | String | Merchant transaction ID |
gcBackendTxId | Yes | String | Payment processor transaction ID |
gcAmount | Yes | Integer | For currencies with decimals, specify the amount in the smallest currency unit, such as Cent, Penny |
gcCurrency | Yes | String | Currency |
gcResultPayment | Yes | Integer | Payment result codes |
gcPkn | Optional | String | Pseudo card number if pkn is active |
gcCardnumber | Optional | String | Masked credit card number if pkn is active |
gcCardExpDate | Optional | String | Credit card expiration date in the format month/year if pkn is active |
gcAccountHolder | Optional | String | Account holder for direct debit if pkn is active |
gcIban | Optional | String | IBAN for direct debit if pkn is active |
gcHash | Yes | String | HMAC MD5 hash on all values of the call. See hash generation |
Der zweite Kommunikationsweg ist die Rückleitung des Käufers in seinem Browser auf eine der drei bei der Initialisierung angegebenen Weiterleitungsadressen:
* successUrl: Hierher wird weitergeleitet, wenn die Zahlung erfolgreich war. * failUrl: Hierher wird weitergeleitet, wenn die Zahlung nicht erfolgreich war. * backUrl: Hierher wird weitergeleitet, wenn der Käufer auf den Zahlungsseiten beschließt, den Vorgang abzubrechen und auf den entsprechenden Button klickt.
Alle 3 URLs werden mit der POST-Methode aufgerufen und erhalten als Parameter die selben Werte wie oben beim Notify angegeben.