User Tools

Site Tools


Translations of this page:
en:girocheckout:creditcard:start

Credit Card

Information about credit card payment can be found under https://www.girosolution.de/girocheckout/fuer-haendler/ (sorry, German only).

Test data

Visa 4111111111111111
Mastercard 5500000000000004
CVC2/CVV any 3-digit number (is not being checked)
valid until any date in the future

Verified by Visa or Mastercard SecureCode are not available in test mode.

Transaction results

Result code Answer Description
4000 Successful transaction After entering the above data and considering the following information, the transaction is successful:
Integer amount between 1,00 and 99,00
4502 Aborted transaction After clicking the button cancel you create an aborted transaction.

Transaction types

Detailed information on the transaction types.

Reservation (AUTH)

A reservation is to be used when the actual fulfillment of an order takes place at a later time, but the order amount for the presented card (for credit card transactions) or the given account information (for Paydirekt payments and others) needs to be authorized beforehand at the time of the order. Once the reservation period has expired, the reservation is either booked or voided.

  • initial Transaction

PlantUML Graph

Sale

Use sale when the business case is complete, e.g. a shopping cart was offered, ordered and delivered to the customer. The customer's payment method is debited with the amount of the sale.

  • initial Transaction

PlantUML Graph

Initialize credit card payment

After a successful initialization the merchant receives a reference number and a redirect link. The redirect link leads to the payment page. The customer (buyer) must be redirected to this link. This can be achieved by an HTTP redirect header, an HTML page with a corresponding meta tag or a JavaScript redirect.

Provided by: GiroCheckout
Called by: merchant

Workflow

PlantUML Graph

  1. Buyer selects payment type “credit card”
  2. Shop initializes credit card transaction (Initialization)
  3. GiroCheckout initializes transaction at CC processor
  4. Credit card processor transmits result to GiroCheckout
  5. Shop receives response about transaction outcome (transaction ends in case of error)
  6. Shop sends redirect URL to customer browser
  7. Customer browser redirects to credit card processor
  8. Credit card processor displays payment form
  9. Customer authorizes transaction
  10. Credit card processor carries out transaction
  11. Credit card processor transmits result to GiroCheckout
  12. GiroCheckout notifies Shop about transaction outcome (Notification)
  13. Shop processes transaction outcome
  14. Shop sends HTTP status code to GiroCheckout
  15. GiroCheckout sends merchant redirect (return to merchant page) to Credit card processor
  16. Customer clicks “Back to shop” (Return)

API functions

Overview

As shown in the workflow, different API calls are involved in a credit card transaction. During the payment process a 3D-Secure check may be applied as well, but this depends solely on the credit card issuing institute and does not affect merchant or PSP in any way.

  1. Initialize transaction
  2. 3D-Secure check (optional)
  3. Payment result notification to merchant
  4. Buyer redirection to the merchant (triggered by buyer)

Reservation/Sale

POST parameters

Name Mandatory Type Description
merchantId yes Integer merchant ID
projectId yes integer project ID
merchantTxId yes String(255) unique transaction id of the merchant
amount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency yes String(3) currency
EUR = Euro
purpose yes String(27) purpose
type optional String(4) transaction type (see Transaction types)
SALE = Immediate booking (default)
AUTH = Reservation of amount
locale optional String(4) language of the credit card payment page
de = German (default)
en = English
es = Spanish
fr = French
it = Italian
ja = Japanese
pt = Portuguese
nl = Dutch
cs = Czech
sv = Swedish
da = Danish
pl = Polish
spde = German donation
spen = English donation
de_DE_stadtn = German communes
mobile optional Boolean optimised payment page for mobile devices
0 = no (default)
1 = yes
pkn optional String(50) This field is used process a transaction without re-entering the card data.
create = generate a new pseudo card number
[pseudo card number] = pkn of the masked card data (see pseudo card number)
recurring optional Boolean recurring payment
0 = no (default)
1 = yes
urlRedirect yes String URL, where the buyer has to be sent after payment
urlNotify yes String URL, where the notification has to be sent after payment
hash yes String HMAC MD5 hash (see hash generation)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "locale=de" \
     -d "mobile=0" \
     -d "pkn=create" \
     -d "recurring=0" \
     -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
     -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=9fbd406b72b229a386cd65fc1257c9ad" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Reply

