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
Last revision Both sides next revision
en:girocheckout:giropay:start [2024/03/13 20:39]
michaelheumann [Workflow] 		en:girocheckout:giropay:start [2024/03/13 20:51]
michaelheumann
Line 143: 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           |yes  |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 301: 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.txt · Last modified: 2024/03/13 20:53

Page Tools