Please note the Payment Provider may NOT permit processing for Non-Decimal Currencies if the "presentationAmount" does NOT contain a whole number.
Credit/Debit Card
Last changes: 07-03-2023
- Initiate Authorization
- Collect Payment Option Details via SDK
- Issuing Bank Authorizes Payment
- Complete Authorization
The authorization of a payment is initialized by calling the API method 1.38 Init Authorize.
In the example below, we authorize 3.99 EUR for a VISA credit card as part of the purchase of two premium widgets from Widgets GmbH. The shopper's full name is provided alongside their address.
Initiate Authorization Request
Path:
PUT {baseURL}/payment/initAuthorize
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
{
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_VGT284FYXV",
"programAccno": "1679541175",
"accno": "MERCHANT-DE4321",
"accnoType": "00",
"paymentOptionCode": "VISA",
"presentationAmount": 3.99,
"presentationCurrCode": "EUR",
"presentationUsage": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95.",
"useDifferentBillingAddress":true,
"customerFullName": "Jacob Smith",
"emailAddress": "user@example.com",
"addr1":"Anystreet",
"houseNumber":"321",
"city":"Anycity",
"countryCode":"DE",
"postCode":"12345",
"localDate": "2018-10-15",
"localTime": "155107",
"custom1": "WVWZZZ3BZWE689725"
}
In the case of a credit card payments, it is possible to omit the payment option code. The SDK will auto detect the credit card provider on the basis of the entered credit card number.
In line with Strong Customer Authentication (SCA), it is now required that real customer information be accurately provided - i.e. "useDifferentBillingAddress" must be set to true, making the below parameters mandatory:
- customerFullName
- addr1
- houseNumber (if not included in "addr1")
- city
- postCode
- countryCode
It is advised that "emailAddress" also be provided, with accurate customer data.
Please discuss with you business contacts when providing accurate data may not be possible in production, as it may result in transactions being rejected.
More information on Mandatory and Optional parameters can be found in the 3D-Secure v2.x Requirements section.
If the value of "countryCode" is "US" (United States of America) or "CA" (Canada) the "state" parameter is required. The value of "state" must be a valid State Code. (ex. "countryCode": "US", "state": "NY",)
The maximum character length of the presentation usage (see variable "presentationUsage" in the example above) varies between payment options i.e. it may be that with certain payment options the specified presentation usage may be less than 127 and consequently be truncated. It would thus be strongly recommended that the most pertinent information be placed at the beginning of the presentation usage. To be compatible with most payment options we suggest, that the presentation usage may already be truncated at the 22nd character.
Initiate Authorization Response
Status Code:
201 (Created)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"programAccno": "1679541175",
"accno": "MERCHANT-DE4321",
"uniqueReference": "BNkk4BRkQEufPSvgf9lDwA",
"loadAccountReference": "NvPoE85cZE6FguOfrC7Fmw",
"authorizationToken": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
"paymentOptionCode": "BNKACCT",
"paymentOptionCode": "VISA",
"presentationAmount": 3.99,
"presentationCurrCode": "EUR",
"presentationUsage": "Purchase:2xPremiumWidgets. Merchant:WidgetsGmbH. CUSTREF:52650FD95.",
"custom1": "WVWZZZ3BZWE689725",
"statusCode": "RECEIVED",
"paymentProviderResponse": {
"result": {
"code": "000.200.100",
"description": "successfully created checkout"
},
"buildNumber": "b5487567b639c21ffd60a5f42c484f3276ff93b3@2018-10-11 13:50:52 +0000",
"timestamp": "2018-10-15 13:55:51+0000",
"ndc": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
"id": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01"
},
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_VGT284FYXV",
"localDate": "2018-10-15",
"localTime": "155550",
"sysDate": "2018-10-15",
"sysTime": "135551",
"responseCode": "0000",
"responseDescription": "Successful execution",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}The response includes the desired authorization token under the return parameter "authorizationToken" which is used to collect payment option details via the SDK and alongside the "uniqueReference" is required to complete the authorization of the initiated transaction. The transaction reference under the return parameter "uniqueReference" is furthermore required for the following API calls. Beyond this use, it should be persisted if possible, as it enables the identification of the transaction should the need arise at a later stage.
The SDK renders a customizable payment form and sends the entered payment details directly from the customer's browser to the Acquirer. This prevents, that you must fulfill the comprehensive requirements of the PCI DSS. We offer SDKs for the integration into websites as well as mobile applications (Android and iOS).
The example below shows only the relevant part of the Web SDK implementation for Guest Payments with credit card. A complete and detailed description of the Web SDK can be found here.
The authorization token returned by the API method 1.38 Init Authorize which initiated the transaction is used to associate the payment option details collected via the Web SDK with the transaction.
Collect Payment Option Details via WebSDK
cw.PaymentForm(container,
{
authorizationToken: "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
callbackUrl: "https://www.example.com/Checkout/CompleteOrder",
confirmationUrl: "https://www.example.com/ConfirmOrder",
paymentOptionCodes: ["VISA"],
locale: "en-US",
paymentProviderMode: "test",
submitButtonTitle: "Continue",
onError: function(message)
{
console.log(message);
}
}
);
In the case of an omitted Payment Option Code in step 1. Initiate Authorization, specify all allowed credit card providers in the SDK (e.g. paymentOptionCodes: ["VISA","MSTRCRD","AMEX"]). Hence, the credit card scheme will be auto detected on the basis of the entered credit card number.
The "confirmationURL" can be replaced with the desired URL which will display the payment confirmation page. Note, that in most cases the display of a payment confirmation page is not mandatory (see 3. Payment Confirmation Page for further information). Do not specify a “confirmationURL” to skip this step.
The "callbackURL" should be replaced with the URL identifying the server side method which will call the next API method to complete the authorization (see 5. Complete Authorization).
Note, that authorization token is attached to the “callbackUrl” (as query string parameter “id”) and the “confirmationUrl” (as query parameter “authorizationToken”). This approach avoids having to persist this variable on the server side and is thus recommended practice.
After the shopper submits the payment form by clicking the button labeled with the value of "submitButtonTitle" (see example above), he is redirected to the specified “confirmationURL” or “callbackURL”, respectively.
The Payment Confirmation Page enables the collection of payment details prior to the payment i.e. allowing the shopper to review their purchase details prior to finally committing to the payment.
Depending on your location, the display of a payment confirmation page may be mandatory. Please seek assistance by contacting legal counsel should you be unsure of the legal requirements in your country. Do not specify a "confirmationURL" to skip the confirmation page.
You can integrate the payment confirmation button in a few lines of client-side code.
Payment Confirmation Page Example
<form id="confirmation">
<button type="submit">Pay now</button> <!-- confirmation button -->
<form>
<script src="cwPaymentForm-5.3.1.js"></script> <!-- add cwPaymentForm script -->
<script type="text/javascript">
var form = document.getElementById("confirmation"); // Find a confirmation form
try {
// Configure the confirmation form
cw.PaymentConfirmation(form, {
paymentProviderMode: "test" // use "live" for a release version
});
} catch (e) {
document.write(e);
console.log(e);
}
</script>
The embedded form in the body of your HTML site will create a confirmation button. The forwarded authorization token in the “confirmationUrl” (as query parameter “authorizationToken”) associates the payment confirmation page with the payment option details previously collected via the Web SDK.
If 3-D Secure is supported, the shopper will be redirected to complete the 3-D Secure Authentication process as soon as they click the button labelled "PAY NOW" on the Payment Confirmation Page.
When configuring Content Security Policy consider 3-D Secure Verification will redirect to the Customer's Issuing Bank in order to Authorize the Transaction.
The acquiring bank transmits the data to the issuing bank via the card scheme. Based on the validity of the card, the transaction, as well as the cardholder’s available funds, the credit card issuer can approve or decline the transaction. If the transaction is authorized, the respective amount is blocked on the credit card and is no longer available for other charges. Afterwards, the acquirer receives an authorization response.
With the payment option details collected and the payment authorized, the shopper is redirected to the previously specified “callbackURL”.
Since the SDK sends the payment details directly to the acquirer, where the payment is subsequently processed, you have no knowledge about the current status of the payment and if it got authorized. Therefore, call the API method 1.39 Complete Authorize from your server-side method behind the “callbackURL”, which you specified in the SDK.
Complete Authorization Request
Path:
POST {baseURL}/payment/BNkk4BRkQEufPSvgf9lDwA/completeAuthorize
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJhbGciOiJSUzI1NiI{abbreviated}RW5kVG9rZW4=
{
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_JYFGRFTQXM",
"authorizationToken": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01",
"localDate": "2018-10-15",
"localTime": "155550"
}
The transaction authorization is identified by the "uniqueReference" and "authorizationToken" returned initially by the API method 1.38 Init Authorize. Instead of saving these variables on your server-side, pass them via the query string parameters in the “callbackURL”.
In some cases e.g. where the user's device loses internet connectivity, the redirect to the specified “callbackURL” does not take place. To prevent the transaction expiring despite it being successful, the API method 1.39 Complete Authorize should automatically be called from your backend 28 minutes after 1.38 Init Authorize has been called, and the payment process completed.
Complete Authorization response
-
Status Code:
-
200 (OK)
-
Header:
-
Content-Type: application/json
Accept-Language: en-US
{
"initiatorAccno": "1679541175",
"accno": "1679797975",
"uniqueReference": "BNkk4BRkQEufPSvgf9lDwA",
"initiationCountryCode": "DE",
"initiationCountryCode3": "DEU",
"processedAmount": 3.99,
"processedCurrCode": "EUR",
"statusCode": "AUTHORIZED",
"statusReason": "Request successfully processed in 'Merchant in Integrator Test Mode'",
"paymentProviderResponse": {
"id": "8ac7a4a26668b22f0166780ef9b571d1",
"paymentType": "PA",
"paymentBrand": "VISA",
"amount": "3.99",
"currency": "EUR",
"descriptor": "BNkk4BRkQEufPSvgf9lDwA",
"merchantTransactionId": "BNkk4BRkQEufPSvgf9lDwA",
"result": {
"code": "000.100.110",
"description": "Request successfully processed in 'Merchant in Integrator Test Mode'"
},
"card": {
"bin": "402400",
"last4Digits": "9550",
"holder": "Jacob Smith",
"expiryMonth": "04",
"expiryYear": "2022"
},
"customer": {
"ip": "198.51.100.0"
},
"threeDSecure": {
"eci": "06"
},
"customParameters": {
"SHOPPER_EndToEndIdentity": "a3eb5306fcaee2ffb589204ffdc9819ec5f29bd5853923e38adef0aa106e1680",
"CTPE_DESCRIPTOR_TEMPLATE": "${TRANSACTION_ID}"
},
"risk": {
"score": "0"
},
"buildNumber": "b5487567b639c21ffd60a5f42c484f3276ff93b3@2018-10-11 13:50:52 +0000",
"timestamp": "2018-10-15 14:08:59+0000",
"ndc": "82C7C9F6C203F779BDE0F3F975C5C7B6.uat01-vm-tx01"
},
"partnerReference": "DEV-SVR001-DE_CUSTID-KD97TH2FP6_CARTID-PYQRTGMCMQ_JYFGRFTQXM",
"localDate": "2018-10-15",
"localTime": "160910",
"sysDate": "2018-10-15",
"sysTime": "140910",
"responseCode": "0000",
"responseDescription": "Successful execution",
"additionalInformation": {
"requestId": "aff2728481a181dc36daedc14055b516"
}
}
Note, that the 1.39 Complete Authorize response includes the internal representation of the Account Number (indicated by the parameter Account Number Type).
The response includes the Transaction Status under the return parameter "statusCode", which at this point should be set to "AUTHORIZED" and indicates that the payment was authorized.
Please note if "responseCode": "0035" is returned this indicates the transaction is already "Authorized" and it should be treated as a Successful Response.
This can occur if 1.39 Complete Authorize is called twice, or if the authorization was automatically completed 28 minutes after 1.38 Init Authorize.
In such a case it is safe to continue with 1.29 Capture.