The reply is 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.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String additional information about the response code
reference optional String unique GiroCheckout transaction ID
redirect optional String redirect URL to the payment page
HEADER parameter
hash yes String HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=wrlIRO9O30S4NNAO9h6uHwhyWibDFKUWeoWy7mPLDDyZ","rc":"0","msg":""}
Example in case of error
{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

Notification about the payment result

The result of an initialized transaction will be submitted to the merchant through URL specified in the urlNotify parameter. This notification should be used to update the order status in the merchant's system.

The result of the payment is contained in the field gcResultPayment.

Request

URL: notifyUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

GET parameters
Name Mandatory Type Description
gcReference yes String unique GiroCheckout transaction ID
gcMerchantTxId yes String merchant transaction ID
gcBackendTxId yes String payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
gcCurrency yes String currency
gcResultPayment yes Integer Payment result codes
gcHash yes String HMAC MD5 hash (see hash generation)

Reply

As a reply to the GET request, one of the following HTTP status codes is expected.

HTTP status code Description
200 (OK) The notification was processed correctly.
400 (Bad Request) The merchant did not process the notification and does not wish to be notified again.
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 merchant

After completing the payment, the customer may return to the merchant through a link. This return only happens once the customer clicks the “cancel” or “return to shop” button and is not done automatically.

Request

URL: redirectUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

GET parameters
Name Mandatory Type Description
gcReference yes String unique GiroCheckout transaction ID
gcMerchantTxId yes String merchant transaction ID
gcBackendTxId yes String payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny
gcCurrency yes String Currency
gcResultPayment yes Integer Payment result codes
gcHash yes String HMAC MD5 hash (see hash generation)

Other transaction types

These transactions reference a previous transaction. They are based on a server to server communication and require no customer interaction (data entry).

Provided by: GiroCheckout
Called by: Merchant

Workflow

PlantUML Graph

  1. Shop sends reference to previous credit card transaction
  2. GiroCheckout sends transaction to credit card processor
  3. credit card processor transmits result to GiroCheckout
  4. Shop receives reply on transaction outcome (Notification)

Capture

When booking, the customer account is debited with an amount and the merchant account is credited. This model is based on the assumption that the associated business case has been completed, e.g. a shopping cart was offered, ordered and delivered to the customer.

  • Condition: only reserved transactions may be booked
  • Amount ⇐ Reservation amount
  • Partial bookings are possible

Refund

A refund is to be used when a previous payment is to be returned fully or partially to the customer.

  • Condition: may only be applied to the following transaction types:
    • Reservation
    • Reservation/Booking
  • Amount ⇐ Transaction amount of the previous transaction

POST Parameters

URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

Name Mandatory Type Description
merchantId yes Integer Merchant ID
projectId yes Integer Project ID
merchantTxId yes String(255) Unique transaction id of the merchant
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 ISO 4217.
EUR = Euro
reference yes String GiroCheckout transaction ID from a previous transaction, which the capture or refund is for
hash yes String HMAC MD5 hash on the complete call. See hash generation
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

Reply

The reply is 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 other information about the transaction.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String Additional information about the response code
reference yes String Unique GiroCheckout transaction ID
merchantTxId yes String Unique transaction id of the merchant
backendTxId yes String 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
currency yes String Currency
resultPayment yes Integer Payment result codes
HEADER parameter
hash yes String HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"7f18859d-7246-4181-8fb5-30ce7958f309","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1196307_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}
Example in case of error
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":"5200","rc":0,"msg":"Transaktion nicht akzeptiert"}

Void

Void is to be used when an already accepted transaction is not to be executed.

  • Condition: may only be applied to the following transaction types:
    • Reservation (as long as booking has not been done and reservation hasn't expired)
    • Reservation/Booking (only on the same day)
    • Refund (only on the same day)

POST Parameters

URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Name Mandatory Type Description
merchantId Yes Integer Merchant ID of a credit card project
projectId Yes Integer Project ID of a credit card project
merchantTxId Yes String(255) Unique transaction ID of the merchant
reference Yes String GiroCheckout transaction ID that is to be voided
hash Yes String HMAC MD5 hash on the complete JSON string. (see api call reply)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/void

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 response code
msg yes String Additional information about the response code
reference yes String Unique GiroCheckout transaction ID
referenceParent yes String GiroCheckout transaction ID of the original base transaction
merchantTxId yes String Unique transaction id of the merchant
backendTxId yes String 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 Currency
resultPayment yes Integer Payment result codes
HEADER parameter
hash yes String HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"ef27303f-87b3-465e-9c39-fabfb749d253","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1226723_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}
Example in case of failure
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

Pseudo card numbers (PKN)

This function requires a separate implementation on PSP side which also generate a one-time implementation fee.

A pseudo card number is a reference to a credit card that has been used recently by the buyer (card number and expiration date). This reference allows the merchant to offer a previously used credit card for reuse by the customer. If the PKN is transmitted along during the initialization of a credit card transaction, the card number and expiration date is pre-filled in the payment form. The customer needs only to enter the validation code and may then carry out the payment.

Query pseudo card information

This function allows access to PKN information. It returns as a result both the PKN and the saved credit card information (masked credit card number, expiration date), which were used for a previous transaction.

URL: https://payment.girosolution.de/girocheckout/api/v2/creditcard/pkninfo
Provided by: GiroCheckout
Called by: Merchant

POST Parameters

Name Mandatory Type Description
merchantId yes Integer Merchant ID
projectId yes Integer Project ID
reference yes String(36) Unique reference to a GiroCheckout transaction
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f" \
     -d "hash=dc1686b621c9cc15bd271390c694258d" \
     https://payment.girosolution.de/girocheckout/api/v2/creditcard/pkninfo

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 the PKN number, the (masked) credit card number and the expiration date.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String Additional information about the response code
pkn yes String Pseudo card number
cardnumber yes String Masked credit card number, e.g. 411111******1111
expiremonth yes String Month of the credit card's expiration date
expireyear yes String Year of the credit card's expiration date
HEADER Parameter
hash yes String HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"pkn":"ad5c386b38cc9aeb839705d1d10da499","cardnumber":"411111******1111","expiremonth":"2","expireyear":"2016","rc":0,"msg":""}
Example in case of error
{"pkn":null,"cardnumber":null,"expiremonth":null,"expireyear":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}

Recurring credit card payment

The transaction data is transmitted and the result of the credit card payment is returned immediately. This function is used for recurring credit card payments, such as subscriptions.

The following steps are necessary to implement a recurring payment:

  1. Carry out a normal credit card transaction (see Initialize Payment)
  2. Obtain pseudo card number (PKN) (see Query PKN information)
  3. Store this PKN
  4. On the next recurring payment, initialize a payment transaction (use correct end point, see Recurring or PKN transaction), but set parameter pkn and let recurring=1.

Recurring transaction

In order to carry out a recurring payment without customer intervention, use the following function.

POST Parameters

URL https://payment.girosolution.de/girocheckout/api/v2/transaction/payment

Name Mandatory Type Description
merchantId yes Integer merchant ID
projectId yes integer project ID
merchantTxId yes String(255) unique transaction id of the merchant
amount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency yes String(3) currency
EUR = Euro
purpose yes String(27) purpose
type optional String(4) transaction type (see Transaction types)
SALE = Immediate booking (default)
AUTH = Reservation of amount
pkn optional String(50) This field is used process a transaction without re-entering the card data.
create = generate a new pseudo card number
[pseudo card number] = pkn of the masked card data (see pseudo card number)
recurring optional Boolean recurring payment
0 = no (default)
1 = yes
urlNotify yes String URL, where the notification has to be sent after payment
hash yes String HMAC MD5 hash (see hash generation)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "pkn=ad5c386b38cc9aeb839705d1d10da499" \
     -d "recurring=0" \
     -d "hash=0361f14f7b1be9be16326b2edd925853" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/payment

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful.

Parameters

Name Mandatory Type Description
rc yes Integer response code
msg yes String Additional information about the response code
reference yes String Unique GiroCheckout transaction ID
backendTxId yes String Payment processor transaction ID
resultPayment yes Integer Payment result codes
HEADER parameter
hash yes String HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"7f18859d-7246-4181-8fb5-30ce7958f309","backendTxId":"1196307_01","resultPayment":"4000","rc":0,"msg":""}
Example in case of error
{"reference":"fb70602d-c137-4413-8432-7dcc69a9d891","backendTxId":"","resultPayment":"4106","rc":0,"msg":"Pseudo-Kartennummer ungültig "}
en/girocheckout/creditcard/start.txt · Last modified: 2017/04/04 16:16 by michaelheumann

Page Tools