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 [2022/02/25 21:26]
michaelheumann 		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/fuer-haendler/.+
  
 ===== 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 |
Line 83: Line 84:
 |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]]) |
  
  
Line 205: Line 207:
 |amount         |yes       |Integer     |If a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny | |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 | |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 |+|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.| |purpose        |optional  |String(27)  |Purpose of the refund or capture. This information is printed on the credit card statement.|
-|hash           |yes       |String      |HMAC MD5 hash on the complete call. See [[en:girocheckout:general:start#hash_generation|hash generation]] |+|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 == == Example ==
Line 218: Line 221:
 ^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      |yes       |String    |Unique GiroCheckout transaction ID | +|reference      |yes       |String(36)    |Unique GiroCheckout transaction ID | 
-|merchantTxId   |yes       |String      | Unique transaction id of the merchant | +|merchantTxId   |yes       |String(255)      | Unique transaction id of the merchant | 
-|backendTxId    |yes       |String      | Payment processor transaction ID |+|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 | |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 |+|currency       |yes       |String(3)      | Currency |
 |resultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]| |resultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]|
 ^HEADER parameter^^^^ ^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]]) |+|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 == == Example in case of success ==
en/girocheckout/paypal/start.1645820778.txt.gz · Last modified: 2022/02/25 21:26

Page Tools