User Tools

Site Tools


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

PayPal

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.

Workflow

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

  1. buyer chooses PayPal payment method
  2. merchant initializes PayPal transaction (initializing PayPal payment)
  3. GiroCheckout initializes transaction at PayPal
  4. PayPal submits response to GiroCheckout
  5. merchant gets response about initialization (if an issue occurs the transaction is finished)
  6. merchant sends redirect URL to buyer
  7. the buyer's browser redirects buyer to the payment form
  8. PayPal shows payment form
  9. buyer authorises payment
  10. transaction is beeing processed
  11. PayPal submits payment result to GiroCheckout
  12. GiroCheckout notifies merchant about the payment result (payment result notification)
  13. merchant processes result
  14. merchant sends HTTP statuscode to GiroCheckout
  15. GiroCheckout sends merchants redirect page to PayPal
  16. buyer clicks “back to the shop” and gets redirected to the merchant (buyer redirection)

API functions

Overview

As shown in the workflow there are different API calls during a PayPal transaction.

  1. Initialize transaction
  2. Payment result notification to merchant
  3. Buyer redirection to the merchant (triggered by buyer)

Initialize PayPal payment

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.

Request

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
provided by: GiroCheckout
called by: merchant

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
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=19a1f2dae3e6fccc37ea29e025ebfb1a" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Reply

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.

Parameter
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)
Example in case of success

hash : 43bcc298c042d657506c25bd90812750

{"reference":"a79985f0-004e-4823-9de4-54fcb45fab37","redirect":"https://payment.girosolution.de/payment/services/paypal/simulate/1196312","rc":"0","msg":""}
Example in case of error

hash : f826b7b320bf0115722cc3276319b0a8

{"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 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.

Request

URL: notifyUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameter
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)

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 the merchant

After completing the payment, the customer may return to the merchant through a link. This return is not done automatically.

Request

URL: redirectUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameter
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)

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

ShopGiroCheckoutCredit Card Processor1 2 3 4 (c)2016 by GiroSolution AG

  1. Shop sends reference to previous credit card transaction
  2. GiroCheckout sends transaction to credit card processor
  3. credit 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
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
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
{"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":""}
Example in case of error
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":"5200","rc":0,"msg":"Transaktion nicht akzeptiert"}
en/girocheckout/paypal/start.txt · Last modified: 2023/05/08 04:17

Page Tools