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
en:girocheckout:giropay:start [2024/03/13 20:36]
michaelheumann 		en:girocheckout:giropay:start [2024/06/05 18:25] (current)
michaelheumann
Line 19: Line 19:
 ===== Test data giropay ===== ===== Test data giropay =====
 {{page>en:testdata:giropaypd&noheader&nofooter}} {{page>en:testdata:giropaypd&noheader&nofooter}}
 +
 +===== Transaction types =====
 +Detailed information regarding [[en:girocheckout:transactiontypes:start|Transaction types]]. 
 +
 +<uml>
 +left to right direction
 +skinparam packageStyle rect
 +
 +rectangle SALE{
 +  (SALE) --> (REFUND)
 +  (REFUND)
 +}
 +rectangle AUTH {
 +  (AUTH) --> (CAPTURE )
 +  (CAPTURE ) --> (REFUND )
 +
 +}
 +</uml>
  
 ===== Workflow ===== ===== Workflow =====
Line 74: 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 104: Line 143:
 |currency       |yes       |String(3)   |currency\\ EUR = Euro| |currency       |yes       |String(3)   |currency\\ EUR = Euro|
 |purpose        |yes       |String(27)  |purpose field, characters must comply with the SEPA character set (see [[en:girocheckout:giropay:start#sepa_compliant_characters|SEPA-compliant characters]]) | |purpose        |yes       |String(27)  |purpose field, characters must comply with the SEPA character set (see [[en:girocheckout:giropay:start#sepa_compliant_characters|SEPA-compliant characters]]) |
 +|type           |Optional |String(4)      |Transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Sale is booked immediately (default) \\ AUTH = Reservation of the amount |
 |shoppingCartType |Optional | String(19) |Type of the shopping cart. The following values are allowed: \\ PHYSICAL = All goods in the cart are of a physical nature, \\ DIGITAL = All goods in the cart are of a digital nature (require no shipping), \\ MIXED = The cart contains both physical and digital goods (this is the default value should the parameter not be given), \\ ANONYMOUS_DONATION = This is an anonymous donation and not a commercial transaction (no address data necessary), \\ AUTHORITIES_PAYMENT = This is a payment for local authorities (no address data necessary).| |shoppingCartType |Optional | String(19) |Type of the shopping cart. The following values are allowed: \\ PHYSICAL = All goods in the cart are of a physical nature, \\ DIGITAL = All goods in the cart are of a digital nature (require no shipping), \\ MIXED = The cart contains both physical and digital goods (this is the default value should the parameter not be given), \\ ANONYMOUS_DONATION = This is an anonymous donation and not a commercial transaction (no address data necessary), \\ AUTHORITIES_PAYMENT = This is a payment for local authorities (no address data necessary).|
 |shippingAddresseFirstName |(see descr.) |String(100)  | First name of the shipping address. **Mandatory** for shopping cart types PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters: All letters (UTF-8, also foreign), 0-9, the symbols %% .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[] %%, and blanks as well as line breaks. | |shippingAddresseFirstName |(see descr.) |String(100)  | First name of the shipping address. **Mandatory** for shopping cart types PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters: All letters (UTF-8, also foreign), 0-9, the symbols %% .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[] %%, and blanks as well as line breaks. |
Line 262: Line 302:
 {{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.1710358568.txt.gz · Last modified: 2024/03/13 20:36

Page Tools