Girocheckout API

User Tools

Site Tools

Trace:
en:girocheckout:giropay: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
Next revision Both sides next revision
en:girocheckout:giropay:start [2024/03/13 20:38]
michaelheumann 		en:girocheckout:giropay:start [2024/03/13 20:46]
michaelheumann
Line 92: Line 92:
   - buyer/customer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:giropay:start#redirection_of_the_customer_to_merchant|buyer redirection]])   - buyer/customer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:giropay:start#redirection_of_the_customer_to_merchant|buyer redirection]])
  
 +==== Reservation (AUTH) ====
 +{{page>en:girocheckout:transactiontypes:descriptions#auth.desc&noheader&nofooter}}
 +<uml>
 +left to right direction
 +skinparam packageStyle rect
 +
 +rectangle AUTH {
 +  (AUTH) --> (capture)
 +  (AUTH) --> (refund)
 +}
 +</uml>
 +==== Reservation/Booking (SALE) ====
 +{{page>en:girocheckout:transactiontypes:descriptions#sale.desc&noheader&nofooter}}
 +<uml>
 +left to right direction
 +skinparam packageStyle rect
 +
 +rectangle SALE{
 +  (SALE) --> (refund)
 +}
 +</uml>
 ===== API functions ===== ===== API functions =====
  
Line 280: Line 301:
 {{page>codesamples:giropay#senderinfo.response.false&noheader&nofooter}} {{page>codesamples:giropay#senderinfo.response.false&noheader&nofooter}}
  
 +===== Other transaction types =====
 +These transactions refer to a previous transaction. They are based on a server-to-server communication and require no customer intervention (in terms of data entry).
 +
 +Provided by: GiroCheckout \\
 +Called by: Merchant \\
 +
 +==== Workflow ====
 +
 +<uml>
 +hide footbox
 +
 +participant "Shop" as shop
 +participant "GiroCheckout" as girocheckout
 +participant "giropay" as gp
 +
 +autonumber
 +
 +shop -> girocheckout: 
 +girocheckout -> gp: 
 +gp -> girocheckout: 
 +girocheckout -> shop: 
 +
 +center footer (c)2024 by S-Public Services GmbH
 +</uml>
 +
 +  - Shop sends referencing transaction
 +  - GiroCheckout routes transaction to giropay
 +  - giropay transmits result to GiroCheckout
 +  - Shop receives reply regarding transaction result ([[en:girocheckout:giropay:start#notification_of_payment_result|Notification]])
 +
 +==== Booking (CAPTURE) ====
 +{{page>en:girocheckout:transactiontypes:descriptions#capture.desc&noheader&nofooter}}
 +
 +<uml>
 +left to right direction
 +skinparam packageStyle rect
 +
 +rectangle AUTH {
 +  (auth) --> (CAPTURE)
 +}
 +</uml>
 +
 +==== Refund ====
 +{{page>en:girocheckout:transactiontypes:descriptions#refund.desc&noheader&nofooter}}
 +<uml>
 +left to right direction
 +skinparam packageStyle rect
 +
 +rectangle SALE{
 +  (sale) --> (REFUND)
 +}
 +rectangle AUTH {
 +  (auth) --> (REFUND )
 +}
 +</uml>
 +
 +=== POST Parameters ===
 +CAPTURE URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture \\
 +REFUND URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund \\
 +
 +^Name           ^Mandatory^^Type        ^Description   ^
 +^::: ^ CAPTURE ^ REFUND ^::: ^::: ^
 +|merchantId     |Yes       |Yes |Integer     |Merchant ID of a giropay project |
 +|projectId      |Yes       |Yes |Integer     |Project ID of a giropay project |
 +|merchantTxId   |Yes       |Yes |String(255) |Unique merchant transaction ID. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /  |
 +|amount         |Yes       |Yes |Integer     |Full or partial amount. For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
 +|currency       |Yes       |Yes |String(3)   |Transaction currency, see [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro |
 +|purpose        |Yes       |Yes |String(27)  |Transaction purpose. This information is displayed on the accounting reports. |
 +|reference      |Yes  |Yes |String(36)      | GiroCheckout transaction ID of the underlying AUTH transaction. |
 +|merchantReconciliationReferenceNumber   |Optional  |Optional         |String(30)    | Additional information for the payment reconciliation that is shown in the purpose on bank statements. |
 +|final   |Optional  | |Boolean | CAPTURE ONLY. Last CAPTURE for a reservation. After this, no further CAPTURE may be done on the referenced reservation. |
 +|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       |Yes |String(32)      |HMAC MD5 hash of all the values in the call. See [[en:girocheckout:general:start#hash_generation|Generate hash]] |
 +
 +== Example ==
 +{{page>codesamples:giropay#capture.request&noheader&nofooter}}
 +
 +=== Response ===
 +The response is a JSON object. The field resultPayment returns an error code. If resultPayment = 4000 is returned, the transaction was carried out successfully. You receive a transaction number in the reply.
 +
 +== Parameters ==
 +^Name             ^Mandatory  ^Type        ^Description   ^
 +|reference      |Yes       |String(36)      | GiroCheckout transaction ID |
 +|merchantTxId   |Yes       |String(255)      | Merchant transaction ID |
 +|backendTxId    |Yes       |String(36)      | Transaction ID of the payment provider |
 +|amount         |Yes       |Integer     | For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
 +|currency       |Yes       |String(3)      | Currency |
 +|resultPayment  |Yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result]]|
 +|hash           |Yes       |String(32)      | HMAC MD5 hash of all the values of the call. Siehe  [[en:girocheckout:general:start#hash_generation|Generate hash]] |
 +
 +== Example of success case ==
 +{{page>codesamples:giropay#capture.response.true&noheader&nofooter}}
 +
 +== Example of failure ==
 +{{page>codesamples:giropay#capture.response.false&noheader&nofooter}}
 +
 +==== Void ====
 +{{page>en:girocheckout:transactiontypes:descriptions#void.desc&noheader&nofooter}}
 +
 +=== POST Parameters ===
 +URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void
 +
 +^Name           ^Mandatory  ^Type      ^Description   ^
 +|merchantId     |Yes       |Integer     |Merchant ID of a giropay project |
 +|projectId      |Yes       |Integer     |Project ID of a giropay project |
 +|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 & = + , : ; . _ ! ? # /  |
 +|reference      |Yes       |String(36)      |GiroCheckout transaction ID that is to be voided |
 +|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 ==
 +{{page>codesamples:giropay#void.request&noheader&nofooter}}
 +
 +=== Reply ===
 +The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful. The response includes a transaction number and other information.
 +
 +== 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 |
 +|referenceParent      |yes       |String(36)      | GiroCheckout transaction ID of the original base transaction |
 +|merchantTxId   |yes       |String(255)      | Unique transaction id of the merchant |
 +|backendTxId    |yes       |String(36)      | Payment processor transaction ID |
 +|amount         |yes       |Integer     | Voided amount, 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:giropay#void.response.true&noheader&nofooter}}
 +
 +== Example in case of failure ==
 +{{page>codesamples:giropay#void.response.false&noheader&nofooter}}
  
en/girocheckout/giropay/start.txt · Last modified: 2024/03/13 20:53

Page Tools