Integration
Credit Card
Direct Debit
Bluecode
eps
giropay
iDEAL
Maestro
PayPal
Payment Page
Tools
Error codes
Result codes
Test data
For testing purpose there runs a PayPal simulation page. After initialisation of a PayPal payment the buyer is redirected to a simulation page. There can be chosen if the transaction should be finished successfully or unsuccessfully.
Transaktionsausgang
result code | answer type | description |
---|---|---|
4000 | successful transaction | The payment result can be chosen in the simulation page. |
4900 | unsuccessful transaction | The payment result can be chosen in the simulation page. |
As shown in the workflow there are different API calls during a PayPal transaction.
Towards a successful initialization you receive a reference number and an redirect link. The redirect link leads to the payment page of PayPal. He has to be redirected. This can be achieved by a HTTP-Redirect-Header, HTML page with a corresponding Meta-Tag or JavaScript redirect.
URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
provided by: GiroCheckout
called by: merchant
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 |
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) |
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=19a1f2dae3e6fccc37ea29e025ebfb1a" \ https://payment.girosolution.de/girocheckout/api/v2/transaction/start
The reply includes 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.
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(255) | redirect URL to the payment page |
HEADER parameter | |||
hash | yes | String(32) | HMAC MD5 hash overall the JSON string. (see api call reply) |
hash : 43bcc298c042d657506c25bd90812750
{"reference":"a79985f0-004e-4823-9de4-54fcb45fab37","redirect":"https://payment.girosolution.de/payment/services/paypal/simulate/1196312","rc":"0","msg":""}
hash : f826b7b320bf0115722cc3276319b0a8
{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}
The result of an initialized transaction will be submitted to the prior in the urlNotify parameter specified URL. This notification should be used to update the payment status in the merchant's system. The result of the payment is contained in the field gcResultPayment.
URL: notifyUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout
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 is 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) |
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. |
After completing the payment, the customer may return to the merchant through a link. This return is not done automatically.
URL: redirectUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout
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 is 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) |
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
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.
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 |
reference | yes | String(36) | GiroCheckout transaction ID from a previous transaction, which the capture or refund is for |
purpose | optional | String(27) | Purpose of the refund or capture. This information is printed on the credit card statement. |
kassenzeichen | optional | String(255) | (Capture only) 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 |
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 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.
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) |
{"reference":"7f18859d-7246-4181-8fb5-30ce7958f309","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1196307_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":"5200","rc":0,"msg":"Transaktion nicht akzeptiert"}