Girocheckout API

User Tools

Site Tools

Trace: • creditcard
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 [2023/02/10 22:32]
michaelheumann 		en:girocheckout:paypal:start [2023/05/08 04:17]
michaelheumann
Line 4: Line 4:
 ===== Test data ===== ===== Test data =====
 {{page>en:testdata:paypal&noheader&nofooter}} {{page>en:testdata:paypal&noheader&nofooter}}
-===== workflow =====+ 
 +===== Workflow =====
  
 <uml> <uml>
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.
  
-  - initialize 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)
  
  
 ==== Initialize PayPal payment ==== ==== Initialize PayPal payment ====
  
-Torwards 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. +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 84: Line 85:
 |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| |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(2048)      |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(2048)      |URL, where the notification has to be sent after payment | 
-|kassenzeichen  |optional  |String(30)  |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 SEPA character set (see [[#sepa_compliant_characters|SEPA-compliant characters]]). | +|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(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 initialized. 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 101: 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}}
  
-=== SEPA compliant characters === +==== Notification about the payment result ====
-{{page>en:resources:sepa-chars&noheader&nofooter}} +
- +
-==== 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 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 ===+=== Request ===
 **URL:** notifyUrl of the prior init transaction call \\ **URL:** notifyUrl of the prior init transaction call \\
 **provided by:** merchant \\ **provided by:** merchant \\
Line 128: 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 144: 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 154: 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 209: 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.|
-|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. | +|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      |HMAC MD5 hash on the complete call. See [[en:girocheckout:general:start#hash_generation|hash generation]] |+|hash           |yes       |String(32)      |HMAC MD5 hash on the complete call. See [[en:girocheckout:general:start#hash_generation|hash generation]] |
  
 == Example == == Example ==
Line 223: 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.txt · Last modified: 2023/05/08 04:17

Page Tools