Girocheckout API

User Tools

Site Tools

Trace:
en:girocheckout:paypal:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
Last revision Both sides next revision
en:girocheckout:paypal:start [2014/10/14 18:14]
jeromejung [redirection of the customer to the merchant] 		en:girocheckout:paypal:start [2023/03/24 20:47]
michaelheumann
Line 1: Line 1:
 ====== PayPal ====== ====== PayPal ======
-Information about PayPal payment can be found under https://www.girosolution.de/girocheckout/bezahlverfahren.html. 
  
-===== test data =====+ 
 +===== Test data =====
 {{page>en:testdata:paypal&noheader&nofooter}} {{page>en:testdata:paypal&noheader&nofooter}}
-===== workflow =====+ 
 +===== Workflow =====
  
 <uml> <uml>
Line 38: Line 39:
  
   - buyer chooses PayPal payment method   - buyer chooses PayPal payment method
-  - merchant initialises PayPal transaction ([[en:girocheckout:paypal:start#initialise_paypal_payment|initialising PayPal payment]]) +  - merchant initializes PayPal transaction ([[en:girocheckout:paypal:start#initialize_paypal_payment|initializing PayPal payment]]) 
-  - GiroCheckout initialises transaction at PayPal+  - GiroCheckout initializes transaction at PayPal
   - PayPal submits response to GiroCheckout   - PayPal submits response to GiroCheckout
-  - merchant gets response about initialisation (if an issue occurs the transaction is finished)+  - merchant gets response about initialization (if an issue occurs the transaction is finished)
   - merchant sends redirect URL to buyer   - merchant sends redirect URL to buyer
   - the buyer's browser redirects buyer to the payment form   - the buyer's browser redirects buyer to the payment form
Line 57: Line 58:
 ===== API functions ===== ===== API functions =====
  
-==== overview =====+==== Overview =====
  
 As shown in the workflow there are different API calls during a PayPal transaction. As shown in the workflow there are different API calls during a PayPal transaction.
  
-  - initialise transaction +  - Initialize transaction 
-  - payment result notification to merchant +  - Payment result notification to merchant 
-  - buyer redirection to the merchant (triggered by buyer)+  - Buyer redirection to the merchant (triggered by buyer)
  
  
-==== initialise PayPal payment ====+==== Initialize 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. +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 ===+=== Request ===
 **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\ **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\
 **provided by:** GiroCheckout \\ **provided by:** GiroCheckout \\
Line 76: Line 77:
  
 == POST parameters == == POST parameters ==
-^name           ^mandatory  ^type        ^description   ^+^Name           ^Mandatory  ^Type        ^Description   ^
 |merchantId     |yes       |Integer     |merchant ID | |merchantId     |yes       |Integer     |merchant ID |
 |projectId      |yes       |integer     |project ID | |projectId      |yes       |integer     |project ID |
-|merchantTxId   |yes       |String(255) |unique transaction id of the merchant |+|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 | |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| |currency       |yes       |String(3)   |currency\\ EUR = Euro|
 |purpose        |yes       |String(27)  |purpose | |purpose        |yes       |String(27)  |purpose |
 +|type           |optional  |String(4)   |transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Immediate booking (default) \\ AUTH = Reservation of amount|
 |urlRedirect    |yes       |String      |URL, where the buyer has to be sent after payment | |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 | |urlNotify      |yes       |String      |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      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) | |hash           |yes       |String      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
  
  
-== example ==+== Example ==
 {{page>codesamples:paypal#transactionstart.request&noheader&nofooter}} {{page>codesamples:paypal#transactionstart.request&noheader&nofooter}}
  
  
-=== reply === +=== 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.+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.
  
  
Line 105: Line 108:
 |hash           |yes       |String    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | |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 ==+== Example in case of success ==
 {{page>codesamples:paypal#transactionstart.response.true&noheader&nofooter}} {{page>codesamples:paypal#transactionstart.response.true&noheader&nofooter}}
  
-== example in case of error ==+== Example in case of error ==
 {{page>codesamples:paypal#transactionstart.response.false&noheader&nofooter}} {{page>codesamples:paypal#transactionstart.response.false&noheader&nofooter}}
  
 +==== Notification about the payment result ====
  
-==== 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//. 
  
-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 ===
-=== request ===+
 **URL:** notifyUrl of the prior init transaction call \\ **URL:** notifyUrl of the prior init transaction call \\
 **provided by:** merchant \\ **provided by:** merchant \\
Line 129: Line 131:
 |gcAmount         |yes       |Integer     | if a decimal currency is used, the amount is in the smallest unit of value, eg. cent, penny | |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 | |gcCurrency       |yes       |String      | currency |
-|gcResultPayment  |optional |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]|+|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]]) | |gcHash           |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
  
-=== reply ===+=== Reply ===
 As a reply to the GET request, one of the following HTTP status codes is expected.  As a reply to the GET request, one of the following HTTP status codes is expected. 
  
Line 140: Line 142:
 |all others       |The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400. | |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 ====+==== 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.  After completing the payment, the customer may return to the merchant through a link. This return is not done automatically. 
  
-=== request ===+=== Request ===
 **URL:** redirectUrl of the prior init transaction call \\ **URL:** redirectUrl of the prior init transaction call \\
 **provided by:** merchant \\ **provided by:** merchant \\
Line 157: Line 159:
 |gcResultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| |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]]) | |gcHash           |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|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 ====
 +
 +<uml>
 +hide footbox
 +
 +participant "Shop" as shop
 +participant "GiroCheckout" as girocheckout
 +participant "Credit Card Processor" as cc
 +
 +autonumber
 +
 +shop -> girocheckout: 
 +girocheckout -> cc: 
 +cc -> girocheckout: 
 +girocheckout -> shop: 
 +
 +center footer (c)2016 by GiroSolution AG
 +</uml>
 +
 +  - Shop sends reference to previous credit card transaction
 +  - GiroCheckout sends transaction to credit card processor
 +  - credit card processor transmits result to GiroCheckout
 +  - Shop receives reply on transaction outcome ([[en:girocheckout:creditcard:start#notification_about_the_payment_result|Notification]])
 +
 +==== Capture ====
 +{{page>en:girocheckout:transactiontypes:descriptions#capture.desc&noheader&nofooter}}
 +
 +==== Refund ====
 +{{page>en:girocheckout:transactiontypes:descriptions#refund.desc&noheader&nofooter}}
 +
 +=== 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 [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro |
 +|reference      |yes       |String      |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      |(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      |HMAC MD5 hash on the complete call. See [[en:girocheckout:general:start#hash_generation|hash generation]] |
 +
 +== Example ==
 +{{page>codesamples:creditcard#capture.request&noheader&nofooter}}
 +
 +=== 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   |[[en:girocheckout:errorcodes|response code]] |
 +|msg            |yes       |String    |Additional information about the response code |
 +|reference      |yes       |String    |Unique GiroCheckout transaction ID |
 +|merchantTxId   |yes       |String      | Unique transaction id of the merchant |
 +|backendTxId    |yes       |String      | 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      | Currency |
 +|resultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]|
 +^HEADER parameter^^^^
 +|hash           |yes       |String    |HMAC MD5 hash on the complete JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |
 +
 +== Example in case of success ==
 +{{page>codesamples:creditcard#capture.response.true&noheader&nofooter}}
 +
 +== Example in case of error ==
 +{{page>codesamples:creditcard#capture.response.false&noheader&nofooter}}
  
en/girocheckout/paypal/start.txt · Last modified: 2023/05/08 04:17

Page Tools