en:girocheckout:creditcard_3ds2:start
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
en:girocheckout:creditcard_3ds2:start [2020/12/18 14:23] michaelheumann |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Credit Card 3D Secure 2.0 ====== | ||
| - | **This is the future version of the creditcard API that includes the new fields for 3D Secure 2.0. This API is not yet available for testing on our server! These docs are only a preview of the upcoming API.** | ||
| - | |||
| - | New in these docs are mostly the fields whose names start with " | ||
| - | |||
| - | <WRAP center round info 70%> | ||
| - | The parameters related to 3D Secure 2.0 are subject to changes due to modifications in the EMVCo 3-D Secure specs. | ||
| - | </ | ||
| - | |||
| - | ===== Test data ===== | ||
| - | {{page> | ||
| - | |||
| - | ===== Transaction types ===== | ||
| - | Detailed information on the [[en: | ||
| - | |||
| - | ==== Reservation (AUTH) ==== | ||
| - | {{page> | ||
| - | |||
| - | <uml> | ||
| - | left to right direction | ||
| - | skinparam packageStyle rect | ||
| - | |||
| - | rectangle AUTH { | ||
| - | (AUTH) --> (CAPTURE) | ||
| - | (AUTH) --> (VOID ) | ||
| - | (CAPTURE) --> (VOID ) | ||
| - | (CAPTURE) --> (REFUND ) | ||
| - | (REFUND ) --> (VOID ) | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | ==== Sale ==== | ||
| - | {{page> | ||
| - | |||
| - | <uml> | ||
| - | left to right direction | ||
| - | skinparam packageStyle rect | ||
| - | |||
| - | rectangle SALE{ | ||
| - | (SALE) --> (REFUND) | ||
| - | (SALE) --> (VOID) | ||
| - | (REFUND) --> (VOID) | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | ===== 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 ===== | ||
| - | |||
| - | <uml> | ||
| - | hide footbox | ||
| - | |||
| - | participant " | ||
| - | participant " | ||
| - | participant " | ||
| - | participant " | ||
| - | |||
| - | autonumber | ||
| - | |||
| - | customer -> shop: | ||
| - | shop -> girocheckout: | ||
| - | girocheckout -> cc: | ||
| - | cc -> girocheckout: | ||
| - | girocheckout -> shop: | ||
| - | shop -> customer: | ||
| - | customer -> cc: | ||
| - | cc -> customer: | ||
| - | customer -> cc: | ||
| - | cc -> cc: | ||
| - | cc -> girocheckout: | ||
| - | girocheckout -> shop | ||
| - | shop -> shop: | ||
| - | shop -> girocheckout: | ||
| - | girocheckout -> cc: | ||
| - | cc -> shop: | ||
| - | |||
| - | |||
| - | center footer (c)2016 by GiroSolution AG | ||
| - | </ | ||
| - | |||
| - | - Buyer selects payment type " | ||
| - | - Shop initializes credit card transaction ([[en: | ||
| - | - GiroCheckout initializes transaction at CC processor | ||
| - | - Credit card processor transmits result to GiroCheckout | ||
| - | - Shop receives response about transaction outcome (transaction ends in case of error) | ||
| - | - Shop sends redirect URL to customer browser | ||
| - | - Customer browser redirects to credit card processor | ||
| - | - Credit card processor displays payment form | ||
| - | - Customer authorizes transaction | ||
| - | - Credit card processor carries out transaction | ||
| - | - Credit card processor transmits result to GiroCheckout | ||
| - | - GiroCheckout notifies Shop about transaction outcome ([[en: | ||
| - | - Shop processes transaction outcome | ||
| - | - Shop sends HTTP status code to GiroCheckout | ||
| - | - GiroCheckout sends merchant redirect (return to merchant page) to Credit card processor | ||
| - | - Customer clicks "Back to shop" ([[en: | ||
| - | |||
| - | ===== 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. | ||
| - | |||
| - | - Initialize transaction | ||
| - | - 3D-Secure check (optional) | ||
| - | - Payment result notification to merchant | ||
| - | - Buyer redirection to the merchant (triggered by buyer) | ||
| - | |||
| - | ==== Reservation/ | ||
| - | |||
| - | === POST parameters === | ||
| - | ^Name | ||
| - | |merchantId | ||
| - | |projectId | ||
| - | |merchantTxId | ||
| - | |amount | ||
| - | |currency | ||
| - | |purpose | ||
| - | |type | ||
| - | |locale | ||
| - | |mobile | ||
| - | |pkn |optional |String(50) | ||
| - | |recurring | ||
| - | |urlRedirect | ||
| - | |urlNotify | ||
| - | |tds2Address |optional |String | For 3D Secure 2.0: Main address line (usually street and number) of the card holder' | ||
| - | |tds2Postcode |optional |String | For 3D Secure 2.0: Postal code of the card holder' | ||
| - | |tds2City |optional |String | For 3D Secure 2.0: City of the card holder' | ||
| - | |tds2Country |optional |String | For 3D Secure 2.0: Country of the card holder' | ||
| - | |tds2Optional |optional |String | For 3D Secure 2.0: JSON-String that contains further optional fields. A complete list of the available fields can be found underneath this table under [[en: | ||
| - | |hash | ||
| - | |||
| - | === 3D Secure 2.0 Optional Fields (tds2Optional) === | ||
| - | This is a JSON formatted object that has a hierarchical structure (2 levels) and contains the following sub-objects: | ||
| - | |||
| - | * billingAddress | ||
| - | * shippingddress | ||
| - | * homePhoneNumber | ||
| - | * mobilePhoneNumber | ||
| - | * workPhoneNumber | ||
| - | * cardholderAccountInfo | ||
| - | * tdsMerchantRiskIndicators | ||
| - | * tdsRequestorAuthenticationInformation | ||
| - | * tdsTransactionAttributes | ||
| - | |||
| - | Generally, the following fields (all optional) are available (fields in sub-objects are displayed as [sub-object name].[field]): | ||
| - | |||
| - | ^Name | ||
| - | |email |String | The card holder' | ||
| - | |addressesMatch |Boolean | ||
| - | ^**// | ||
| - | |billingAddress.line2 |String | Second line of the billing address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
| - | |billingAddress.line3 |String | Third line of the billing address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
| - | |billingAddress.state |String | Subdivision (state, province or the like) of a country according to ISO 3166-2. Format A-Z, max. 3. | | ||
| - | ^**// | ||
| - | |shippingAddress.line1 |String | First line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
| - | |shippingAddress.line2 |String | Second line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
| - | |shippingAddress.line3 |String | Third line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
| - | |shippingAddress.postcode |String |Postal code of the shipping address, Format A-Z, a-z, 0-9, Blank, [-], max. 11 | | ||
| - | |shippingAddress.city |String | City of the shipping address, Format A-Z, a-z, 0-9, Blank, [-/ | ||
| - | |shippingAddress.state |String | Subdivision (state, province or the like) of a country according to ISO 3166-2. Format A-Z, max. 3 | | ||
| - | |shippingAddress.country |String | Country of the shipping address, Format A-Z, max. 2. Two-letter country code according to the currently applicable standard ISO 3166. | | ||
| - | ^**// | ||
| - | |homePhoneNumber.country |Integer | Country code of the telephone number without leading zeroes. Format 0-9, max. 3. e.g. 49 for Germany. | | ||
| - | |homePhoneNumber.regional |String | Telephone number without country code and without leading 0 (area code and local number). Format 0-9, max. 15, e.g. 73482984938. | | ||
| - | ^**// | ||
| - | |mobilePhoneNumber.country |Integer | Country code of the mobile phone number without leading zeroes. Format 0-9, max. 3. e.g. 49 for Germany. | | ||
| - | |mobilePhoneNumber.regional |String | Telephone number without country code and without leading 0 (area code and local number). Format 0-9, max. 15, e.g. 73482984938. | | ||
| - | ^**// | ||
| - | |workPhoneNumber.country |Integer | Country code of the work phone number without leading zeroes. Format 0-9, max. 3. e.g. 49 for Germany. | | ||
| - | |workPhoneNumber.regional |String | Telephone number without country code and without leading 0 (area code and local number). Format 0-9, max. 15, e.g. 73482984938. | | ||
| - | ^**// | ||
| - | |cardholderAccountInfo.accountAgeIndicator |String | Indicates when the customer' | ||
| - | |cardholderAccountInfo.passwordChangeIndicator |String | Indicates when the password of the customer account was changed the last time. Possible values: " | ||
| - | |cardholderAccountInfo.paymentAccountAgeIndicator |String | Indicates when the customer' | ||
| - | |cardholderAccountInfo.accountChange |String | Indicates when the customer account in the shop was last modified, e.g. address change or new payment data. Possible values: " | ||
| - | |cardholderAccountInfo.shippingAddressAgeIndicator |String | Indicates when the customer first used the current shipping address. Possible values: " | ||
| - | |cardholderAccountInfo.shippingNameIndicator |String | Specifies if the card holder' | ||
| - | |cardholderAccountInfo.suspiciousAccountActivity |Boolean | Indicates if the shop experienced suspicious activities of the card holder (true) or not (false). | | ||
| - | |cardholderAccountInfo.provisioningDayCount |Integer | Number of "add card" attempts within the last 24 hours. Format 0-9, max. 3. | | ||
| - | ^**// | ||
| - | |tdsMerchantRiskIndicators.deliveryTimeframe |String | Indicates when the customer will receive the merchandise. Possible values: " | ||
| - | |tdsMerchantRiskIndicators.deliveryEmailAddress |String | Delivery email address of the customer in case of an electronic delivery. Format A-Z, a-z, 0-9, [_.+-@], max. 254. | | ||
| - | |tdsMerchantRiskIndicators.giftCardAmount |Integer | Amount of a gift card in major currency unit, e.g. 123,45 EUR is 123. Format 0-9, max. 10. | | ||
| - | |tdsMerchantRiskIndicators.giftCardCount |Integer | Total count of gift cards purchased. Format 0-9, max. 2. | | ||
| - | |tdsMerchantRiskIndicators.giftCardCurrency |Integer | Currency code of a gift card according to ISO 4217. Format A-Z, max. 3. | | ||
| - | |tdsMerchantRiskIndicators.preOrderDate |Date | In the case of a pre-ordered purchase: date when the merchandise is expected to be available. | | ||
| - | |tdsMerchantRiskIndicators.preOrderPurchaseIndicator |String | Possible values: " | ||
| - | |tdsMerchantRiskIndicators.reorderItemsIndicator |String | Indicates if the customer is reordering previously purchased merchandise: | ||
| - | |tdsMerchantRiskIndicators.shippingIndicator |String | Specifies where the merchandise is delivered to. Possible values: " | ||
| - | ^**// | ||
| - | |tdsRequestorAuthenticationInformation.authenticationData |String | Authentication data of the customer. Format A-Z, a-z, 0-9 [!"# | ||
| - | |tdsRequestorAuthenticationInformation.authenticationTimestamp |DateTime | Date and time when the customer authenticated in the shop. Format JJJJ-MM-TTTHH: | ||
| - | |tdsRequestorAuthenticationInformation.authenticationMethod |String | Specifies how the customer authenticated to the shop. Possile values: " | ||
| - | ^**// | ||
| - | |tdsTransactionAttributes.purchaseInstalmentData |Integer | Maximum number of authorisations permitted for instalment payments. Format 0-9, max. 3, Wert muss > 1 sein. | | ||
| - | |tdsTransactionAttributes.recurringExpiry |Date | Date after which no further authorisations shall be carried out. Format YYYY-MM-DD. | | ||
| - | |tdsTransactionAttributes.recurringFrequency |Integer | Minimum number of days between authorisations. Format 0-9, max. 4. | | ||
| - | |tdsTransactionAttributes.type |String | Type of 3-D Secure 2.0 payment. Possible values: " | ||
| - | |||
| - | == Example of a tds2Optional string (formatted for demonstration purposes, should normally be specified in one line) == | ||
| - | < | ||
| - | { | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | }, | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | " | ||
| - | } | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | == Example of a transaction initialization == | ||
| - | {{page> | ||
| - | |||
| - | === 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 | ||
| - | |rc | ||
| - | |msg |yes | ||
| - | |reference | ||
| - | |redirect | ||
| - | ^HEADER parameter^^^^ | ||
| - | |hash | ||
| - | |||
| - | == Example in case of success == | ||
| - | {{page> | ||
| - | |||
| - | == Example in case of error == | ||
| - | {{page> | ||
| - | |||
| - | ==== Notification about the payment result ==== | ||
| - | |||
| - | The result of an initialized transaction will be submitted to the merchant through URL specified in the // | ||
| - | |||
| - | The result of the payment is contained in the field // | ||
| - | |||
| - | === Request === | ||
| - | **URL:** notifyUrl of the previous init transaction call \\ | ||
| - | **Provided by:** Merchant \\ | ||
| - | **Called by:** GiroCheckout | ||
| - | |||
| - | == GET parameters == | ||
| - | ^Name | ||
| - | |gcReference | ||
| - | |gcMerchantTxId | ||
| - | |gcBackendTxId | ||
| - | |gcAmount | ||
| - | |gcCurrency | ||
| - | |gcResultPayment | ||
| - | |gcHash | ||
| - | |||
| - | === 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) | ||
| - | |All others | ||
| - | |||
| - | ==== 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 " | ||
| - | |||
| - | === Request === | ||
| - | **URL:** redirectUrl of the previous init transaction call \\ | ||
| - | **Provided by:** Merchant \\ | ||
| - | **Called by:** GiroCheckout | ||
| - | |||
| - | == GET parameters == | ||
| - | ^Name | ||
| - | |gcReference | ||
| - | |gcMerchantTxId | ||
| - | |gcBackendTxId | ||
| - | |gcAmount | ||
| - | |gcCurrency | ||
| - | |gcResultPayment | ||
| - | |gcHash | ||
| - | |||
| - | |||
| - | ===== Other transaction types ===== | ||
| - | These transactions reference a previous transaction. | ||
| - | |||
| - | **Provided by:** GiroCheckout \\ | ||
| - | **Called by:** Merchant \\ | ||
| - | |||
| - | ==== Workflow ==== | ||
| - | |||
| - | <uml> | ||
| - | hide footbox | ||
| - | |||
| - | participant " | ||
| - | participant " | ||
| - | participant " | ||
| - | |||
| - | autonumber | ||
| - | |||
| - | shop -> girocheckout: | ||
| - | girocheckout -> cc: | ||
| - | cc -> girocheckout: | ||
| - | girocheckout -> shop: | ||
| - | |||
| - | center footer (c)2016 by GiroSolution AG | ||
| - | </ | ||
| - | |||
| - | - Shop sends reference to previous credit card transaction | ||
| - | - GiroCheckout sends transaction to credit card processor | ||
| - | - credit card processor transmits result to GiroCheckout | ||
| - | - Shop receives reply on transaction outcome ([[en: | ||
| - | |||
| - | ==== Capture ==== | ||
| - | {{page> | ||
| - | |||
| - | ==== Refund ==== | ||
| - | {{page> | ||
| - | |||
| - | === POST Parameters === | ||
| - | URL CAPTURE: https:// | ||
| - | URL REFUND: https:// | ||
| - | |||
| - | ^Name | ||
| - | |merchantId | ||
| - | |projectId | ||
| - | |merchantTxId | ||
| - | |amount | ||
| - | |currency | ||
| - | |reference | ||
| - | |purpose | ||
| - | |hash | ||
| - | |||
| - | == Example == | ||
| - | {{page> | ||
| - | |||
| - | === 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 | ||
| - | |rc | ||
| - | |msg |yes | ||
| - | |reference | ||
| - | |merchantTxId | ||
| - | |backendTxId | ||
| - | |amount | ||
| - | |currency | ||
| - | |resultPayment | ||
| - | ^HEADER parameter^^^^ | ||
| - | |hash | ||
| - | |||
| - | == Example in case of success == | ||
| - | {{page> | ||
| - | |||
| - | == Example in case of error == | ||
| - | {{page> | ||
| - | |||
| - | ==== Void ==== | ||
| - | {{page> | ||
| - | |||
| - | === POST Parameters === | ||
| - | URL VOID: https:// | ||
| - | |||
| - | ^Name | ||
| - | |merchantId | ||
| - | |projectId | ||
| - | |merchantTxId | ||
| - | |reference | ||
| - | |hash | ||
| - | |||
| - | == Example == | ||
| - | {{page> | ||
| - | |||
| - | === 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 | ||
| - | |rc | ||
| - | |msg |yes | ||
| - | |reference | ||
| - | |referenceParent | ||
| - | |merchantTxId | ||
| - | |backendTxId | ||
| - | |amount | ||
| - | |currency | ||
| - | |resultPayment | ||
| - | ^HEADER parameter^^^^ | ||
| - | |hash | ||
| - | |||
| - | == Example in case of success == | ||
| - | {{page> | ||
| - | |||
| - | == Example in case of failure == | ||
| - | {{page> | ||
| - | |||
| - | ===== Pseudo card numbers (PKN) ===== | ||
| - | <WRAP center round important 60%> | ||
| - | 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, | ||
| - | |||
| - | ==== Query pseudo card information ==== | ||
| - | This function allows access to PKN information. | ||
| - | |||
| - | **URL:** https:// | ||
| - | **Provided by:** GiroCheckout \\ | ||
| - | **Called by:** Merchant | ||
| - | |||
| - | ==== POST Parameters ==== | ||
| - | ^Name | ||
| - | |merchantId | ||
| - | |projectId | ||
| - | |reference | ||
| - | |hash | ||
| - | |||
| - | == Example == | ||
| - | {{page> | ||
| - | |||
| - | ==== 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 | ||
| - | |rc | ||
| - | |msg |yes | ||
| - | |pkn |yes | ||
| - | |cardnumber | ||
| - | |expiremonth | ||
| - | |expireyear | ||
| - | ^HEADER Parameter^^^^ | ||
| - | |hash | ||
| - | |||
| - | == Example in case of success == | ||
| - | {{page> | ||
| - | |||
| - | == Example in case of error == | ||
| - | {{page> | ||
| - | |||
| - | ===== 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: | ||
| - | |||
| - | - Carry out a normal credit card transaction (see [[# | ||
| - | - Obtain pseudo card number (PKN) (see [[# | ||
| - | - Store this PKN | ||
| - | - On the next recurring payment, initialize a payment transaction (use correct end point, see [[# | ||
| - | |||
| - | ===== Recurring transaction ===== | ||
| - | |||
| - | In order to carry out a recurring payment without customer intervention, | ||
| - | |||
| - | ==== POST Parameters ==== | ||
| - | URL https:// | ||
| - | |||
| - | ^Name | ||
| - | |merchantId | ||
| - | |projectId | ||
| - | |merchantTxId | ||
| - | |amount | ||
| - | |currency | ||
| - | |purpose | ||
| - | |type | ||
| - | |pkn |optional |String(50) | ||
| - | |recurring | ||
| - | |urlNotify | ||
| - | |hash | ||
| - | |||
| - | == Example == | ||
| - | {{page> | ||
| - | |||
| - | ==== 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 | ||
| - | |rc | ||
| - | |msg |yes | ||
| - | |reference | ||
| - | |backendTxId | ||
| - | |resultPayment | ||
| - | ^HEADER parameter^^^^ | ||
| - | |hash | ||
| - | |||
| - | == Example in case of success == | ||
| - | {{page> | ||
| - | |||
| - | == Example in case of error == | ||
| - | {{page> | ||
en/girocheckout/creditcard_3ds2/start.1608297822.txt.gz · Last modified: 2021/04/12 14:32