====== PayPal ====== Information about PayPal payment can be found under https://www.girosolution.de/girocheckout/fuer-haendler/. ===== test data ===== {{page>en:testdata:paypal&noheader&nofooter}} ===== workflow ===== hide footbox participant "buyer" as customer participant "merchant" as shop participant "GiroCheckout" as girocheckout participant "PayPal" as paypal autonumber customer -> shop: shop -> girocheckout: girocheckout -> paypal: paypal -> girocheckout: girocheckout -> shop: shop -> customer: customer -> paypal: paypal -> customer: customer -> paypal paypal -> paypal: paypal -> girocheckout: girocheckout -> shop shop -> shop: shop -> girocheckout: girocheckout -> paypal: paypal -> shop: center footer (c)2013 by GiroSolution AG - buyer chooses PayPal payment method - merchant initialises PayPal transaction ([[en:girocheckout:paypal:start#initialise_paypal_payment|initialising PayPal payment]]) - GiroCheckout initialises transaction at PayPal - PayPal submits response to GiroCheckout - merchant gets response about initialisation (if an issue occurs the transaction is finished) - merchant sends redirect URL to buyer - the buyer's browser redirects buyer to the payment form - PayPal shows payment form - buyer authorises payment - transaction is beeing processed - PayPal submits payment result to GiroCheckout - GiroCheckout notifies merchant about the payment result ([[en:girocheckout:paypal:start#notification_about_the_payment_result|payment result notification]]) - merchant processes result - merchant sends HTTP statuscode to GiroCheckout - GiroCheckout sends merchants redirect page to PayPal - buyer clicks "back to the shop" and gets redirected to the merchant ([[en:girocheckout:paypal:start#redirection_of_the_customer_to_the_merchant|buyer redirection]]) ===== API functions ===== ==== overview ===== As shown in the workflow there are different API calls during a PayPal transaction. - initialise transaction - payment result notification to merchant - buyer redirection to the merchant (triggered by buyer) ==== initialise PayPal payment ==== Torwards a successful initialisation 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 | |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 | |urlRedirect |yes |String |URL, where the buyer has to be sent after payment | |urlNotify |yes |String |URL, where the notification has to be sent after payment | |hash |yes |String |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) | == example == {{page>codesamples:paypal#transactionstart.request&noheader&nofooter}} === reply === The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialised. The response also includes a transaction id and a redirect URL to the payment page. == Parameter == ^name ^mandatory ^type ^description ^ |rc |yes |Integer |[[en:girocheckout:errorcodes|response code]] | |msg |yes |String |additional information about the response code | |reference |optional |String |unique GiroCheckout transaction ID | |redirect |optional |String |redirect URL to the payment page| ^HEADER parameter^^^^ |hash |yes |String |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | == example in case of success == {{page>codesamples:paypal#transactionstart.response.true&noheader&nofooter}} == example in case of error == {{page>codesamples:paypal#transactionstart.response.false&noheader&nofooter}} ==== notification about the payment result ==== The result of an initialised 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 | unique GiroCheckout transaction ID | |gcMerchantTxId |yes | String | merchant transaction ID | |gcBackendTxId |yes |String | 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 | currency | |gcResultPayment |yes |Integer | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| |gcHash |yes |String | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|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 | unique GiroCheckout transaction ID | |gcMerchantTxId |yes | String | merchant transaction ID | |gcBackendTxId |yes |String | 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 | currency | |gcResultPayment |yes |Integer | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| |gcHash |yes |String | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |