Enterprise allows the developer to remain in complete control over the entire payment process. The cardholder never leaves the merchants environment.
You can follow the below steps to prepare for integration to your website, shopping cart or application to the Enterprise solution:
In order to register for a live account, you will need an internet merchant account and sign up for Wirecard's payment gateway services.
For testing purposes, we have provided a MerchantUID and ApplicationUIDs in multiple currencies.
Note: If your merchant account is 3DS enabled, please ensure that you have integrated into the 3DS Lookup and Authenticate methods (Actions 14 and 15).
View all ApplicationUIDsMerchantUID: F5785ECF-1EAE-40A0-9D37-93E2E8A4BAB3
When going live, these will need to be replaced in your code by using the Wirecard issued MerchantUID and ApplicationUID.
The Web Service URL is the Wirecard API URL used to submit the web service to:
https://api.mygateglobal.com/api/
The Web Service WSDL is:
https://api.mygateglobal.com/api/?wsdl
Note: Mode 0 (test) and Mode 1 (live) can be used.
Note: Mode 1 must be used when going live.
Use the Go Live Check List to make sure that you have completed all necessary tasks before going live. Please ensure that the following criteria have been met:
Test 3D Secure Lookup and Authenticate
Test Authorise and Settle
Test transactions are visible in Wirecard Web Console
Merchant received Go Live email from Wirecard. This email will contain the merchants Customer ID and Merchant ID .
(If not, have merchant contact support.za@wirecard.com)
Ensure that you are using the Live URL.
Add referral IP address.
Web Service Mode have been changed from 0 to 1 (0 test / 1 live)
Perform Live transaction with Live card
Test Cards are used to perform test authorizations to Wirecard. Test Cards will only work when using Test Mode (0) in the live environment. Test Cards transactions will not go to the acquirer.
Test Card Types
Note: Test Cards will not work in Live Mode (Mode 1) in the Live Environment.
Visa Successful | |
Card Name | Joe Soap |
Card Number | 4111111111111111 |
Card Type | Visa |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
Visa Declined | |
Card Name | Joe Soap |
Card Number | 4242424242424242 |
Card Type | Visa |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
MasterCard Successful | |
Card Name | Joe Soap |
Card Number | 5100080000000000 |
Card Type | MasterCard |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
MasterCard Declined | |
Card Name | Joe Soap |
Card Number | 5404000000000001 |
Card Type | MasterCard |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
Amex Successful | |
Card Name | Joe Soap |
Card Number | 370000200000000 |
Card Type | AMEX |
Expiry Date | Any date in future |
CVV Number(last 3 digits on back of card) | any cvv |
Amex Declined | |
Card Name | Joe Soap |
Card Number | 374200000000004 |
Card Type | AMEX |
Expiry Date | Any date in future |
CVV Number(last 3 digits on back of card) | any cvv |
Diners Successful | |
Card Name | Joe Soap |
Card Number | 36135005437019 |
Card Type | Diners |
Expiry Date | Any date in future |
CVV Number(last 3 digits on back of card) | any cvv |
Diners Declined | |
Card Name | Joe Soap |
Card Number | 36135182434011 |
Card Type | Diners |
Expiry Date | Any date in future |
CVV Number(last 3 digits on back of card) | any cvv |
Maestro Successful | |
Card Name | Joe Soap |
Card Number | 5641821111166669 |
Card Type | Maestro |
Expiry Date | Any date in future |
CVV Number(last 3 digits on back of card) | any cvv |
Maestro Declined | |
Card Name | Joe Soap |
Card Number | 6759411100000008 |
Card Type | Maestro |
Expiry Date | Any date in future |
CVV Number(last 3 digits on back of card) | any cvv |
Visa Successful | |
Card Name | Joe Soap |
Card Number | 4000000000000002 |
Card Type | Visa |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
Visa Failed | |
Card Name | Joe Soap |
Card Number | 4000000000000010 |
Card Type | Visa |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
MasterCard Successful | |
Card Name | Joe Soap |
Card Number | 5200000000000007 |
Card Type | MasterCard |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
MasterCard Failed | |
Card Name | Joe Soap |
Card Number | 5200000000000023 |
Card Type | MasterCard |
Expiry Date | Any date in future |
CVV Number (last 3 digits on back of card) | any cvv |
As additional account security, every credit card comes with a special three or four digit code generally known as a CVV2 or CVV number. Cardholders will be requested to enter this when processing an online payment. An identity thief who has come across credit card information illegally will not have access to the CVV number if they do not have physical access to the card.
Enter the full response code below:
View all Response Codes
Illustration: Transaction Overview
Message definitions describe the general purpose, type, routing, and response information of each of the Wirecard API message type. Each Wirecard API message has 2 portions;
The below table represents the header portion of the Message that the API supports.
XML | Data Type & Length | Presence | Comments | Example Data |
<Header> | ||||
<authenticate> | ||||
<merchantUID>F5785ECF-1EAE-40A0-9D37-93E2E8A4BAB3</merchantUID> | GUID | M | Each merchant is issued MerchantUID by Wirecard. This identifies who the merchant is on Wirecard's Back Office System. | F5785ECF-1EAE-40A0-9D37-93E2E8A4BAB3 |
<merchantToken>F5785ECF-1EAE-40A0-9D37-93E2E8A4BAB3</merchantToken> | GUID | M | A merchant token is linked to your website or application. Your default token is the MerchantUID issued to you by Wirecard. | F5785ECF-1EAE-40A0-9D37-93E2E8A4BAB3 |
<actionTypeID>1</actionTypeID> | Integer (2) | M | This is used to identify what action should be performed. | 1 |
<authenticate> | ||||
</Header> |
F5785ECF-1EAE-40A0-9D37-93E2E8A4BAB3
F5785ECF-1EAE-40A0-9D37-93E2E8A4BAB3
1
The below table represents the message body message types that the API supports and indicates the entity that originates the message type.
Message Type |
Action Type |
Comments |
Processor |
Authorise | 1 |
The Authorise message creates a request to hold the requested amount and mark it as unavailable from the customer's card until it is either Captured or the hold terminates, thus rendering the amount available again. |
MG, AB, SB, NB, FNB, BC |
Authorise – Reversal | 2 |
The Authorise – Reversal Message releases the hold that the Authorize placed on the customer's credit card funds. Use this service to reverse an unnecessary or undesired Authorisation. You can use full Authorise – Reversal only for an authorisation that has not been captured. |
MG, AB, SB, NB, FNB, BC |
Capture | 3 |
When you are ready to fulfil a customer's order, Capture the Authorisation for that order. |
MG, AB, SB, NB, FNB, BC |
Sale | 5 |
A sale is a bundled authorization and capture. You can use a Sale instead of a separate Authorise and Capture if there is no delay between taking a customer's order and shipping the goods. |
BC |
Credit Capture | 4 |
A Follow-On Credit is linked to a Capture in the system. You can request multiple Follow-On Credits against a single Capture. This action would reverse a Capture – Action 3. |
MG, AB, SB, NB, FNB, BC |
Credit Sale | 12 |
Credit Request messages are generated when a merchant wants to return the funds after a transaction that has been captured (refund of a Sale - action 5). |
MG, BC |
3DS Lookup | 14 |
This message is used to verify if the issuer and cardholder participates in 3D Secure program. |
MG, AB, SB, NB, FNB, BC |
3DS Authenticate | 15 |
This message is used direct the card holder to their banks authentication page where they will validate the transaction using their secret password. |
MG, AB, SB, NB, FNB, BC |
Reports | 19 |
The Report request exposes console and internal database reporting via an API call and returns the data in an xml format. |
MG, AB, SB, NB, FNB, BC |
Visa Checkout | 20 |
This action is used when payment is made via Visa Checkout |
MG, AB, SB, NB, FNB |
Create Token | 21 |
This message is used when creating a token |
MG, AB, SB, NB, FNB, BC |
Read Token | 22 |
This message is used when reading a token |
MG, AB, SB, NB, FNB, BC |
Delete Token | 23 |
This message is used when deleting a token |
MG, AB, SB, NB, FNB, BC |
Update Token | 24 |
This message is used when updating a token |
MG, AB, SB, NB, FNB, BC |
Processor List |
||||||
Abbreviation |
MG |
AB |
FNB |
SB |
NB |
BC |
This section describes the mandatory, conditional, optional data element layouts for all message types (Actions) that the API supports.
This message is used to verify if the issuer and cardholder participates in 3D Secure program.
Wirecard offers the 3D Secure service to all of its merchants. If you are using Enterprise, you may be required to integrate to Wirecard's 3D Secure API which is included in this document.
Wirecard's payment platform is integrated to 3D Secure enabling transactions to be processed to both the MasterCard Secure Code & Verified by Visa 3D Secure schemes.
3D Secure stands for Three Domain Secure - the payment industry's internet authentication standard which has been developed by the major card schemes. Visa has called their version of the scheme 'Verified by Visa' and MasterCard have called their equivalent initiative 'MasterCard Secure Code'. These are both collectively referred to as 3D Secure.
Note: In order for a merchant to share the benefits of 3D Secure, they must request that their internet merchant account be 3D Secure enabled.
Note: 3D Secure is mandatory with certain banks.
The 3D Secure process consists of a web service call followed by a form post. Each call can bring back variable results that will form part of the next process.
High Level 3D Secure Transaction Process:
Step 1 - Shopper browses at merchant site, adds items to shopping cart, then finalizes purchase.
Step 2 - The merchant will invoke a web service (3DS Lookup) to the Wirecard's API.
Step 3 - Wirecard sends query including card number to Directory Server. This leg of the process is also commonly known as VERes.
Step 4 - If card number is in a participating card range, Directory Server queries appropriate Access Control Server (ACS) to determine whether card number is enrolled.
Step 5 - ACS responds to Directory Server, indicating whether authentication is available for the card number.
Step 6 - Directory Server forwards ACS response (or its own) to Wirecard.
Step 7 - Wirecard's will return a 3DS Lookup Response to the merchant. If cardholder is not enrolled in 3D Secure or if authentication is otherwise unavailable, the merchant submits a traditional authorization request and the 3D process ends.
Step 8 - Based on the result (issuer or card type participating), merchant initiates a form post (3DS Authenticate) that posts the values retrieved from the 3DS Lookup Response (first web service call) to the Access Control Server (ACS) via the shopper's browser.
Step 9 - ACS authenticates shopper as appropriate for the card number then formats the ACS Result message with appropriate values and digitally signs it.
Step 10a - ACS returns an ACS result (PARes) to merchant via shopper's browser.
Step 10b - ACS sends a copy of the Payer Authentication Response to the Authentication History Server.
Step 11 – Merchant process the result with authorization request to Wirecard.
This Form POST will return TransactionIndex and paresPayload values once the cardholder has correctly entered their OTP. These values will be entered into the Authorise or Sale actions (Actions 1 or 5).
Illustration: OTP Page
The ECI indicates the security level associated with an Internet purchase transaction. The 3DS Lookup & 3DS Authenticate requests will return an ECI in the response message which the merchant can use to gauge risk associated with the transaction. The payment gateway will process the ECI to the acquirer or its processor for inclusion in the authorization request message.
Note: Some ECI indicators will allow liability shift for certain transactions relating to chargebacks.
Note: Merchants can request that Wirecard block specific ECI's that do not allow for liability shift.
Merchants are recommended to store the below data as evidence in the event of a chargeback dispute relating to 3D Secure processing. The below data is returned on the 3DS Lookup & Authenticate responses.
Dispute Situation |
ECI |
Evidence |
Proof of Authentication or Authentication Attempt |
5,6,1 or 2 |
Minimum, if available: |
· Purchase Date and Time |
||
· XID |
||
· Purchase Amount |
||
· Order Description |
||
· Transaction Status |
||
· ECI |
||
· Signature Date & Time |
||
· CAVV / AAV |
The merchant will be required to initiate three 3D Secure calls as defined below:
3DS Lookup: This message is used to verify if the issuer and cardholder participates in 3D Secure program.
3DS Authenticate: This message is used to direct the card holder to their banks authentication page where they will validate the transaction using their secret password.
3DS Lookup
The standard timeout value for the 3DS Lookup to complete is ten seconds.
3DS Authenticate
The 3DS Authenticate Request message has no timeout value as it relies on the merchant's eCommerce application to determine maximum time frames for various shopping session activities.
This message is used direct the card holder to their banks authentication page where they will validate the transaction using their secret password.
The Authorise message creates a request to hold the requested amount and mark it as unavailable from the customer's card until it is either Captured or the hold terminates, thus rendering the amount available again.
A sale is a bundled authorization and capture. You can use a Sale instead of a separate Authorise and Capture if there is no delay between taking a customer's order and shipping the goods.
NOTE: Action 5(Sale) currently only works with VISA Africa. For all other banks use an Action 1 (Authorize) followed by an Action 3(Capture)
When you are ready to fulfil a customer's order, Capture the Authorisation for that order.
The Authorise – Reversal Message releases the hold that the Authorize placed on the customer's credit card funds. Use this service to reverse an unnecessary or undesired Authorisation. You can use full Authorise – Reversal only for an authorisation that has not been captured.
A Follow-On Credit is linked to a Capture in the system. You can request multiple Follow-On Credits against a single Capture. This action would reverse a Capture – Action 3.
Credit Request messages are generated when a merchant wants to return the funds after a transaction that has been captured (refund of a Sale - action 5).
The Report request exposes console and internal database reporting via an API call and returns the data in an xml format.
This message is used when payment is made via Visa Checkout.
Visa Checkout provides a single sign-in service to pay for online shopping purchases. After a simple setup, Visa Checkout users can skip inputting their payment and shipping information for their orders.
Tokenized card payments offer the card holder a simplified checkout experience. The solution caters for customers that repeatedly purchase goods or services from a merchant’s website by simplifying the checkout experience. The solution will tokenize the card holder’s details during the initial transaction. For subsequent transactions, the card holder is only required to enter their CVV to process the payment making the checkout process more simplified. At any point, the card holder can amend card details, which will update the token with the new card information.
Tokenization Process Flow
This message is used when creating a token.
This message is used when reading a token. This action can be used to check if a supplied token exists or to validate the cards expiry date.
This message is used when deleting a token.
Note: To get a successful result from this action, first call action 21 (createToken) and replace {token-to-be-deleted} with the returned token.
This message is used when updating a token.
Batch payments enable merchants to submit a batch of items with variable amounts to be debited off a credit card. This is most commonly used in industry verticals such as insurance, telecoms, media, gyms and bill payment for the collection of services rendered. In order to process credit card batch payments, sensitive card data such as PAN and Expiry date are required to be stored for subsequent transactions to be submitted. Merchants can replace cardholder data with a Wirecard token that can be used for subsequent submissions.
For security purposes, a security hash needs to be passed in the batch request. The security hash is created by adding the merchantToken, applicationUID, numberOfRecords and the orderTotal. The result is sh 256 hash encoded and passed in the securityHash field.
NOTE: Batch requests cannot exceed 32Mb. Large batches should be split into seperate requests.
The below table represents the batch item xml node wrapper name and the action it relates to.
Batch Item Node Name |
Action Type |
ccAuth | 1 |
ccAuthReversal | 2 |
ccCapture | 3 |
ccAuth | 5 |
ccCredit | 4 |
ccCredit | 12 |
ccVisaCheckout | 20 |
tokenCreate | 21 |
tokenRead | 22 |
tokenDelete | 23 |
tokenUpdate | 24 |
This message is used when submitting a batch.
Select your sample code package below:
Solution | View Code |
Enterprise | View Code |
Enterprise Tokenization | View Code |
Visa Checkout | View Code |
Merchants
If you are a merchant that has signed up with Wirecard's Enterprise solution, you will have access to Wirecard's Integration Help Desk for telephonic and email support. Telephonic support is available 8am to 5pm GMT +2. Email support is 8am to 5pm GMT + 2 and connects directly to our help desk through our ticketing system.
Enterprise allows the developer to remain in complete control over the entire payment process. The cardholder never leaves the merchants environment. Enterprise is a high performance TCP/IP payment solution that resides on your server. You can build your own API and use a web service to access the Wirecard server.
Enterprise relies on web services for the processing of transactions. A web service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-process able format (specifically WSDL). Other systems interact with the Web service in a manner prescribed by its description using SOAP messages, typically conveyed using HTTP with an XML serialization in conjunction with other web-related standards.
Enterprise requires that TLS protocol 1.2 or higher is enabled active in your application. The details of the transactions are passed to the Wirecard Payment Gateway from your website using web services. This is an efficient method of ensuring that any payment page is neatly under the control of an organisations website and an excellent way to micromanage even the smallest of details. When combined with TLS, a secure platform emerges which can be designed to work proficiently with any payment solution.
One of the main benefits of utilising the Enterprise Solution is the control over the payment page and entire payment process. It requires a higher level of integration as the merchant may be required to form part of the 3D Secure transaction process if their merchant account is 3D enabled.
Enterprise requires that the merchant host their own payment page. Once the transaction is received by Wirecard, it is then processed to the acquiring bank for authorization. The authorization message is then returned to the merchant.
Illustration: Enterprise Payment Process
Step 1 – Cardholder makes purchase from merchant's website.
Step 2 – Merchant displays payment page.
Step 2 – Merchant uses a web service to transmit data utilizing TLS protocol to Wirecard
Step 3 – Wirecard receives the transaction request and performs validation on the credit card detail and other
Data elements submitted.
Step 3 – Wirecard processes the transaction to merchant Bank.
Step 4 – The merchant bank processes the transaction and returns a successful or declined message to
Wirecard.
Step 5 – Wirecard returns this result and/or error code with error description back to the Merchant
Website address specified in the Web Service call.
Step 6 – If the notifications are enabled, (from the Wirecard Web Console) Wirecard will notify the merchant by
email of the transaction details.
Note: The entire transaction process takes around 3 seconds.
Note: The above diagram and transaction process does not include the 3D Secure process.
An Internet Merchant Account is required to accept credit card transactions over the internet. If you have an Internet Merchant Account you need to supply these details to Wirecard before going Live. If you do not have an Internet Merchant Account, Wirecard can assist you with your application to the acquirer (bank).
Note: An Internet Merchant Account is a different type of merchant account than what is used for card present / POS transactions. You will need to apply for an Internet Merchant Account even if you already accept credit card transactions from your store.
You need to apply security best business practice to ensure that confidential data and card detail are protected while either being stored in the database or while data is being transmitted. It is suggested that you encrypt key information issued to you by Wirecard such as merchant ID, application ID and transaction index.
Note: To reduce fraud or potential incidents it is recommended to encrypt any password that gives access to your server.
TLS (Transport Layer Security) and its predecessor, Secure Sockets Layer (SSL), both frequently referred to as "SSL", are cryptographic protocols that provide communications security over a computer network.
The Enterprise Solution requires a TLS 1.2 protocol or above to be enabled in your app before live transactions can be processed. Without this protocol, Wirecard will automatically fail any live transactions that are being submitted.
Storing of credit card detail is not recommended. Wirecard offers numerous payment solutions that enable merchants to maintain control over payment processing without storing card.
Note: Refer to Wirecard's Tokenization Solutions.
Note: Refer to PCI Standards for rules behind storing of card detail.
This section highlights best business practices when it comes to handling credit card information on your "Payment Page". These practices will aid in reducing cardholder finger error and also provide ability for some validation before processing to Wirecard.
When a transaction is completed the cardholder should be directed to a page that shows if the transaction was successful or declined. This is called the failure / success page. This allows the cardholder to identify whether the transaction was successful or not. The logic relating to which page to display is determined by the merchant based on the Transaction Result returned by Wirecard. In the event that the transaction result is declined, you can also display a message description informing the cardholder why the transaction was declined.
Configuration is controlled from within the Wirecard Web Console. Certain configuration is "mandatory" in order to begin trading live. Configuration for the payment gateway can be found under settings within the Wirecard Web Console. (refer to Settings – Gateway below)
NOTE: The Referral IP must be configured in the Wirecard Web Console in order for web service to be accepted. This is only required in Live mode.
Gateway settings are used to configure the Wirecard payment solutions.
Illustration: Settings - Gateway
Within this section you can configure the IP Address that you will be calling from.
The Referral IP address is the IP address that your application is being sent from. The IP address must be a static IP address. The IP address must be added in the configuration menu in order for your web service call to be accepted by Wirecard.
In this section the various payment instruments supported are listed. These are updated regularly as new payment instruments are integrated to the Wirecard platform.
The below lists the different credit card transaction types that Wirecard supports:
The Wirecard Web Console is used by merchants to manage payment gateway transactions. The console is full of rich features enabling transactional management of any Wirecard's solution or integration methods. A merchant will be issued with a user name and password for the web console when they sign up with Wirecard.
The credit card transaction process is defined mainly by an authorization and a capture. An authorize request is processed to the acquirer who in turn on processes to the issuer. If the transaction is approved / successful the issuer will reserve the funds on the credit card for 21 working days. This is called an authorization. In order for you to receive your funds (settlement), a capture request is required.
To Capture an Authorized transaction, you can either:
MasterCard and Visa require that the settlement of a credit card transaction takes place at time of delivery of the purchased product or service. If you are providing a product or service with real time delivery then deferred settlement is not required and a "Sale" action type can be used.
If you are delivering a product or service in real time, then you can use the Sale action type processing call which means you can perform one web service call that will include the authorize and capture request in the same API call.
A Sale action type eliminates the need for two web service calls (Authorize and Capture) to Wirecard. A Sale action type only requires one web service call to Wirecard.
If you are delivering a product or service in arrears, then you can use the "Deferred Settlement" process which means you will first send an authorize request to reserve the funds of the credit card. When you have delivered the goods or service you can send a capture request or capture in the Wirecard Web Console. Upon capture, Wirecard will submit the transaction for settlement to the bank.
Note: Go to https://www.wirecard.co.za/payment-solutions/payment-gateway/online-payments/ to find out more about deferred settlement.
It is important to note that certain transaction types can be processed either by the "web service" or through the "Wirecard Web Console".
From the Wirecard Web Console merchants can process:
Note: The Wirecard Web Console caters for a high level of security, user permissions and processing limits for Credits / Refunds and Captures. Based on the merchants requirements, integration to certain transaction types may not be necessary as they can be managed through the Wirecard Web Console.
Note: It is recommended that you use the Wirecard Web Console for these specific transaction types to reduce risk and potential error.
The transaction result is the transaction response returned from the request web service when sending any message type request to Wirecard. The transaction result informs you whether the transaction was successful or declined. The transaction result is often used to display to the cardholder on the failure / success page. Wirecard provides declined reason codes, error messages and in-depth message descriptions that can be displayed to merchant on the failure / success page.