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
en:girocheckout:paypal:start [2014/10/14 18:14]
jeromejung [notification about the payment result] 		en:girocheckout:paypal:start [2023/05/08 04:17] (current)
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 |
-|urlRedirect    |yes       |String      |URL, where the buyer has to be sent after payment | +|type           |optional  |String(4)   |transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Immediate booking (default) \\ AUTH = Reservation of amount| 
-|urlNotify      |yes       |String      |URL, where the notification has to be sent after payment | +|urlRedirect    |yes       |String(2048)      |URL, where the buyer has to be sent after payment | 
-|hash           |yes       |String      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |+|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 [[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 99: Line 102:
 ^name           ^mandatory  ^type      ^description   ^ ^name           ^mandatory  ^type      ^description   ^
 |rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] | |rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] |
-|msg            |yes       |String    |additional information about the response code | +|msg            |yes       |String(255)    |additional information about the response code | 
-|reference      |optional |String    |unique GiroCheckout transaction ID | +|reference      |optional |String(36)    |unique GiroCheckout transaction ID | 
-|redirect       |optional |String    |redirect URL to the payment page|+|redirect       |optional |String(255)    |redirect URL to the payment page|
 ^HEADER parameter^^^^ ^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]]) |+|hash           |yes       |String(32)    |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 124: Line 126:
 == GET parameter == == GET parameter ==
 ^name             ^mandatory    ^  type        ^description   ^ ^name             ^mandatory    ^  type        ^description   ^
-|gcReference      |yes       |String      | unique GiroCheckout transaction ID | +|gcReference      |yes       |String(36)      | unique GiroCheckout transaction ID | 
-|gcMerchantTxId   |yes       | String     | merchant transaction ID | +|gcMerchantTxId   |yes       |String(255)     | merchant transaction ID | 
-|gcBackendTxId    |yes       |String      | payment processor 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 | |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(3)      | currency |
 |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(32)      | 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 150: Line 152:
 == GET parameter == == GET parameter ==
 ^name             ^mandatory    ^  type        ^description   ^ ^name             ^mandatory    ^  type        ^description   ^
-|gcReference      |yes       |String      | unique GiroCheckout transaction ID | +|gcReference      |yes       |String(36)      | unique GiroCheckout transaction ID | 
-|gcMerchantTxId   |yes       | String     | merchant transaction ID | +|gcMerchantTxId   |yes       |String(255)     | merchant transaction ID | 
-|gcBackendTxId    |yes       |String      | payment processor 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 | |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(3)      | currency |
 |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(32)      | 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(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 [[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(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     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]| 
 +^HEADER parameter^^^^ 
 +|hash           |yes       |String(32)    |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