Implementing Mastercard payment gateway services
This area contains technical overview of MasterCard Payment Gateway Services's products and services.
Bank card processing
The Bank Card Service allows you to authorise a card payment in real time and settle the funds next day or later. Successful payments can be refunded without the need to store sensitive card details. The service can be seamlessly integrated into your systems, enabling your customers and Customer Service teams to experience fast and efficient processing and management of transactions.
There are two parts to the Bank Card Service: authorisation and settlement.
Obtaining an Authorisation Code
Once the payment details have been collected and sent to MasterCard Payment Gateway Services, they are immediately sent to your Acquiring Bank for authorisation. Your Bank forwards the request to the Card Issuing Bank. The Issuing bank check the card details against their own systems and return an authorisation code if they approve the transaction. The full transaction response including the authorisation code is then passed back to your system via your Bank and MasterCard Payment Gateway Services. The entire process typically takes less than two seconds.
Once the authorisation code has been issued, the funds for that transaction are reserved for you - this means that even if the card subsequently becomes over it's limit, the funds are still available for you. Each authorisation code remains valid for typically between one and ten working days, after which the funds will become available to the card holder again if the transaction has not been settled. Further details on the timescales involved can be obtained from your Acquirer if required.
Settling the Transaction
To transfer the money between you and your customer, the authorised transaction needs to be settled by your Acquiring Bank.
Each day, MasterCard Payment Gateway Services collate all the authorised transactions and submit them to your Acquiring Bank, who then settle the transactions. This process takes place every working day at midnight, which means that transactions are settled next working day.
Your Acquirer will typically take three to five working days to settle the transaction. Please contact your Acquirer for more information regarding settlement times.
Settlement does not take place on English Bank Holidays - a list of Bank Holidays is available from the Department of Trade and Industry.
Requirements
Before you can go live with this service, you will need the following:
A MasterCard Payment Gateway Services account.
A merchant account or merchant ID (MID) with one of the Acquiring Banks that MasterCard Payment Gateway Services are integrated with.
A complete list of Acquiring Banks supported by MasterCard Payment Gateway Services is available here.
Transaction Processing Models
There are two types of Transaction Processing Models which can be used to submit new card payments to MasterCard Payment Gateway Services. One Stage processing - the transaction is authorised and then settled. If you are using this model, you will only need to contact the MasterCard Payment Gateway Services servers once.
Two Stage processing - the transaction is authorised, but settlement is delayed until you are ready to proceed. If you are using this model, you will need to contact the MasterCard Payment Gateway Services servers twice - once for authorisation and again for settlement.
Either model can be used for each transaction. There are no restrictions, extra service charges or additional account configuration.
Each time a transaction is submitted to the MasterCard Payment Gateway, it contains the information that determines the model to be used for that transaction. This ensures you have the flexibility to mix and match models as required on an individual transaction basis.
In both models, the authorisation request is returned to you in real time. The difference between each model lies in the settlement process.
Once a transaction has been submitted to MasterCard Payment Gateway Services, it can be refunded or cancelled if required. This is available to both processing models without additional account configuration.
One Stage Processing
The One Stage model will send transaction details to your Acquiring Bank for settlement on the next working day. This process will charge or refund the card holder without requiring any additional action from yourselves.
Situations in which this could be implemented include:
Instant access services - such as software downloads
Ticketing systems - such as airline and train reservation services
Physical goods that will be shipped same day
The transaction types that can be used with the one stage model are:
Transaction Type |
Affect |
Uses |
---|---|---|
auth |
Debits the Card |
Requests authorisation and settles transaction the next working day |
refund |
Credits the Card |
Returns funds to the card holder. The transaction is settled next working day |
Two Stage / Delayed Processing
The delayed settlement model enables you to settle the transaction at your convenience. The transaction is authorised, but is not automatically settled. Settlement takes place once the second stage has been initiated by your systems.
Situations in which this could be implemented include:
Ordered Items are not currently available
Additional in-house processes need to be completed prior to settlement
The transaction types that can be used with the two stage model are:
Transaction Type |
Affect |
Uses |
---|---|---|
pre |
Debits the Card |
Reserves funds on the card, but does not settle the transaction until a valid fulfillrequest is received. |
erp |
Credits the Card |
Creates a refund request, but does not settle the transaction until a valid fulfillrequest is received. |
fulfill |
Completes the two stage process |
Initiates settlement of a valid pre or erptransaction. The transaction is settled next working day |
The card details are only required for the pre and erp transactions types, they are not required to fulfill the transaction.
Refunding without Card Information
MasterCard Payment Gateway Services provide a specific transaction type to allow successful transactions to be refunded without needing the full card details. This enables refunds tobe performed on existing transactions without the need to store the full card details.
Transaction Type |
Affect |
Uses |
---|---|---|
txn_refund |
Credits the Card |
Uses an existing transaction to returns funds to a card. The transaction is settled next working day |
The original transaction can either be completely or partially refunded, and multiple refunds can be performed on one transaction until the full value of the transaction has been refunded.
Cancelling Payments
One stage transactions and completed two stage transactions can be prevented from debiting (or crediting) the card using the cancel transaction type. This will prevent an authorised transaction from being settled and can therefore only be used before the transaction has been settled.
Situations in which this could be implemented include:
Customer cancellations - for systems allowing the customer to cancel an order after placement
Physical Shipment - if at shipment the goods are found to be damaged, the payment can be cancelled
Transaction Type |
Affect |
Uses |
---|---|---|
cancel |
Prevents settlement of a transaction |
Stops one stage and completed two stage transactions from being settled |
Prevents an uncompleted two stagetransaction from accidental fulfillment |
As a cancelled transaction will not be settled, the reserved funds will be returned to the customer after one to ten working days.
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Performing an Initial Card Transaction
For the Bank Card service, the following information needs to be collected from the card holder for every transaction:
the card number
the expiry date of the card
the start date - if present on the card
the issue number - if present on the card
To allow you to ensure each item of information required for each card is provided, MasterCard Payment Gateway Services provide the CardInfo files. Each time a payment is entered on to your system, these files can be used to ensure all the required fields have been completed before the transaction is submitted to MasterCard Payment Gateway Services. These files also contain other information which can be utilised if required. Further information about the CardInfo files is available in the Developers Area.
In addition to the card information collected from the customer, these details about the transaction are also required:
the value and currency of the transaction
a unique reference number generated by your system - to allow the transactions to be distinguished from each other
the transaction type - to allow MasterCard Payment Gateway Services to use the correct processing model. One ofpre, auth, erp or refund
Completing the Two Stage Process
To settle a transaction processed using the Two Stage process, a fulfill is needed. This informs MasterCard Payment Gateway Services that you wish to proceed with the transaction. Once this has been done, the card will be charged. Only successful pre anderp transactions can be fulfilled.
To fulfill a transaction, information from the result of the original pre / erptransaction is required, in addition to the transaction type:
the MasterCard Payment Gateway Services reference
the authorisation code
the transaction type - fulfill
Transactions are normally fulfilled for the full value of the original transaction. If you wish to perform a partial fulfill, this can be done by specifying theamount in the fulfill request. Each transaction can be fulfilled once.
Refunding without Card Information
The txn_refund transaction type uses a successful transaction to perform a refund, instead of requiring the card details. The reference number returned to you by MasterCard Payment Gateway Services when submitting the original transaction is used to locate the card details.
Any successful auth or completed pre-fulfill transaction can be refunded in this fashion, provided they have not been cancelled.
To txn_refund a transaction, information from the result of the original transaction is required, in addition to the transaction type:
the MasterCard Payment Gateway Services reference
the transaction type - txn_refund
Transactions are normally refunded for the full value of the original transaction. If you wish to refund a lower value, this can be done by specifying the amount in the txn_refund request. Each transaction can be refunded several times, provided the total refunded does not exceed the value of the original.
Cancelling Transactions
To cancel a transaction prior to settlement, information from the result of the original transaction is required, in addition to the transaction type:
the MasterCard Payment Gateway Services reference
the transaction type - cancel
Response Codes
There are three basic Bank Responses for transactions:
Accepted
Declined
Referred
In addition there are various error codes that can be produced by this service. Examples of each response type available in the Developers Guide.
Accepted Transactions
Once a transaction is accepted, your system can complete the normal ordering process. If you are using the Two Stage model, please remember that the second stage must be completed to debit / credit the card.
Declined Transactions
Occasionally, you may find a transaction is declined. There are several general reasons why a card may be declined. These include:
The card has been cancelled
The card is approaching or is past its limit and does not have enough funds to cover the full value
The Issuing bank have noticed unusual patterns of spend on the card
If a transaction is declined, MasterCard Payment Gateway Services return the full bank response to you. You may wish to encourage the user to try another card, or to re-try at a later date.
Referred Transactions
A referral response is part way between an accepted and a declined response. The Issuing Bank does not wish to automatically issue an authorisation code, but is providing you with the opportunity to receive a manual authorisation instead of simply issuing a decline response. To proceed with the payment, you should phone the authorisation centre of your Acquiring Bank - not the cardholders bank - with the card details.
For an auth, the transaction can then be continued by sending an authorize_referral_request transaction, specifying the authorisation code provided by the authorisation centre. For a pre, the transaction can be completed by including the authcode in the fulfill transaction, or by an authorize_referral_request which is followed at a later date by a fulfill. Alternatively, the transaction could be entirely resubmitted to MasterCard Payment Gateway Services with the authorisation code.
Additional services, such as AVSCV2 or ReD may also prevent the transaction being authorised. If this is the case, you will not be able to issue fulfill or authorize_referral_requesttransactions to continue processing.
Like the declines MasterCard Payment Gateway Services return the full bank response to you.
The main reasons for a referral are:
the Issuer is performing a spot check
the card is approaching its limit
If you are designing a fully automated system, you may wish to simply treat these transactions in the same way as a decline. This requires no extra action on your part.
Error Messages
A complete list of Response Codes for this service is available here. The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate on how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The transactions are detailed in the Bank Card section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Summary - gives a summary of the transactions
List - shows specific details of the transactions
Details - shows full details of each transaction
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Fraud screening
This page enables you to quickly determine which fraud screening mechanisms are available for each of the Payment Services provided by MasterCard Payment Gateway Services.
The URU Fraud Screening Service is available as a separate transaction type. This enables the service to be used before the transaction payment is attempted. This means the URU Service can be used before any of the Services listed.
Service |
Payer Authentication |
||
---|---|---|---|
Bank Card |
|||
Corporate Purchasing Cards |
|||
Airlines |
|||
Pre-Registered Cards |
n/a |
n/a |
|
Capture Method |
with limitations |
with limitations |
|
Historic |
with limitations |
n/a |
|
Fire and Forget |
n/a |
n/a |
|
Batch Input |
AVS only |
n/a |
AVSCV2
AVSCV2 can be used with any Card Payment Service transaction, provided:
The card number is provided with the transaction
The CV2 number is not stored
Due to these two limiting factors, the AVSCV2 Service is not available in the following situations:
With Pre-Registered Cards Service
For merchants using the Pre-Registered Service, the AVSCV2 check can only be performed on the initial transaction, as this check cannot be performed with a Pre-Registered transaction. Providing you have performed the AVSCV2 check with the initial transaction, this does not impact the security of the transactions.
The CV2 number for a particular card will only change if the card is re-issued. When a card is re-issued, the validity (ie the expiry date and start date) of the card would also change. This means the card details stored by the DPG are no longer correct and a new transaction will need to be performed to use as the basis for future pre-registered transactions - the new CV2 number can be checked at this stage.
With Capture Method Recurring Transactions
As the CV2 number cannot be stored, the cv2 check should only performed if the customer is able to re-enter the details at the time of the transaction. This means there is limited scope to perform a cv2 check with a cont_authtransaction.
With Historic Recurring Service
Merchants using the Historic Recurring Service should perform the AVSCV2 check with the initial setup transaction.
With Fire and Forget
With the Fire and Forget Service, neither the initial setup or the repeat payments can be performed with AVSCV2 checking, as the initial authorisation request is not processed immediately, but at a later date.
If you wish perform an AVSCV2 check, this can be done by performing a normal Bank Card transaction with AVSCV2 first, and then set up the Fire and Forget Service to take a payment fewer.
With Batch Input Services
The AVS check can be performed - where appropriate - for Batch Input transactions if these details are provided along with the card number. If your Acquiring Bank supports the Extended AVS check, this can be used if you are using the XML format for the batch. The Standard AVS check is available to all Acquiring Banks.
Please Note - as the Card Scheme Rules state that the CV2 should not be stored, this information cannot be accepted when using the Batch Input Service.
3-D Secure
3-D Secure can be used with any Card Payment Service transaction, provided:
The card number is provided with the transaction
The transaction is an e-Commerce transaction
The authorisation is carried out immediately
Due to these limiting factors, the 3-D Secure Service is not available in the following situations:
With Pre-Registered Cards Service
For merchants using the Pre-Registered Service, the 3-D Secure check can only be performed on the initial transaction, as this check cannot be performed with a Pre-Registered transaction. Providing you have performed the 3-D Secure check with the initial transaction, this does not impact the security of the transactions.
With Capture Method Service
MasterCard and Visa do not currently support 3-D Secure checking for recurring transactions. However the check can still be performed on the initiale-Commerce transaction.
With Historic Recurring Service
It is not currently possible to perform a 3-D Secure check with this service.
With Fire and Forget
With the Fire and Forget Service, neither the initial setup or the repeat payments can be performed with 3-D Secure checking, as the initial authorisation request is not processed immediately, but at a later date.
If you wish perform a 3-D Secure check, this can be done by performing a normal Bank Card transaction with 3-D Secure first, and then set up the Fire and Forget Service to take a payment fewer.
With Batch Input Services
The 3D Secure service enables your customer to authenticate themselves directly their Issuing Bank in real time. This means the service cannot is not available in conjunction with batched transactions.
3D Secure
3-D Secure is an authenticated payment system to improve online transaction security and encourage the growth of e-commerce payments. Collectively Visa, MasterCard and AMEX secure systems are brand identities of the 3-D Secure Cardholder Authentication Scheme.
3-D Secure systems recreate the high level of security of a physical payment environment by requesting further payment authentication. The objective is to provide a safe and secure online payment experience across all three domains using a password that is validated by the card issuer and further checked by all other parties involved in the transaction.
How does 3-D Secure work?
3-D Secure uses Three Domain and SSL Technology to provide a standardised and secure method of performing transactions over the internet. These systems are in place to protect all parties including the merchant, card holder and the banks of the cardholder and merchant against unauthorised use.
Without these measures AMEX, VISA and MasterCard are not compliant with card scheme rules and are liable to pay heavy fines from acquiring banks. These measures have been put in place to enhance convenience, acceptance and security.
Features
- Supports Verified by Visa, MasterCard SecureCode and AMEX SafeKey
- Pre-accredited with majorAcquiring Banks
- Easily integrated with MPI(Merchant Plug In) to MasterCard Payment Gateway Services Payment Gateway
- Fully outsourced solution whichis maintained by MasterCard Payment Gateway Services
- Facilitates International anddomestic Maestro processing
Benefits
- Protects cardholder against unauthorised use
- Added layer of fraud protection
- Shift fraud liability from your business with chargeback protection on qualifying transactions
- Increase customer confidence when shopping online
- Resides on secure, reliable and resilient DPG
- Consolidated MasterCard Payment Gateway Services customer support
- Potential to negotiate lower rates for 3-D secure transactions with your acquiring bank
3D Secure MPI Service
This Service enables the cardholder, you and the card Issuing Bank to authenticate each other prior to the authorisation of a transaction.
Instead of installing and integrating new software with your systems, you use an extension to the MasterCard Payment Gateway designed specifically for this purpose. This software is called the MasterCard Payment Gateway Services MPI.
When this Service is incorporated into the authorisation process, there are four stages to the normal transaction cycle: card enrolment check, cardholder verification, authorisation and settlement.
Card Enrolment check
Once the payment details have been collected and sent to MasterCard Payment Gateway Services, they are immediately forwarded by the MasterCard Payment Gateway Services MPI to the Directory Server which determines whether the card is enrolled within the 3-D Secure system.
The results of this check are passed back to your systems via the MPI. If the card is enrolled, this message will include the payment authentication request(PAReq), which contains the details required to re-direct the card holder to theAccess Control Server (ACS) for their Issuing bank. It also contains the information required to re-direct them back to your own site, once authentication has been completed.
Cardholder Verification
If the card is enrolled for 3-D Secure, your systems will use the PAReq to re-direct the card holder to the ACS page provided by their Issuing Bank. This page enables the card holder to authenticate themselves directly with their bank.
Once the authentication process is complete, the ACS re-directs the card holder back to your website. This re-direction process also passes back the payment authentication response (PARes) which is generated by the Issuer, and contains information about the result of the check.
For cards which are not registered for 3-D Secure, your system may automatically proceed directly to authorisation if required.
Authorisation
Once the verification process has been completed, the PARes is forwarded to the DPG by your system. It is then checked to ensure it genuinely came from the Issuer and that the cardholder successfully authenticated themselves. If the verification was successful, the transaction is sent to your Acquiring Bank for authorisation. Your bank forwards the request to the Issuing Bank, who return an authorisation code if they approve the transaction.
If the cardholder was unsuccessful in their verification attempt or the PARes is somehow invalid, the transaction will not be sent for authorisation.
The full transaction response - including the authorisation code if the transaction is successfully authorised - is then passed back to your system by the DPG.
Settlement
Successfully authorised transactions are settled next working day, in the same way as transactions which have not been checked using 3-D Secure.
Requirements
Before you can go live with this service, you will need the following:
a MasterCard Payment Gateway Services e-Commerce account
the account to be configured with the 3-D Secure service
the account to be configured to use the MasterCard Payment Gateway Services MPI
to be a registered 3-D Secure merchant with your Acquirer, for the specific card schemes
The 3-D Secure check is currently available for certain Acquiring Banks and card schemes. These are outlined in the table below:
Acquiring Bank |
Card Scheme |
---|---|
Barclays |
MasterCard, Visa |
HBOS |
MasterCard, Visa |
HSBC |
MasterCard, Visa |
Lloyds TSB |
MasterCard, Visa |
Royal Bank of Scotland Group (includes NatWest) |
MasterCard, Maestro International, Visa |
Transaction Processing Models
There are two types of Transaction Processing Model which can be used to submit new card payments to MasterCard Payment Gateway Services using the 3-D Secure service:
One Stage 3-D Secure - the enrolment check is performed, the transaction is authorised and then automatically settled. The enrolment check is initiated using the auth transaction type.
Two Stage 3-D Secure - the enrolment check is performed, the transaction is authorised, but settlement is delayed until you are ready to proceed. The enrolment check is initiated using the pre transaction type, and settlement is initiated using a fulfill transaction.
Either model can be used for each transaction. There are no restrictions, extra service charges or additional account configuration.
Each time a transaction is submitted to the MasterCard Payment Gateway, it contains the information that determines the model to be used for that transaction. This ensures you have the flexibility to mix and match models as required on an individual transaction basis.
In both models, the card enrolment check and authorisation request is returned to you in real time. The difference between each model lies in the settlement process.
Once a transaction has been submitted to MasterCard Payment Gateway Services, it can be refunded or cancelled if required. Refunds and cancellations are processed in exactly the same way as for Bank Card transactions.
One Stage 3-D Secure
The One Stage 3-D Secure model will send successful transaction details to your Acquiring Bank for settlement on the next working day.
Situations in which this could be implemented include:
Instant access services - such as software downloads
Ticketing systems - such as airline and train reservation services
Physical goods that will be shipped same day
The transaction types that can be used with this model are:
Transaction Type |
Effect |
---|---|
auth |
Requests a card enrolment check |
threedsecure_authorisation_request |
Submits the PARes and initiates the authorisation and settlement process on the existing auth. The transaction will be settled (if approved) automatically.
|
Two Stage 3-D Secure
The delayed settlement model enables you to settle the transaction at your convenience. The transaction is authorised, but is not automatically settled. Settlement takes place once the final stage has been initiated by your systems.
Situations in which this could be implemented include:
Ordered Items are not currently available
Additional in-house processes need to be completed prior to settlement
The transaction types that can be used with the two stage model are:
Transaction Type |
Effect |
---|---|
pre |
Requests a card enrolment check |
threedsecure_authorisation_request |
Submits the PARes and initiates the authorisation process on the existing pre, but does not settle the transaction until a valid fulfill request is received
|
fulfill |
Initiates settlement of the transaction. The transaction is settled next working day |
Referred Authorisation
MasterCard Payment Gateway Services provide a specific transaction type to enable referred 3-D Secure transactions to be processed. This transaction type retains any liability shift confered by the check and means the card details do not need to be re-entered.
Transaction Type |
Effect |
---|---|
threedsecure_authorize_referral_request |
Enables an authorisation code obtained directly from the bank to be supplied for a transaction |
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
The transaction types fulfill, cancel, refund, erp and txn_refund are all performed as outlined in the Bank Card Service - no extra information is required for these transaction types.
Card Enrolment Request
When you wish to check whether a card is enrolled for 3-D Secure, an auth orpre transaction with the normal transaction and card information should be submitted, in the exactly the same way as for the Bank Card Service.
In addition to this, extra information about the transaction is required:
verification status set to yes - to verify the transaction
the device category - whether the site is being accessed via a web browser, or a mobile phone browser
the date & time
your website URL - this will be displayed to the cardholder when they are redirected to complete the verification process
a simple description of the product or service being purchased
details of the headers accepted by the browser
the web browser platform & version
Authorisation Request
In order to proceed to authorisation, a threedsecure_authorisation_requesttransaction is needed. This needs two pieces of information:
the MasterCard Payment Gateway Services reference from the original transaction
the transaction type - threedsecure_authorisation_request
And for cards which are enrolled, the PARes must also be submitted with this transaction.
If the card was not enrolled or is in a scheme for which the 3-D Secure check is not available, a PARes will not be generated and cannot be supplied.
In a very small number of cases, the ACS may not be able to perform the verification process. These transactions would normally be automatically rejected. If you wish to accept this outcome to a transaction, this can be indicated in the card authorisation request.
Referred Authorisation
To process a threedsecure_authorize_referral_request, three pieces of information are required:
the transaction type - threedsecure_authorize_referral_request
the MasterCard Payment Gateway Services reference from the original transaction
the authorisation code received from your Acquirer
By-Passing 3-D Secure
If you wish to by-pass the 3-D Secure check for a particular transaction, this may be done by setting:
verification status set to no
along with a normal auth or pre transaction.
Response Codes
Each stage of a 3-D Secure transaction has its own response types, which are described below.
A complete list of Response Codes for this service is available. The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Enrolment Checks
There are two basic responses for the enrolment check:
enrolled
not enrolled
Examples of each response type are available in the Developers Guide.
Authorisation Requests
An authorisation request may generate the three basic bank responses described in the Bank Card Service:
Authorised
Referred
Declined
Errors may also be generated at this stage.
Reporting
When a transaction has been checked using the 3-D Secure service, the details of the check will be available for each transaction on the Bank Card Details page
The Support Centre contains full hints and tips to help you get the most out of Reporting
3D Secure MPI Service
This Service enables the cardholder, you and the card Issuing Bank to authenticate each other prior to the authorisation of a transaction.
By using this Service, you can continue to use MasterCard Payment Gateway Services as your Payment Service Provider if you choose to purchase and use a Merchant Server Plug-in (MPI) from a third party supplier instead of the MasterCard Payment Gateway Services MPI.
When this service is incorporated into the authorisation process, there are four stages to the transaction cycle: card enrolment check, cardholder verification, authorisation and settlement. The first two steps are completed before the transaction is submitted to the DPG.
Card Enrollment check
Once the payment details have been collected, the third party MPI which is installed within your system contacts the Directory Server which determines whether the card is enrolled within the 3-D Secure system.
If the card is enrolled, your third party MPI will generate a payment authentication request (PAReq), which contains the details required to re-direct the card holder to the Access Control Server (ACS) for their Issuing bank. It also contains the information required to re-direct them back to your own site, once authentication has been completed.
Cardholder Verification
If the card is enrolled, your systems will use the PAReq to re-direct the card holder to the ACS provided by their Issuing Bank. This page enables the card holder to authenticate themselves directly with their bank.
Once the authentication process is complete, the Issuing Bank re-directs the card holder back to your website. This re-direction process also passes back the payment authentication response (PARes) which is generated by the Issuer, and contains information about the result of the check. Your third party MPI will then check the PARes to ensure it genuinely came from the Issuer and that the cardholder successfully authenticated themselves
For cards which are not registered for 3-D Secure, your system may automatically proceed directly to authorisation if required.
Authorisation
Once the verification process has been completed, your system submits the card details to the DPG, along with details taken from the PARes. The transaction is then sent to your Acquiring Bank for authorisation. Your bank forwards the request to the Issuing Bank, who return an authorisation code if they approve the transaction.
The full transaction response - including the authorisation code if the transaction is successfully authorised - is then passed back to your system by the DPG.
Settlement
Successfully authorised transactions are settled next working day, in the same way as transactions which have not been checked using 3-D Secure.
Requirements
Before you can go live with this service, you will need:
a MasterCard Payment Gateway Services e-Commerce account
the account to be configured with the 3-D Secure service
to be a registered 3-D Secure merchant with your Acquirer, for the specific card schemes
appropriate third party MPI integrated with your website
The 3-D Secure check is currently available for certain Acquiring Banks and card schemes. These are outlined in the table below:
Acquiring Bank |
Card Scheme |
---|---|
Barclays |
MasterCard, Visa |
HBOS |
MasterCard, Visa |
HSBC |
MasterCard, Visa |
Lloyds TSB |
MasterCard, Visa |
Royal Bank of Scotland Group (includes NatWest) |
MasterCard, Maestro (International), Visa |
Transaction Processing Models
Each transaction processed using this service may be submitted using either the one stage or the two stage processing model. The transactions can also be cancelled and refunded, if required, in exactly the same way as for Bank Card transactions. Full details of these models and transaction types are available in the Bank Card section.
Performing Transactions
When using this service, the normal transaction and card information should be provided; this is the exactly the same as for the Bank Card Service.
For card schemes which are supported by the 3-D Secure service, additional information about the transaction is required:
the type of card used
whether the card was registered for 3-D Secure
Plus if the card was registered, these pieces of information taken from the PARes:
the Electronic Commerce Indicator
the security code - the Cardholder Authentication Verification Value for Visa cards, or Universal Cardholder Authentication Field for MasterCard
transaction id
Card schemes which are not supported for 3-D Secure should be presented without this extra information, as described in the Bank Card Service.
Response Codes
An authorisation request may generate the three basic bank responses described in the Bank Card Service:
Authorised
Referred
Declined
A complete list of Response Codes for this service is available here. These are in addition to the general return codes. The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
When a transaction has been checked using the 3-D Secure service, the details of the check will be available for each transaction on the Bank Card Details page
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Address and Security Code Verification Service
The Address and Security Code Verification Service allows the Card HoldersStatement Address and/or the Card Security Code provided by your customer to be compared with the information held by the Issuer when the card payment is authorised. These can be checked to help identify and reduce the impact of fraudulent transactions.
For an AVSCV2 transaction to be classed as successful, it must pass a minimum level of checking. This minimum level of checking is called the policy, and you decide which level is acceptable for your business.
There are three stages to the check, these are outlined below.
Obtaining an Authorisation Code and AVSCV2 Check
Once the payment details have been collected and sent to MasterCard Payment Gateway Services, they are immediately sent to your Acquiring Bank for authorisation. Your Bank forwards the request to the Card Issuing Bank.
The Issuing bank authorises the transaction and compares the CV2 number, postcode and address provided against the details stored in their own systems. Each of these three elements will receive one of five bank responses.
The five bank responses are:
No information available
Not checked
Matched
Not matched
Partial match1
The authorisation code and the results of the AVSCV2 check are then both passed back to MasterCard Payment Gateway Services. If the Issuer is unable to authorise the transaction,the AVSCV2 information is not returned with the transaction.
1 Only returned if you use Barclays as an Acquirer. Does not apply to the CV2 number.
Comparing the Policy
When MasterCard Payment Gateway Services receive the transaction results, they are immediately compared against your policy for the transaction. When a transaction matches your policy, the transaction response including the results of the AVSCV2 check are returned to you.
Reversing a Failed Transaction
If a transaction does not match your policy,MasterCard Payment Gateway Services will re-contact your Acquirer to reverse the transaction. A successful reversal cancels the authorisation code of the transaction, ensuring that there are no funds reserved against the card. Most Issuers will reverse authorisation codes immediately, though others may take longer.The full transaction response is then returned to you, including the result of the AVSCV2 check and the reversal request. A transaction which does not match your policy cannot be settled.
Requirements
If you are using any of the MasterCard Payment Gateway Services Credit and Debit Card Processing Services, the AVSCV2 Service can also be used. The Service requires no additional configuration of your account.
The level of checking and cards that can be checked will depend upon your Acquiring Bank.These are outlined in the table below:
Acquiring Bank |
Card Scheme |
Checking Available |
|
---|---|---|---|
Standard |
Extended |
||
American Express |
Amex |
yes |
yes |
Barclays |
Visa, Visa Delta, Visa Electron, Mastercard, Solo, Switch |
yes |
yes |
Diners |
Diners |
yes |
yes |
Girobank |
Visa, Visa Delta, Visa Electron, Mastercard |
yes |
no |
HBOS |
Visa, Visa Delta, Visa Electron, Mastercard, Solo, Switch |
yes |
yes |
HSBC |
Visa, Visa Delta, Visa Electron, Mastercard, Solo, Switch, JCB |
yes |
yes |
Lloyds TSB |
Visa, Visa Delta, Visa Electron, Mastercard, Solo, Switch |
yes |
yes |
NatWest |
Visa, Visa Delta, Visa Electron, Mastercard, Solo, Switch |
yes |
yes |
The CV2 number can be checked for any of the above cards issued in any country.
Due to the differing address/postcode formats globally, AVS information can currently only be checked for cards issued in the UK.
AVS checking is not currently available for Diners.
Transaction Processing Models
There are three different ways in which the policy can be specified for card payments.
Default Policy - a default policy can be configured on your account. The policy is chosen from a short list of options and can be over-ridden on a per transaction basis if required.
Standard Policy - the policy information is sent through with each transaction, over-riding any default policy. The policy is chosen from a pre-defined short list of options.
Extended Policy - the policy information is sent through with each transaction, over-riding any default policy. There is much greater flexibility than with the standard policy.
Each time a transaction is submitted to the MasterCard Payment Gateway,it contains the information that determines the model to be used for that transaction. This ensures you have the flexibility to mix and match policies as required on an individual transaction basis - for example, you may wish to have a higher level of checking on your larger value orders.
When choosing a policy, it is important to ensure that enough information is collected from the customer to pass the check. For example: if you only collect CV2data from your customer, choose a policy which does not require the AVSinformation to be matched.
If you are unsure which policy to use, you may wish to initially implement a policy which will accept all responses. This will allow you to receive and monitor the results of the checks without rejecting transactions before choosing.
Default Policy
The default policy is the simplest way to implement AVSCV2 checking.The policy is configured against your account here at MasterCard Payment Gateway Services. It treats the address and postcode as a single element.
Policy |
Places Priority on |
Accepts transaction if |
---|---|---|
0 |
- |
Accepts all transactions |
1 |
AVS |
The AVS elements have been checked and the data matched |
2 |
CV2 |
The CV2 element has been checked and the data matched |
3 |
AVS and CV2 |
All elements have been checked and all the data matched |
5 |
AVS |
Either the AVS elements have been checked and matched, or all elements returned not checked |
6 |
CV2 |
Either the CV2 element has been checked and matched or all elements returned not checked |
7 |
AVS and CV2 |
Either all the elements have been checked and matched, or all elements returned not checked |
When a AVSCV2 check is performed using the default policy, the results of each individual element of the check are converted into a single standard response for the entire transaction. This conversion is performed using a set of rules provided by your Acquiring Bank. Further information about the conversion is available in the Support Centre if required.
The five standard converted responses are:
ALL MATCH
SECURITY CODE MATCH ONLY
ADDRESS MATCH ONLY
DATA NOT CHECKED
NO DATA MATCHES
If you choose to use the default policy, please contact Support to configure your chosen default policy on your account prior to sending transactions.
Standard Policy
The standard policy is very similar to default policy. If a standard policy is used, this will be used in preference to any default policy configured on the account. This gives increased flexibility, as it allows you to alter the policy on a per transaction basis.
The differences between standard and default policies are:
A policy value of 0 (zero) cannot be used as a standard policy, only as a default policy. The remaining policies are unchanged.
The standard policy is submitted to the DPG along with the transaction details.
Extended Policy
The extended policy has the most flexibility of all the models.Instead of choosing from a short list of pre-defined policies, the extended policy allows you to precisely define the results of each of the elements which are acceptable to you.
When choosing an extended policy for each of the CV2, Address and Postcode elements, a decision needs to be made on whether to accept or decline each of the five bank responses.
For example, you may wish to accept transactions if the CV2 number is eithermatched or not checked and both the postcode and address are matched - all other responses would be rejected.
When using the extended policies, the results of each individual element of the check are returned to you in the transaction response.
Performing Transactions
To incorporate the full AVSCV2 service into your payment process, the following information needs to be collected from the card holder:
the CV2 number
the customers statement address
the customers statement postcode
In addition you will also need to choose a policy, which should either be configured on your account for default policy, or submitted with the transaction for the standard and extended policies.
If you wish to perform only part of the AVSCV2 check, the full customer details do not need to be collected.
Response Codes
When using the AVSCV2 Service, the basic Responses for transactions become:
Accepted
Declined
Referred
CV2AVS Declined
In addition there are various error codes that can be produced by this service. Examples of each response type available in the Developers Guide.
For all AVSCV2 checked transactions, the results of the check and the policy used will be returned to you.
Accepted Transactions
An Accepted transaction has successfully passed the AVSCV2 check with the policy chosen, and the bank has authorised the transaction.
Once a transaction is accepted, your system can complete the normal ordering process. If you are using the Two Stage model, please remember that the second stage must be completed to debit / credit the card.
Declined Transactions
If a transaction is declined the result of the AVSCV2 check will not be available.
Some Issuers may decline a transaction if the data they receive for the AVSCV2 check does not match their records. For example: American Express have advised that they may at some stage in the future require merchants to collect all three items of data to guarantee a successful transaction.
Referred Transactions
If a transaction is referred the result of the AVSCV2 check will still be returned. If the AVSCV2 check was successful using the selected policy, you will be able to complete the transaction using an authorize_referral_request transaction as for a normal Bank Card transaction.
If the AVSCV2 check was not successful using the selected policy then any attempt to use an authorize_referral_request will result in a CV2AVS Declined response
CV2AVS Declined Transactions
If a transaction is CV2AVS declined, the data provided by your customer failed to match your chosen AVSCV2 policy. The result of the AVSCV2 check will be returned to you, together with the authorisation code and the result of the request to reverse the authorisation code.
Error Messages
A complete list of Response Codes for this service is available here. TheSupport Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate on how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
When a transaction has been checked using the AVSCV2 service, the details of the check will be available for each transaction on the Bank Card Detailspage
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Age & Identity Verification
The URU Service allows the identity of your customers to be verified, using data collected from the customer. The Service can be used in many different ways, for example:
-to ensure the customer is over a certain age
-to verify current or past address details
-to prevent identify fraud
Once the details have been collected and sent to MasterCard Payment Gateway Services, they are immediately sent to the GB Group for verification. GB Group's URU Verification Service checks the information against a wide range of sources - including the Electoral Roll and Deceased Register - and returns the results. The full results are then passed back to your systems via MasterCard Payment Gateway Services, where they are used to decide whether to proceed to a Credit/Debit Card or BACS Payment transaction.
Requirements
Before you can go live with this Service you will need the following:
an account set up with MasterCard Payment Gateway Services,
an account set up with GB Group's URU Verification Service
the ability to send XML transactions to the MasterCard Payment Gateway.
Transaction Types
MasterCard Payment Gateway Services provide two transactions types with which to access the URU Service:
Transaction Type |
Affect |
Uses |
---|---|---|
authenticate |
Performs verification based on the data provided |
Verifies data & returns result in real time |
get_log_by_authentication_id |
Returns the result of a previous transaction |
Allows the results of an existing authenticate to be re-collected at a later time |
Performing Transactions
Each transaction type requires specific information to be provided. In addition to the transaction type specific information, all transactions also require:
client and password - these are security details that identify your MasterCard Payment Gateway Services account
A unique reference generated by your system - to allow transactions to be distinguished from each other
the transaction type - either authenticate or get_log_by_authentication_id
Support is also available to submit information in the transaction to allow different URU accounts to be used for different transactions. Login details for the account that should be used need to be supplied for this type of transaction
Authenticating a Customer
Many pieces of information can be used to authenticate a customer. At least one from the following list must be gathered to enable authentication.
Customer name
Date of birth
Gender
Current Address
Residence status at current address
Up to three previous addresses
Dates of residence at each address
Full or partial Passport details, for both UK and International passports
Birth details - country of birth and mother's maiden name
Details from household telephone and electicity bills
Credit or debit card information
Driving licence details
Current employment status
Full details of the exact data and it's format are available in the Developers Guide
Re-Collect Authentication Results
To perform a get_log_by_authentication_id transaction, the reference number returned with the result of the authentication is required.
Responses
There are two basic response types which can be returned from the Service:
Accepted
Error
All MasterCard Payment Gateway Services responses will contain a status code, status message, time, MasterCard Payment Gateway Services reference number. There will be additional data in the responses depending on the type of the transaction.
Accepted
An Accepted transaction returns the results of the URU verification.
Each element of the URU service used for verification will return detailed response codes and information about each test performed. The response codes fall into four main groups:
Match
Warning
Mismatch
Comment
It is possible to configure a URU account (see GB Group documentation) to return scores for individuals' performance on the tests submitted. The interpretation of these scores is dependant on the configuration at the URU side of the transaction. MasterCard Payment Gateway Services will return the score value for any transaction that is thus enabled. Interpretation of the score is the responsibility of the merchant.
Full details of the individual response codes and how they relate to the data submitted are available from GB Group.
Error responses
In the event of an error, whether in validating the input data or as the result of a communication error with the URU server, the status and reason fields will provide a general explanation of the problem. If more detail is available it is sent back in an information field. A complete list of error codes is available here
Direct Credit & Direct Credit Overview
MasterCard Payment Gateway Services is a fully accredited BACS bureau (BAB), and provides a fully online Paperless Direct Debit solution allowing you to process Direct Debit Instructions (DDIs). This is complimented by a Direct Credits service, which can be used for paying into bank accounts and credit card accounts, and to process Direct Debit refunds.
Key Features
Collect repeated payments from your customers easily and effectively
Process AUDDIS and Paperless Direct Debit
Supported by standard MasterCard Payment Gateway Services XML API
Available for cardholder not present and Chip and PIN sales channels
Incorporates bank account and sort code verification and sanity checking
Standard Direct Credit payments to nominated UK bank accounts enable one-off or regular payment to suppliers, employees, dividends, etc.
Direct Debit Refunds enable refunds to be made against Direct Debit Instructions, for instance in the case where a customer has cancelled their DD agreement and requires funds to be returned to their account
Direct Credits to Credit Card Account Payments can be used when refund payments cannot be made to the credit card account by the usual process of a 'refund' or a 'txn_refund' transaction (i.e. no initial payment has been taken)
Key Benefits
Predict cashflow with greater ease
Enhance customer loyalty
Open up to customer not present sales channels with convenient and popular Paperless Direct Debits.
Avoid unnecessary DDI failures with bank account and sort code sanity checking
Reconcile transactions easily with payment history incorporated into the MasterCard Payment Gateway Services Reporting suite
Direct Debit
This is a technical introduction to the MasterCard Payment Gateway Services Direct Debit Service. Further detailed information to assist integration with the Service is available in the Developers Guide.
The Direct Debit Service
Direct Debit is a simple way for you to collect regular or occasional payments from your customers.
The MasterCard Payment Gateway Services Direct Debit Service can be used for both AUDDIS and AUDDIS Paperless Direct Debits. If you are currently using a non-AUDDIS system, MasterCard Payment Gateway Services can assist you in the transfer of existing Direct Debit Instructions to AUDDIS.
Validating a Direct Debit Instruction
The MasterCard Payment Gateway Services Direct Debit Service incorporates a comprehensive, BACS approved, validity checking service. Every Direct Debit Instruction (DDI) is checked to verify that the customer's sort code and account number are valid and can be used for Direct Debits. This check takes place in real time, ensuring that any data entry errors can be identified and rectified immediately.
Processing a DDI
Once the DDI details have been validated, the next stage is for it to be set up against your customers bank account. Each working day, MasterCard Payment Gateway Services collate all the DDIs which require setting up and submit them to BACS. This process is called settlement. BACS then liaise with your customers bank to set up the DDI against the account. This processing of the instruction takes five working days from the time of submittal.
Taking Payments
Payments can be taken from the instruction once it has been set up on your customer's account. The process of taking a Direct Debit payment is called a drawdown.
Using the MasterCard Payment Gateway Services solution, you have the option to either generate and submit each individual drawdown to the DPG or the DPG can generate these automatically and email the results to you. Further information about the automated drawdown Service is available here.
Whichever generation mechanism you choose, the settlement process for drawdowns is the same. Like the DDIs, all drawdowns are batched by the DPG each working day and are submitted to BACS for processing. This process takes three working days.
Refunds
The MasterCard Payment Gateway Services solution can also be used to perform refunds against existing DDIs if required.
Cancellations
The Direct Debit Guarantee enables your customer to cancel their DDI by contacting their bank or building society directly. Using the MasterCard Payment Gateway Services Service, information about these cancellation advices can be automatically collected by the DPG on your behalf if required. These are then used to update our records and can be emailed to you.
If you wish to cancel a DDI - either because the customer has contacted you directly, or it has expired on your system - this can also be done through the DPG. A cancellation of a DDI is called a revoke on the DPG. The settlement process for revokes is the same as for the DDIs themselves.
Drawdowns may be cancelled before settlement, if required.
Requirements
Before you can go live with this service, you will need:
- an account with MasterCard Payment Gateway Services configured for this service
- to be the holder of an AUDDIS Direct Debit Originator's Identification Number (OIN)
- to have completed any accreditation required by your Sponsoring Bank
- the ability to send XML transactions to our servers
MasterCard Payment Gateway Services can also collect on your behalf, information about any changes to your setups. If you wish to use this feature, you will also need:
- to complete section 6 of your BACSTEL-IP application form (which is submitted to your Sponsoring Bank), naming MasterCard Payment Gateway Services as your Bureau.
- an email address for the DPG to send the DDI updates to
Your Sponsoring Bank may require you to complete accreditation testing with them before the service can be set live.
Transaction Processing Models
The MasterCard Payment Gateway Services Direct Debit Service has the flexiblity to allow DDIs to be set up in two different ways.
- One Stage Processing - the DDI is validated and then sent to BACS. If you are using this model, you will only need to contact the MasterCard Payment Gateway Services servers once to set up a DDI.
- Two Stage Processing - the DDI is validated, but is not sent to BACS until you are ready to proceed. If you are using this model, you will need to contact the MasterCard Payment Gateway Services servers twice - once for validation and again to confirm.
Each DDI can be processed in the model of your choosing - there are no restrictions, additional service charges or extra account configurations required.
Each time a DDI is submitted to the DPG, it contains the information that determines the model to be used for that transaction. This ensures you have the flexibility to mix and match models as required on an individual transaction basis.
In both models, the customer details are validated and the result returned to you in real time. The difference between the models lies in the submission of the DDI to BACS.
One Stage Processing
The One Stage model validates the customer details and activates the instruction without additional effort on your part. The details are submitted to BACS the next working day. BACS then pass the details to your Sponsoring Bank and the customer's bank. The customer's bank set up the DDI.
Using the One Stage process, the start date of the DDI is five days after submission to the DPG.
This model is useful if you do not require the customer to return a signed DDI - for example if you are using the AUDDIS PAPERLESS scheme.
Transaction Type |
Effect |
Uses |
---|---|---|
setup |
Sets up a DDI |
Validates the DDI detail and submits it to BACS for setup against the customer's account |
Two Stage Processing
The Two Stage model also validates the customer details in real time, but does not activate the instruction. This initial stage is performed using a presetup. The instruction is activated once the second stage - the confirm has been received.
Transaction Type |
Effect |
Uses |
---|---|---|
presetup |
Validates DDI |
Validates the DDI detail only. The DDI is not sent to BACS to be set up against the account until a valid confirm is received |
confirm |
Completes the two stage process |
Initiates the submission of a successful presetup to BACS, where it is set up against the customer's account |
This allows you to delay the full setup of the instruction until up to a maximum of twenty eight days after the presetup. This can be useful if you are waiting for a signed DDI from your customer before completing the setup process.
Once the confirm has been received, the details are submitted to BACS the next working day.
Using the Two Stage process, the start date of the DDI is five days after submission of the confirm to the DPG.
Transferring Existing DDIs to MasterCard Payment Gateway Services
If you have existing AUDDIS or AUDDIS PAPERLESS DDIs which you wish to make payments on through MasterCard Payment Gateway Services, these DDIs can be transferred to your MasterCard Payment Gateway Services account. As the DDI is already set up at BACS, they only require validation. Once transferred they can be used to submit drawdowns immediately, as the start date is the current date. The One Stage process should be used when transferring existing DDIs.
Converting DDIs to AUDDIS
MasterCard Payment Gateway Services are also able to assist in converting existing non-AUDDIS DDIs to AUDDIS. The converted DDIs are validated and sent to BACS for processing - this process takes five days. The One Stage process should be used when converting existing DDIs.
When converting a DDI, the start date is five days after submission to the DPG.
As the conversion to AUDDIS may require additional configuration of your OIN, please contact your Sponsoring Bank prior to submission of the DDIs to MasterCard Payment Gateway Services. Additional information about this process is available in the Originator's Guide and Rules.
Drawdowns
Drawdowns can be submitted to DPG on or after the start date of any valid DDI. As the processing of drawdowns takes three days, the due date - the date the money will be transferred - must be a minimum of three days ahead of submission to the DPG.
Transaction Type |
Effect |
Uses |
---|---|---|
drawdown |
Takes Payment |
Transfers funds for a valid DDI from the customer's account |
The MasterCard Payment Gateway Services will automatically calculate whether the drawdown is the first drawdown on a DDI or a later drawdown. If you wish a particular drawdown to be flagged in a different fashion, this can be done by using transaction codes.
Revoking DDIs
If you wish to cancel a DDI, this can be done by submitting a revoke to the DPG.
Transaction Type |
Effect |
Uses |
---|---|---|
revoke |
Cancels DDI |
Cancels the DDI on both the customer's account and the DPG |
Situations in which this could be implemented include:
- Your customer has informed you that they wish to cancel the DDI, but has not informed their bank.
- You have taken the agreed number of payments from the customer, and will no longer require the DDI.
- You collect the DDI cancellation information direct from your bank and wish to update the DPG with these cancellations.
Cancelling a Drawdown
If you wish to cancel a drawdown prior to settlement, this can be done by submitting a cancel to the DPG.
Transaction Type |
Effect |
Uses |
---|---|---|
cancel |
Cancels drawdown |
Prevents an unsettled drawdown from being sent to BACS for processing |
Performing Transactions
Each transaction requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Performing the Initial Validation
For both one and two stage setups, these details need to be collected from the customer:
- the sort-code of the customer's bank
- the customer's account number
- the name the account is held under
In addition, these details are required:
- the transaction method - either setup or presetup
- the reference number of the DDI
When transferring or converting an existing DDI, the one stage setup should be used. In these cases, in addition to the information above, an extra flag is used to indicate whether the DDI is a conversion or a transfer. Please refer to the Developers Guide for full details.
Completing a Two Stage setup
To complete the processing of a Two Stage DDI, a confirm is needed. This informs MasterCard Payment Gateway Services that you wish the DDI to be set up on the customer's bank account.
To confirm a DDI, information from the result of the original presetup is required, in addition to the transaction method:
- the transaction method - confirm
- the MasterCard Payment Gateway Services reference number of the presetup
- the reference number of the DDI
Taking Payments
Once a DDI start date has passed, payments can be taken from the DDI. To submit a drawdown, the following information should be supplied:
- the amount - the value to be debited from the account.
- the transaction method - drawdown
- the MasterCard Payment Gateway Services reference of the setup or confirmed presetup
- the drawdown reference number - to allow you to distinguish the drawdown on the Reporting System. This reference may be the same as the DDI reference number and is not sent to BACS.
Each drawdown will be processed by BACS from the customer's account three working days after it is submitted to MasterCard Payment Gateway Services. If you wishto submit drawdowns in advance, this can be done by specifying the due date along with the transaction.
A transaction code may also be presented for the drawdown if required.
Revoking a DDI
To revoke an existing DDI, the following fields are required:
- the MasterCard Payment Gateway Services reference of the setup or confirmed presetup
- the transaction method - revoke
- your DDI reference number
Cancelling a Drawdown
To cancel an unsettled drawdown, the following fields are required:
- the MasterCard Payment Gateway Services reference of the drawdown
- the transaction method - cancel
Response Codes
There are two basic Response types for all transactions.
- Acknowledgements
- Errors
Examples of both response types are available in the Developers Guide.
Acknowledgement
An acknowledgement response indicates that the transaction has been successfully entered into the DPG and will be sent to BACS for processing. This does not guarantee that the transaction will be successfully processed by BACS however. The Direct Debit Scheme provides excellent customer protection by allowing both the DDI and drawdowns to be queried or cancelled by the customer. If BACS are unable to process the transaction for whatever reason, they will notify you directly.
If section 6 of your BACSTEL-IP application form has been completed and submitted to your Sponsoring Bank, MasterCard Payment Gateway Services will receive notifications of any rejections, cancellations and failures of your DDIs directly from BACS. These will be used to update our records to prevent further drawdowns being sent to your bank on those setups. In addition, these will be mailed to an email address of your choosing, in an attachment of standard CSV format to allow you to automatically update your own systems. Further details about the format of the CSV file are available in the Developers Guide, available here.
Errors
A complete list of Response Codes for this service is available here. The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The Direct Debit transactions are detailed in the Direct Debit section of the MasterCard Payment Gateway Services Reporting system. There are six main pages:
- For DDIs:
- Setup Summary - gives a summary of the DDIs
- Setup List - shows specific details of the DDIs
- Setup Details - shows full details of each DDI
- For drawdowns:
- Drawdown Summary - gives a summary of the drawdowns
- Drawdown List - shows specific details of the drawdowns
- Drawdown Details - shows full details of each drawdown
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Direct Credit
This Service enables you to quickly and easily return funds by Direct Credit, to any customers with a UK bank account accepting Direct Credits.
There are two parts to the Service: validation and settlement.
Validating a Transaction
The Service incorporates a comprehensive, BACS approved, validity checking service. Every transaction is checked to verify that the customer's sort code and account number are valid and can be used for Direct Credits. This check takes place in real time, ensuring that any data entry errors can be identified and rectified immediately.
Settling the Transaction
To transfer the money between you and your customer, the validated transaction needs to be settled by your Sponsoring Bank.
Direct Credits are batched by the DPG each working day and are submitted to BACS for processing. BACS then pass the details to your Sponsoring Bank. This process takes three working days.
Requirements
Before you can go live with this service, you will need the following:
an account with MasterCard Payment Gateway Services configured for the Standard Direct Credit Service
your OIN to be configured at your Sponsoring Bank for Direct Credit
the ability to send XML transactions to our servers
Transaction Processing Models
MasterCard Payment Gateway Services provide two transaction types with which to access the Service:
Transaction Type |
Effect |
Uses |
---|---|---|
directcredit |
Returns funds to the account |
Returns funds directly to the customer's bank account |
cancel |
Prevents settlement of a transaction |
Prevents an unsettled directcreditfrom being submitted for settlement |
Performing Transactions
Both transaction types require specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Performing a Direct Credit
To perform a directcredit the following information is required:
the value you wish to be refunded
the transaction type - directcredit
the sort code of the customer
the account number of the customer
the name of the account holder
a unique reference number generated by your system - to allow the transactions to be distinguished from each other
In addition, a bank reference number can be supplied if required.
Cancelling a refund
To cancel a directcredit prior to settlement, the following information is required:
the MasterCard Payment Gateway Services reference for the directcredit
the transaction type - cancel
Response Codes
There are two basic Response types for all transactions.
Accepted
Errors
Accepted
A successful response indicates that the directcredit will be sent to BACS for settlement, unless it is cancelled.
Errors
A complete list of Response Codes for this service is available here. The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The directcredit transactions are detailed in the Direct Credit section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Summary - gives a summary of thetransactions
List - shows specific details ofthe transactions
Details - shows full details of each transaction
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Direct Debit Refunds
This Service enables you to quickly and easily return funds by Direct Credit, to any customers with Direct Debit Instructions held on your account in the DPG. The funds are credited back to the account details held on the DDI, even if the DDI has been cancelled.
Like the Direct Debit drawdowns, all Direct Debit Refunds are batched by theDPG each working day and are submitted to BACS for processing. This process takes three working days.
Requirements
Before you can go live with this service, you will need the following:
an account with MasterCard Payment Gateway Services configured for the Direct Debit Refunds Service
existing DDIs set up on the account with the Direct Debit Service
the ability to send XML transactions to the DPG
your OIN to be configured at your Sponsoring Bank for Direct Credit
Transaction Processing Models
Any existing DDI can be used to perform a Direct Debit Refund. If the DDI has already been revoked, it may still be used for refunds. It is also possible to cancel a Direct Debit Refund before settlement if required.
Refunding a Direct Debit
Situations in which you may wish to implement Direct Debit Refunds include:
Customer cancels DDI just after a payment has been settled
Payment value needs to be be adjusted
Payment taken in error
Transaction Type |
Effect |
Uses |
---|---|---|
ddrefund |
refunds a DDI |
Returns funds to the account |
Cancelling a Refund
The cancel transaction prevents any unsettled ddrefund from being settled
Transaction Type |
Effect |
Uses |
---|---|---|
cancel |
Prevents settlement of a transaction |
Prevents an unsettled ddrefund from being submitted for settlement |
Performing Transactions
Both transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Refunding a Direct Debit
To perform a ddrefund, the following information needs to be submitted:
the value you wish to be refunded
the transaction type - ddrefund
the MasterCard Payment Gateway Services Reference of the DDI you wish to perform the refund against
a unique reference number generated by your system - to allow the transactions to be distinguished from each other
Cancelling a refund
To cancel a ddrefund prior to settlement, the following information is required:
the MasterCard Payment Gateway Services Reference of the ddrefund you wish to cancel
the transaction type - cancel
Response Codes
There are two basic Response types for all transactions.
Accepted
Errors
Accepted
A successful response indicates that the ddrefund will be sent to BACS for settlement, unless it is cancelled.
Errors
A complete list of Response Codes for this service is available here. TheSupport Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The ddrefunds are detailed in the Direct Debit section of the MasterCard Payment Gateway Services Reporting system, on the same pages as the drawdowns.
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Payments to Card Collection Accounts
The Credit Card Account Payment Service enables payments to be made to the collection account of any UK issued Visa or Mastercard branded credit card. This type of payment is generally used when funds cannot be returned to a credit card account using the Credit and Debit Card Service.
There are two parts to this Service: validation and settlement.
Validating the Transaction
Once the details of the transaction have been sent to the DGP, a BACSapproved database is used to determine whether the card Issuing Bankallows Direct Credit to be performed using the card. If the Issuing Bank does allow Direct Credits, the database is then used to obtain the collection account details for the card. This database is regularly updated to ensure the latest details are always available.
Settling the Transaction
To transfer the money between you and your customer, the validated transaction needs to be settled by your Sponsoring Bank.
Direct Credits are batched by the DPG each working day and are submitted to BACS for processing. BACS then pass the details to your Sponsoring Bank. This process takes three working days.
Requirements
Before you can go live with this service, you will need the following:
an account with MasterCard Payment Gateway Services configured for the Direct Credit Card Collection Account Service
your OIN to be configured at your Sponsoring Bank for Direct Credit
the ability to send XML transactions to our servers
Transaction Processing Models
MasterCard Payment Gateway Services provide two transactions types with which to access the Service:
Transaction Type |
Effect |
Uses |
---|---|---|
cardaccountpayment |
Credits the customer |
Returns funds to the card collection account for the card holder |
cancel |
Prevents settlement of a transaction |
Prevents an unsettled cardaccountpayment from being submitted for settlement |
Performing Transactions
Both transaction types require specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Performing a Card Payment via Direct Credit
To perform a payment to a card collection account, the following information about the card can be collected
the customers card number
card expiry date - this is optional
the name of the account holder - this is optional
In addition to the card information collected from the customer, these details about the transaction are also required:
the value you wish to be refunded
the transaction type - cardaccountpayment
a unique reference number generated by your system - to allow the transactions to be distinguished from each other
Cancelling a refund
To cancel a cardaccountpayment prior to settlement, the following information is required:
the MasterCard Payment Gateway Services reference for the cardaccountpayment
the transaction type - cancel
Response Codes
There are two basic Response types for all transactions.
Accepted
Errors
Accepted
A successful response indicates that the card collection account details have been validated and the cardaccountpayment will be sent to BACS forsettlement, unless it is cancelled.
Errors
A complete list of Response Codes for this service is available here. TheSupport Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The cardaccountpayment transactions are detailed in the Direct Credit section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Summary - gives a summary of the transactions
List - shows specific details of the transactions
Details - shows full details of each transaction
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Recurring Payments
MasterCard Payment Gateway Services supports a range of services designed to process your subscription and instalment payments by Bank Card and Direct Debit.
There is a range of "flavours" available to suit your requirements including: Fire and Forget, Capture Method, and Historic Transactions.
Fire and Forget
Set up a recurring payments schedule with one instruction and let MasterCard Payment Gateway Services manage all subsequent transactions on a recurring transactions merchant ID (Not needed for Direct Debits). Fire and Forget is suitable where instalments are of fixed amounts, although the first and last payment may vary, e.g. A home entertainment company could invoice a customer for a TV with payments spread over 36 months on a fixed payment plan.
Historic Transactions (Bank Card Only)
This allows you to send MasterCard Payment Gateway Services a recurring transaction set up request with the initial transaction made on a customer's card. MasterCard Payment Gateway Services then allocate a unique reference number to that card. This allows you to send through subsequent authorisation requests on a recurring transactions merchant ID using only this reference number. All card details are stored on MasterCard Payment Gateway Services's secure servers relieving your security liability. The amount and frequency of each instalment can vary, e.g. A mobile phone company could invoice a customer each month for call charges incurred in the previous month.
Capture Method (Bank Card Only)
This allows you to send MasterCard Payment Gateway Services a recurring transaction set up request with the initial transaction made on a customer's card. Subsequent authorisation requests can then be sent through on a recurring transactions merchant ID, allowing you to instigate each payment on that card. The amount and frequency of each instalment can vary, e.g. A music downloads company could invoice a customer as and when they purchase music regardless of the amount and without having to take the customer's card details each time.
Key Features:
- Supports subscription and instalment payments by credit and debit card (Fire and Forget also supports Direct Debit payments).
- Supports flexible payment schedules (e.g. daily, weekly, monthly, quarterly, annually).
- Works in collaboration with MasterCard Payment Gateway Services fraud prevention solutions (Dependant on "flavour").
- Real-time MIS Reporting.
Key Benefits:
- Capture and retain more subscriptions annually.
- Easily create fixed payment schedules with one instruction using Fire and Forget.
- Process variable instalment amounts with Capture Method or Historic Transactions.
- Eliminate your security liability by storing all card details on MasterCard Payment Gateway Services servers with Fire and Forget and Historic Transactions.
Recurring Payments Technical Overview
Many merchants want to be able to process repeated, regular payments against a client's direct debit account or credit card. This can be achieved by the merchant initiating repeated transactions using the same account or card details. Using one of our Recurring Transactions models, however, achieves the same outcome with one or more of the following benefits:
- ability to use stored account or credit card details
- ability to send one setup which details when regular transactions should take place
- ability to link a set of recurring transactions associated with an account for reporting purposes
- ability to flag credit card transactions as Recurring Transactions such that the expiry date is not relevant
Note that Recurring Transactions is also known as Continuous Authority, where the end user has authorized continued debits against their account or credit card.
Range of models available
MasterCard Payment Gateway Services have provided different models for processing Recurring Transactions to suit different merchant's requirements. Click on the links for details on how to integrate with these services.
Direct Debit transactions
Recurring Transactions (fire & forget)
Credit Card transactions
Recurring Transactions(fire & forget)
Historic Recurring Transactions
(historic txns refer to card details of initial setup)Capture method Recurring Transactions
(normal credit card txn processed using RT MID)
Recurring Transaction features and restrictions
There are different features/restrictions of Recurring Transactions (RT) depending on which model you use: Direct Debit or one of the Credit Card models. For credit card transactions acquiring banks have special treatment for transactions flagged as RT, and there are restrictions such as
whether your acquirer supports RT
whether your acquirer needs you to have a separate Merchant ID (MID) for RT txns
the supported card schemes
the transaction types that can be used (refunds are not applicable)
the first transaction should be processed in your normal environment (Mo/To or e-commerce) and include a valid expiry date
subsequent transactions should be flagged as RT and allow an expired card to be used
For all models you have to have an account set up with a client ID (VTID), but some models also require you to be registered with MasterCard Payment Gateway Services for that service and/or have specific TIDs set up before you can use RT.
Some models have a concept of an account, where a setup transaction must be sent first. This setup transaction stores the account or card details for future use, and may detail when regular transactions should take place automatically or initiate a bank transaction immediately. Models that use an account have a specific section of Reporting that can be used to view the history of transactions associated with a particular account.
Testing
We recommend that you acquire a test account on the testserver and arrange for it to be set up to match the requirements of your proposed production system in order to fully test all the features you will be using.
Testing on the production servers is not recommended and restrictions may be applied in the future.
Direct Debit Continuous Authority
The Direct Debit Continuous Authority Service enables you to automatically collect regular payments from any valid Direct Debit Instruction on your MasterCard Payment Gateway Services account, without needing to design a system to submit the individual drawdown requests to the DPG.
Creating a Direct Debit Continuous Authority Account
For each DDI which requires regular payments to be taken, a Direct Debit Continuous Authority account is set up on the DPG. This account contains the details of the frequency and value of regular payments. You may also configure each account with a different amount to be used for the first and/or last payment, and these payments can be taken on specific dates.
Collecting Payments
Each working day the DPG will look at each of your Direct Debit Continuous Authority accounts to see if any payments are due. For each payment which is found, a drawdown will be generated. You will receive an email notifying you of all drawdowns generated on that particular day. The DPG will then settle the drawdowns.
Merchant Requirements
Before you can go live with this service, you will need the following:
a MasterCard Payment Gateway Services Account configured for this service
existing DDIs set up on this account with the Direct Debit Service
the ability to send XML transactions to the DPG
an email address for the DPG to send drawdown notifications to
Transaction Processing Models
There are many different ways in which the Direct Debit Continuous Authority Service can be implemented. Each account can be set up to create drawdowns in one of these frequencies:
Weekly - payments will be taken on a particular day of the week
Monthly - payments taken on a particular day of the month
Quarterly - payments taken on a particular day every three months
Annually - payments will be taken on a particular day each year
Using these, the regular payments will be taken from your customer's account. If a particular payment date falls on a non-business day, the payment will be taken on the next available date. For example: if monthly payments are taken on the 31st of the month, the payment which was due in February would be taken on the next business day, nominally 1-Mar.
As well as the frequency of payments, the number of regular payments to be taken from the account can be specified:
An undefined number of payments - the customer will have regular payments deducted until further notice
A set number of payments - a pre-defined number of payments will be taken from the account
When specifying a set number of payments, the initial and/or final payments can also be set for a different date and value to the regular payments if required.
All of these account types can be cancelled before completion if required.
Creating an Account
Any DDI which is valid on your MasterCard Payment Gateway Services account can be easily accessed using a Continuous Authority Account - of any flavour. All account types are set up using the transaction type drawdown.
Situations in which this could be implemented include:
Subscription Services
Utility payments, such as Council Tax, mobile phones or electricity
Charity donations
Transaction Type |
Effect |
Uses |
---|---|---|
drawdown |
Creates a Direct Debit Continuous Authority account |
Used to perform regular payments from an existing DDI |
Cancelling an Account
Accounts can be cancelled before completion without also cancelling the underlying DDI. Situations in which this could be implemented include:
The values or timings of the payment need to change - for example, increasing the price in line with inflation. The old account can be cancelled and a new account can be created against the existing DDI, without requiring a new DDI to be issued to your customer
Payments from the account need to be halted or suspended, but re-instated at a later date on the same DDI
Transaction Type |
Effect |
Uses |
---|---|---|
cancel |
Cancels the Continuous Authority Account |
Prevents any future payments from being taken from the account |
If the underlying DDI is cancelled or revoked, the account will be automatically cancelled.
Performing Transactions
The account setups and cancellations each require specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Creating a Continuous Authority Drawdown Account
There are several options available when setting up a continuous authority account. The most basic account set up is the unspecified number of drawdowns account. To set this type of account up, a particular set of data is required. This set of data is required for all types of account, with extra information being added to it to create the other account types.
The following sections introduce the data required for the most basic type, then move on to the extra information required when setting up accounts utilising the additional features.
Unspecified Number of Drawdowns
To set up an account to bill indefinitely, the following information is required:
the date of the first regular drawdown
the frequency of drawdowns, one of:
weekly
monthly
quarterly
annually
the transaction method - drawdown
the value of the regular drawdowns
the MasterCard Payment Gateway Services Reference of the DDI you wish to set the recurring drawdowns against
the merchant reference number - to allow you to distinguish the account on the Reporting System
Specified Number of Drawdowns
If the total number of drawdowns to be taken is known in advance, this can be pre-configured into the account. When setting this type of account up, the information required is exactly the same as that required for an unspecified number of payments, though a single extra piece of information is required:
the total number of regular payments
Initial Payment
To set an initial payment to be different from the regular payments, these fields should also be provided:
the value of the initial payment
the date of the initial payment
Final Payment
Using the specified number of payments account type, it is also possible to set the final payment to be of a different amount to the regular payments. The additional information required for this is:
the value of the final payment
the date of the final payment
Please note: This option is only available if the total number of regular payments has been specified
Drawdown Flagging
By default, all payments taken from the continuous authority account are flagged as normal payments. If you require the first and last payments to be flagged differently, this can be achieved using the transaction codes. Details of transaction codes are available within the Direct Debit Service.
Cancelling Accounts
To cancel an account, only two additional pieces of information - besides theclient and password - are required:
the transaction method - cancel
the MasterCard Payment Gateway Services reference number of the account
Response Codes
There are two basic Response types for all transactions.
Accepted
Errors
Examples of both response types available in the Developers Guide.
Accepted
An Accepted response indicates the account has been successfully set up and will be used to generate drawdowns.
When the drawdowns are generated by the DPG, their details will be mailed to an email address of your choosing, in an attachment of standard CSV format to allow you to automatically update your own systems.
If the underlying DDI is cancelled, the DPG will automatically cancel the account. Details of these cancellations will also be emailed to your choosen address in CSV format.
Further details about the format of the CSV file are available in the Developers Guide, available here.
Errors
A complete list of Response Codes for this service is available here. TheSupport Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The Direct Debit Continuous Authority Accounts are detailed in the DD. Cont. Auth section of the MasterCard Payment Gateway Services Reporting system. There are five main pages:
For Accounts:
Account Summary - gives a summary of the accounts
Account List - shows specific details of the accounts
Account Details - shows full details of each account, with links to view theoriginal DDI and the full details of each drawdown taken from the account
For Notifications:
Notification Summary - gives a summary of the notifications sent
Notification List - shows specific details of the notifications sent, with links to the both the original DDI and the drawdown for each notification
The setups and drawdowns are shown in the Direct Debit section of Reporting.
The Support Centre contains full hints and tips to help you get the most out of MasterCard Payment Gateway Services Reporting.
Bank Card (Fire & Forget)
The Fire and Forget Continuous Authority Service enables you to automatically collect regular recurring payments from any Amex, Visa or Mastercard branded card, without needing to design a system to submit the individual transaction requests to the DPG.
Creating a Fire and Forget Continuous Authority Account
For each set of payments, a Continuous Authority account is set up on theDPG. This account contains the details of the frequency and value of regular payments. You may also configure each account with a different amount to be used for the first and/or last payment, and these payments can be taken on specific dates.
Collecting Payments
Each day the DPG will look at each of your Fire and Forget Continuous Authority accounts to see if any payments are due. For each payment which is found, a transaction will be generated and sent to your bank for authorisation. You will receive an email notifying you of all transaction generated on that particular day and their results. The DPG will then settle the transactions next working day.
Requirements
Before you can go live with this service, you will need the following:
an account with MasterCard Payment Gateway Services configured for this Service
an e-Commerce or Mo/To Merchant ID
a recurring Transaction capable MID
the ability to send XML transactions to our servers
an email address for the DPG to send payment notifications to
Transaction Processing Models
Using this Service, each transaction can be processed with either the one stage or the two stage processing models. The transactions can also be cancelled and refunded if required. Full details of these models and transaction types are available in the Bank Card page.
There are many different ways in which the Fire and Forget Continuous Authority Service can be implemented. Each account can be set up to create payments in one of these frequencies:
Weekly - payments will be taken on a particular day of the week
Monthly - payments taken on a particular day of the month
Quarterly - payments taken on a particular day every three months
Annually - payments will be taken on a particular day each year
Using these, the regular payments will be taken from your customer's account. If a particular payment date falls on a non-calender day, the payment will be taken on the next available date. For example: if monthly payments are taken on the 31st of the month, the payment which was due in February would be taken on the next business day, nominally 1-Mar.
As well as the frequency of payments, the number of regular payments to be taken from the account can be specified:
An undefined number of payments - the customer will have regular payments deducted until further notice
A set number of payments - a pre-defined number of payments will be taken from the account
When specifying a set number of payments, a final payment can also be set for a specific date and value, if required. If an initial payment - for a different value from the regular payments - needs to be taken, this can be specified, along with the date of the payment.
All of these account types can be cancelled before completion if required.
Creating an Account
Accounts can be set up to create payments which use either the one stage or two stage processing models
Completing the Two Stage Process
If you are processing the recurring payments as two stage transactions, please remember that you will need to fulfill each transaction before it can be settled.
Cancelling an Account or Payment
Accounts can be cancelled before completion, and the individual transactions generated from them can also be cancelled if required. Situations in which this could be implemented include:
The values or timings of the payment need to change - for example, increasing the price in line with inflation. The old account can be cancelled and a new account can be created
The contract has been cancelled - either by the customer or yourself - and so the account is no longer required
Transaction Type |
Effect |
Uses |
---|---|---|
cancel |
Cancels the Continuous Authority Account |
Prevents any unsettled payments from being settled and prevents any future payments from being taken from the account |
Performing Transactions
Both transaction types require specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Creating An Account
When setting up an account, the normal transaction and card information should be provided. This is the exactly the same as for the Bank Card Service.
In addition, there are additional pieces of information about the payments which need to be provided:
Unspecified Number of Payments
To set up an account to bill indefinitely, the following information is required:
the date of the first regular payment
the frequency of payments, one of:
weekly
monthly
quarterly
annual
the transaction type - to allow MasterCard Payment Gateway Services to use the correct processing model for the payments: either pre or auth
the value of the regular transactions
the merchant reference number - to allow you to distinguish the account on the Reporting System
Specified Number of Payments
If the total number of payments to be taken is known in advance, this can be pre-configured into the account. When setting this type of account up, the information required is exactly the same as that required for an unspecified number of payments, though a single extra piece of information is required:
the total number of regular payments
Initial Payment
To set an initial payment to be different from the regular payments, these fields should also be provided:
the value of the initial payment
the date of the initial payment
Final Payment
Using the specified number of payments account type, it is also possible to set the final payment to be of a different amount to the regular payments. The additional information required for this is:
the value of the final payment
the date of the final payment
Please note: This option is only available if the total number of regular payments has been specified
Cancelling Accounts
Both accounts and the transactions generated from them can be cancelled if required. Exactly the same information is needed for both of these as for cancelling a normal Credit and Debit card transaction.
Response Codes
There are two basic Response types for setting up the account:
Accepted
Error
The payments themselves can generate the same responses as for the Bank Card service.
Accepted
Once a transaction is accepted, your system can complete the normal ordering process. Each day payments are generated from your accounts, the DPG will automatically send you an email detailing the results of all the payments in a standard CSV format attachment. This can be used to automatically update your own systems. You will also be notified of any cards which will expire before the next payment is due.
When payments are taken from an account, the reference number for the payment will be the reference number of the account followed by four characters indicating how many payments have been taken from the account. For example, the first payment on account ABCDEFG will be ABCDEFG-001 and the fourteenth will be ABCDEFG-014.
If you are using a two stage payment model, please remember that the second stage must be completed to debit the card.
Error
An error indicates that the account could not be set up. A complete list of Response Codes for this service is available here. The Support Centre also contains extensive examples for most error codes. Suggestions are also given to help you prevent them from occurring.
Reporting
The Recurring Transaction Fire and Forget Accounts are detailed in theRecurring section of the MasterCard Payment Gateway Services Reporting system. There are five main pages:
For Accounts:
Account Summary - gives a summary of the accounts
Account List - shows specific details of the accounts
Account Details - shows full details of each account, with links to view the full details of each payment taken from the account
For Notifications:
Notification Summary - gives a summary of the notifications sent
Notification List - shows specific details of the notifications sent, with links to the both the original recurring account and the payment for each notification
The payments taken from the accounts are detailed in the Bank Card section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Summary - gives a summary of the transactions
List - shows specific details of the transactions
Details - shows full details of each transaction
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Historic Recurring Cards
This Service allows repeat payments to be processed on a Recurring Transaction Merchant ID for any Amex, Visa or Mastercard branded card. When the first payment is taken from the card, an account is also set up at MasterCard Payment Gateway Services. When you wish to perform a recurring payment, the details of this account are passed to the DPG instead of the card details. This allows you to remain in control of the timings and value of each payment, while removing the need to store sensitive card details within your own systems.
To use this service, your account will be configured with your recurring MID and also your normal MID (either e-Commerce or MoTo).
Many aspects of this service are similar to the Bank Card Service.
There are three stages to setting up an account and taking payments from it:authorisation of the first payment, authorisation of subsequent payments andsettlement.
Authorisation of Initial Payment:
Once the payment details have been collected and sent to MasterCard Payment Gateway Services, they are immediately sent to your Acquiring Bank for authorisation. Your Bank forwards the request to the Card Issuing Bank. The Issuing bank checks the card details against their own systems and return an authorisation code if they approve the transaction.
For successfully authorised transactions, an account will be automatically setup.
The full transaction response - including the outcome of the transaction and details of the account - is then passed back to your system.
Authorisation of Subsequent Payments
When you wish to take a subsequent payment from the card, the details of the card's account are passed to MasterCard Payment Gateway Services. The DPG locates the account and uses the card details recorded against it to send the transaction for authorisation against your recurring MID. The result of this transaction is then passed back to your system.
Settlement of Payments
The settlement process for the initial and subsequent payments is the same as for normal Credit and Debit Card transactions.
Requirements
Before you can go live with this service, you will need the following:
an account with MasterCard Payment Gateway Services configured for this Service
an e-Commerce or Mo/To Merchant ID
a recurring Transaction capable MID
the ability to send XML transactions to our servers
Transaction Processing Models
Using this Service, each transaction can be processed with either the one stage or the two stage processing models. The transactions can also be cancelled and refunded if required. Full details of these models and transaction types are available in the Bank Card page.
Transaction Type |
Effect |
---|---|
setup |
Performs an initial charge against the MID of your choice. If successful, it also sets up the account for the card |
historic |
Makes a payment on the account |
cancel |
Can be used to either cancel the account, or a payment |
Performing Transactions
Both transaction types require specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Initial Payment and Account Setup
When setting up an account, the normal transaction and card information should be provided. This is the exactly the same as for the Bank Card Service, details are available here.
In addition, there are two extra pieces of information:
the type setup - to indicate that a Historic Recurring set up account is required in addition to the payment
the capture method for the initial transaction, one of:
ecomm - the transaction is an e-Commerce transaction
cnp - the transaction is a MoTo transaction
cont_auth - a recurring transaction. This should only be used if you have previously processed recurring transactions for the customer, but are transfering the processing of these to MasterCard Payment Gateway Services.
Taking Subsequent Payments
When you wish to take subsequent payments, the following information is presented in the place of the card details:
the MasterCard Payment Gateway Services reference of the original transaction
the type historic - to identify the transaction as a Historic Recurring transaction
Cancelling an Account or Payment
Both accounts and transactions can be cancelled. Exactly the same information is needed for both of these as for cancelling a normal Credit and Debit card transaction.
Response Codes
The basic Response types for the initial authorisation are the same as for the Bankcard service. This means the basic Response types for this service are:
Accepted
Declined
Referred
Error
Accepted
Once a transaction is accepted, your system can complete the normal ordering process. If you are using the two stage payment model, please remember that the second stage must be completed to debit / credit the card.
Errors
A complete list of Response Codes for this service is available here. The Support Centre also contains extensive examples for most error codes. Suggestions are also given to help you prevent them from occurring.
Reporting
The transactions are detailed in the Bank Card section of Reporting, in the same fashion as normal Bank Card transactions.
The accounts are detailed in the Recurring section. There are three main areas:
Summary - gives a summary of the accounts
List - shows specific details of the accounts
Details - shows full details of each account individually
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Capture Method Recurring Transaction Service
The Capture Method Recurring Transaction Service allows repeat payments to be processed on a Recurring Transaction Merchant ID for any Amex, Visa or MasterCard branded card. It operates in a very similar way to the Bank Card Service. If you are already using the Bank Card service, the Capture Method Service can be added easily to your existing processes as it only requires one single extra piece of information to be submitted with each transaction.
To use this service, your account will be configured with your recurring MID and also your normal MID (either e-Commerce or MoTo). When submitting a transaction to the DPG, an additional flag specifies whether you wish the transaction to be processed as a normal transaction or as a recurring transaction.
The initial transaction on a card is flagged for your normal MID and all subsequent debits are flagged for your recurring MID. If you wish to return funds to the card, this should be done using your normal MID.
Requirements
Before you can go live with this service, you will need the following:
an account with MasterCard Payment Gateway Services configured for this Service
either an e-Commerce or MoTo MID
a recurring Transaction capable MID
an application integrated with the MasterCard Payment Gateway Services Bank Card Service
the ability to send XML transactions to our servers
Transaction Processing Models
Each Capture Method Recurring Transaction can be processed with either the one stage or the two stage processing models. The transactions can also be cancelled and refunded, if required, in exactly the same way as for Bank Card transactions. Full details of these models and transaction types are available in the Bank Card section.
Performing Transactions
When using this service, the normal transaction and card information should be provided; this is the exactly the same as for the Bank Card Service.
In addition, the capture method for each transaction needs to be specified. This specifies which environment - and hence the MID - the transaction will be processed against. The capture methods are:
ecomm - the transaction is to be processed using the e-Commerce MID
cnp - to be processed using the MoTo MID
cont_auth - to be processed using your recurring MID
If you are using NatWest as your Acquirer, each cont_auth transaction should also indicate which environment the initial transaction was processed in.
Response Codes
The Responses returned for the Capture Method Recurring Transaction Service are the same as those returned for the Bank Card Service. Transactions can be Accepted, Declined and Referred.
A complete list of Response Codes for this service is available here.
Reporting
The transactions processed using this service are displayed in the Bank Cardsection of Reporting in the same fashion as non-capture method transactions.
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Tokenization - Technical Overview
Merchants wishing to accept multiple payments from a customer’s bank card, without PCI DSS burden of requesting and retaining the card number for every transaction, have the option of submitting encrypted data (a ‘token’ or a ‘reference’) associated with the customer’s card number or previously authorised transaction via MasterCard Payment Gateway Services Payment and Card Tokenization solutions.
Tokenization solution enables merchants to convert Bank Card numbers into tokens either during a Bank Card authorisation (as a bi-product), or to migrate card data to MasterCard Payment Gateway Services in return for a unique 40 character alphanumeric token (card tokenization) or a 16 numeric digit MasterCard Payment Gateway Services reference number (payment tokenization).
The token or reference number can then be submitted for all subsequent payment requests, thus removing the burden of storing sensitive card data internally and reducing PCI DSS compliance requirements.
Easily integrated with any existing Merchant website, call centre or mobile app; both tokenization solutions can be used in conjunction with MasterCard Payment Gateway Services Fraud Prevention tools, 3-D Secure and MasterCard Payment Gateway Services Hosted Pages Solutions. Both methods can be added as an extension to an existing MasterCard Payment Gateway Services integration, without disrupting the merchant’s payments workflow.
MasterCard Payment Gateway Services offers two options within the Tokenization Solution, of which the key product feature differences between each are highlighted below:
Payment Tokenization |
Card Tokenization |
Payments tokenized as a bi-product of processing successful transactions |
Cards tokenized as a bi-product of processing successful transactions or via a standalone tokenization process without authorisation |
1. Functionality The reference can be used in place of the card number with the merchant only needing to capture the card security code (CVV) and expiry date to authorise subsequent transactions. 3-D Secure is compatible with payments initiated using reference numbers. References for subsequent payments are only obtained as a bi-product of processing successful transactions. The reference is unique to the transaction not the card number |
1. Functionality The token can be used in place of the card number with the merchant only required to capture the card security code (CVV) and expiry date to authorise subsequent transactions. 3-D Secure is compatible with payments initiated using tokens. Tokens for subsequent payments are obtained as a bi-product of transaction processing or via a standalone tokenization process during which a token is generated but no authorisation occurs, enabling Merchants to batch send card numbers for token generation. |
2. Pre-set Expiry Date |
2. Pre- set Expiry Date |
3. MasterCard Payment Gateway Services Reporting |
3. MasterCard Payment Gateway Services Reporting |
Payments Flow
Dependent on the action the Merchant wishes to take, the payment flow experienced for both solutions will differ. Possible examples are explained below:
1. Obtaining and storing a reference during the payment process i) Merchant submits a standard authorisation request, to the MasterCard Payment Gateway. ii) MasterCard Payment Gateway Services processes the transaction request and communicates with the Merchant’s acquiring bank for authorisation iii) If successful, an auth code and 16 digit reference is returned in the authorisation response to the Merchant. iv) The reference may be used within a 13 month period to process a subsequent transaction. |
1. Obtaining and storing a token during the payment process i) Merchant submits a standard authorisation request to the MasterCard Payment Gateway
|
2. Transaction using a MasterCard Payment Gateway Services Reference i) Although the transaction process is the same as above, instead of sending the customer’s card details to the MasterCard Payment Gateway, the Merchant submits a simple XML request containing theMasterCard Payment Gateway Services reference numberassociated to the previous transaction, along with the other card information (security code, amount, reference etc). ii) The MasterCard Payment Gateway locates the Card Number from the previous transaction and submits an authorisation request to the Merchants’ acquiring bank. iii) On receipt of a successful transaction, the authorisation code, along with a new MasterCard Payment Gateway Services reference number, is then passed on to the Merchant to store and use within a 13 month period. |
2. Transaction using a token i) Using a previously generated token, the merchant submits an authorisation request to the MasterCard Payment Gateway including token and card expiry date. MasterCard Payment Gateway Services will validate the token has been generated from a previous transaction or tokenized request. |
3. Requesting a reference without authorising a payment References used for the purposes of an authorisation request can only be obtained as a bi-product of the transaction authorisation process.
|
3. Requesting a token without authorising a payment i) If a Merchant wishes to tokenize a card number without debiting the card, the Merchant need only submit a tokenization request containing the card number. ii) Once the tokenization request is received and has been validated by the MasterCard Payment Gateway, the token is then generated, stored, and returned to the merchant to store for use within a 48 month period. Suitable for merchants wishing to clear internal systems of sensitive card numbers were these were traditionally stored. |
Payment Tokenization Pre-Registered Card Service
The Pre-Registered Card Service extends the functionality of the Bank Card Service. It enables new transactions to be performed on any credit or debit card which has previously been successfully authorised on your MasterCard Payment Gateway Services account within the last 13 months. When using this service, the details of the previous transaction are passed to the DPG with the transaction, instead of the card details. The DPG locates the earlier transaction and uses the card details from it to submit another authorisation request to your Acquiring Bank. This means you do not need to store sensitive card details on your system.
For all Pre-Registered transactions, the authorisation and settlement process remains exactly the same as with the Bank Card Service.
Requirements
Before you can go live with this service, you will need the following:
an account with MasterCard Payment Gateway Services configured for this Service
an application integrated with the MasterCard Payment Gateway Services Bank Card Service
the ability to send XML transactions to our servers
The service uses your existing merchant ID. It does not require a Recurring merchant ID as the transactions are not processed as recurring transactions.
Transaction Processing Models
Each Pre-Registered transaction can be processed with either the one stage or the two stage processing models. The transactions can also be cancelled and refunded, if required in exactly the same way as for Bank Card transactions.
Performing Transactions
The Existing Transaction
Any transaction which has been successfully authorised in the last 13 months can be used as the basis for a Pre-Registered transaction, regardless of its settlement status. This means that even uncompleted two stage and cancelled transactions can be used.
With the Pre-Registered Card Service, additional transactions cannot be processed once the card has expired - it is therefore recommended to store the expiry date of the card to ensure that it is still valid prior to submission to the DPG.
Performing a Pre-Registered Transaction
To submit a Pre-Registered transaction, the information required is very similar to that needed for the Bank Card Service. These pieces of information are supplied instead of the full card details:
the MasterCard Payment Gateway Services reference of the original transaction
the type - to identify the transaction as a Pre-Registered transaction
These details enable to DPG to locate the card details from the original transaction.
The remaining elements are the same as for the Bank Card Service.
Response Codes
The Responses returned for the Pre-Registered Card Service are the same as those returned for the Bank Card Service. Transactions can be Accepted, Declined and Referred.
A complete list of Response Codes for this service is available here.
Reporting
All Pre-Registered transactions are displayed in the Bank Card section of Reporting in the same fashion as the initial Bank Card transactions.
The Reporting System has the functionality to search for all Pre-Registered transactions submitted from a particular initial transaction. The MasterCard Payment Gateway Services reference numbers for existing transactions can also be retrospectively downloaded from the Reporting System, if you do not have access to them via your own system.
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Card Tokenization
The Card Tokenization Service allows merchants to store card data relating to a transaction in the form of a token, without storing the actual card number. This enables further payments to be made by supplying the token in place of the card number. Although storing a Token alleviates some of a merchant’s responsibility with respect to PCI, it does not remove it completely. A merchant who captures card data before passing it to MasterCard Payment Gateway Services is still responsible for ensuring their systems are PCI compliant.
This service can be used in conjunction with any service involving a card number. These include:
- Bank Card
- Payments to Card Collection Accounts
- PPT
- Fuels
- MPI Only
- RBS Gift Card
- Recurring Transactions
- Historic Recurring Cards
- Capture Method Recurring Transactions
- Pre-Registered Card Service
- Fully Hosted Payments Pages
- Hosted Card Capture
- Batch Input
When using this service, there are two stages. The first tokenizes card details as they are used. The second stage is to use that token for a subsequent transaction.
Tokenize a card number
When using this service, your MasterCard Payment Gateway Services account will be configured with a shared secret key. The shared secret is pre-configured or a specific merchant defined shared secret can be provided to MasterCard Payment Gateway Services. Alternatively the shared secret can be provided with each transaction. Each time a card number is sent to your account, MasterCard Payment Gateway Services will use a Secure Hash Algorithm and shared secret to encrypt the card number and convert this to a unique token . The token will be returned within the transaction response.
The card payment details can collected from the cardholder via the MasterCard Payment Gateway Services Hosted Payment page or from within your own systems. Tokens will be generated each time a card payment is submitted to your account. Tokens can also be generated without making a payment on the card and may be shared across multiple accounts.
Using Tokens
When you wish to take a payment from a card token, simply send the token in the place of the card number.
Requirements
Before you can go live with the Card Tokenization Service, you will need the following:
- A MasterCard Payment Gateway Services account configured with a Card Processing service.
- The Card Tokenization Service configured on the account.
- A shared secret key configured on the account. You may provide your own key, or MasterCard Payment Gateway Services will generate a key on your behalf
If you have more than one MasterCard Payment Gateway Services account and wish to use tokens generated on one account on the others, these will be configured as a vTID group with the same secret key.
Transaction Processing Models
Using the Card Tokenization Service, there are three ways in which cards can be allocated tokens. By sending a:
- normal transaction with a card number.
- tokenize transaction.
- query on an existing transaction.
Transaction Type |
Effect |
auth, pre, refund, erp, txn_refund, fuel_validate, fuel_offline_auth_settle, fuel_online_auth, fuel_settle, mpi, top_up, redeem, refund, balance_enquiry, reversal |
Processes card transaction as normal. Token is included in response |
query |
Returns details of existing transaction, plus token |
tokenize |
Turns a card number into a token |
Once a card number has been tokenized by any one of these three methods, it may be used in place of the card number for any transaction.
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Tokenize a card number
Once the Card Tokenization Service is configured on your account, all attempted authorizations and query transactions will automatically return the token for that card.
If you wish to tokenize a card number without attempting authorization, the following details are required:
- unique reference number generated by your system - to allow the transactions to be distinguished from each other
- the transaction type of tokenize
- the card number
All transactions will automatically use the shared secret key which is configured on your account. If you wish to use a different key, this may be supplied within the transaction.
All tokens have an initial lifespan of four years. Each time the token is subsequently used, it's lifespan will be re-set back to four years.
Using Tokens
In order to use an existing token to take a payment from, simply supply the token instead of the card number. As the token only relates to the card number, any other information specific to the card - such as cv2 and expiry date - must be supplied separately if this is required for the transaction type you are using.
Expire Token or Re-tokenize a card number
Any existing token may be cancelled and replaced by a new one, if required. This is done by sending a tokenize transactions, along with a new shared secret key.
Response Codes
There are a range of response codes that may be generated when using Card Tokenization.
A complete list of Response Codes is available in the Developers Area. The Support Centrealso contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The Reporting Details page will display the token for any transaction which has been processed using a token, or for which a token has been generated.
Subscribed merchants will be able to search for transactions using the token.
The Reporting System also enables tokens to be downloaded via configurable CSV.
Chip and PIN Service
This document is a technical introduction to the Chip and PIN Service. It assumes the reader has some familiarity with the Cardholder Not Present Bank Card service. Further detailed information to assist integration with the Service is available in the Developers Guide.
The MasterCard Payment Gateway supports Card Holder Present transactions using the following input methods:
- legacy Magnetic Stripe - the data is swiped from the magetic card stripe
- legacy PAN Key Entry - the data is keyed into the terminal
- Chip and PIN - the data is taken from the chip while the card is parked in the POS terminal
There are three different ways in which authorisations for the Service may be submitted: always off-line, always on-line and predominantly off-line:
Always Off-Line
In this mode of operation, no transactions are submitted to the DPG for authorisation. The transactions are manually authorised and their details are stored in a log. At the end of the day, all the transactions in the log are submitted to the DPG for settlement, along with the authorisation code. This can be done using the Batch Input Service if required.
Always On-Line
Using this mode of operation, all transactions are submitted to the DPG for authorisation in real time.
Predominantly Off-Line
In this mode of operation, some of the transactions are processed in on-line mode and the remainder are processed off-line.
Requirements
Before you can go live with this service you will need the following:
- an account set up with MasterCard Payment Gateway Services,
- the ability to send XML transactions to the DPG
Transaction Processing Models
There are two different models for processing transactions:
- one transaction authorisation - the transaction is sent to MasterCard Payment Gateway Services and is automatically settled.
- two transaction authorisation - the initial transaction is sent to MasterCard Payment Gateway Services for authorisation, but is not settled. A subsequent transaction is submitted to settle the transaction. This is only available for on-line tranasctions.
The transaction types which are used for the Service are:
Transaction Type |
Effect |
Uses |
---|---|---|
creditcheck |
Obtains authorisation without settlement |
The initial transaction of the two transaction on-line model |
auth |
Obtains authorisation and is automatically settled |
One transaction on-line model |
Uses previously issued authorisation code to settle transaction |
Off-line transactions. Or the second transaction for the two transaction on-line model |
|
cancel |
Cancels and reverses existing unsettled transaction |
Any transactions |
Always Off-Line
In this mode of operation, auth transactions are manually authorised and are entered into the retailers log. They are submitted to the DPG at the end of the day, and are automatically settled. The transactions may be cancelled before settlement if required.
Always On-Line
Using this mode of processing, there are two ways to achieve authorisation:
- creditcheck - the transactions are submitted for authorisation codes and are not settled. The authtransaction type is then submitted using the authorisation code of the initial transaction and the authis automatically settled.
- auth - the transactions are submitted for authorisation and are automatically settled.
Both transaction types may be cancelled, though in practice as only auth are settled, these are the only ones which may need cancelling.
Predominantly Off-Line
In this mode of operation, most of the transactions are processed off-line as auth transactions. They are manually authorised and are retained in a log which is submitted at the end of the day.
The remainder of the transactions are processed in on-line mode. There are two ways in which the online transactions may be submitted.
- creditcheck - the online transactions are submitted for authorisation and are not automatically settled. The authorisation code obtained is then added to the retailers log as an auth transaction type and are submitted for settlement later along with the off-line transactions
- auth - the online transactions are automatically settled.
Both auth and creditcheck transaction types may be cancelled, though in practice as only auth are settled, these are the only ones which may need cancelling.
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
On-Line and Off-Line Transactions
The following information can be provided for transactions:
- the transaction method, either auth or creditcheck
- the value and currency of the sale
- the cashback amount, if requested by the customer
- details of the terminals capabilities
- the technique used to obtain the data from the card, either parked, keyed or swiped
Additional details about the card must be obtained from the chip or magnetic stripe if the card is parked or swiped. Please refer to the Developers Guide for full details.
When the transaction has been authorised, the authorisation code should also be presented.
If the XML Batch Input Service is being used to submit the off-line transactions, the same fields can be provided.
Cancellation & Reversal of Transactions
A transaction can be cancelled by providing the same information as for the Bank Card Service. If you require the transaction to also be reversed, can also be indicated in the transaction.
Return Codes
The three basic Bank Responses for authorisation requests are the same as for the Bank Card:
- Accepted
- Declined
- Referred
In addition there are various error codes that can be returned. Many of these are general error codes which may also be generated by the Bank Card Service, but there are some errors that are specific to the Card Holder Present Service.
The Support Centre also contains extensive examples for most error codes. Illustrations and suggestions are given to help you prevent them from occurring.
Reporting
The transactions are detailed in the Bank Card section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
- Summary - gives a summary of the transactions
- List - shows specific details of the transactions
- Details - shows most details of each transaction
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Pre-allocated Reference Chip & Pin
This Service enables a reference number to be allocated on the MasterCard Payment Gateway (DPG) for a transaction before the payment details are submitted to MasterCard Payment Gateway Services. This means that once the payment details are submitted to the DPG, if a communication error prevents you from receiving any response, you may use the allocated reference number to check on the status of the transaction using the Reporting facility, or to automatically cancel the payment.
This service may only be used for Card Holder Present transactions.
Requirements
Before you can go live with Preallocated Reference transactionsyou will need the following:
An account set up with MasterCard Payment Gateway Services, configured with the CHP service
The ability to send XML transactions to the DPG
Transaction Processing Models
Using this service, an initial allocate_reference transaction is submitted to MasterCard Payment Gateway Services.
Transaction Type |
Effect |
Uses |
---|---|---|
allocate_reference |
Generates a MasterCard Payment Gateway Services reference |
Enables any subsequent payment request to be cancelled, even if the result of the payment is not known |
When the payment is submitted using the allocated reference, it can be processed as either a creditcheck or an auth transaction type - in exactly the same way as for normal Chip and PIN transactions.
The payments may be cancelled if required using the allocated reference.
Performing Transactions
In addition to the fields listed below, all transactions must contain a clientand a password field for authentication purposes.
Allocate Reference
In addition to the standard fields mentioned above, you mustprovide the following information when preallocating a reference:
The transaction type allocate_reference
A unique reference number generated by your system - to allow the transactions to be distinguished from each other
Once allocated, a reference must be used within five minutes orelse it will expire.
Taking Payments with an Allocated Reference
When taking a payment using a pre-allocated reference, exactly the same information must be presented as for the Chip and PIN service, with the allocated reference number taking the place of the reference number
Cancelling Transactions
Cancellations and reversals of the transactions using this Service are performed in exactly the same way as for a normal Chip and PIN transaction.
Return Codes
The basic return codes for transactions remain the same as for the Chip and PIN Service
In addition there are various error codes that can be produced specifically by this service.
The Support Centre also contains extensive examples for most error codes. Illustrations and suggestions are given to help you prevent them from occurring.
Reporting
All transactions performed using this service will appear in the Bank Cardsection of Reporting. There are three main pages:
Summary - gives a summary of the transactions
List - shows specific details of the transactions
Details - shows full details of each transaction. This page will not be available for any unused preallocated references
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Hosted Pages Solution
MasterCard Payment Gateway Services provides a hosted pages solution to radically reduce the burden of PCI DSS compliance for Merchants. The solution fronts the rich functionality and high service level payment processing already provided by the MasterCard Payment Gateway.
Consistent functionality includes multi-currency, multi card type, high availability, security, resilience, fraud prevention tools and access to the management reporting system.
The solution is easily integrated with any existing Merchant website, call centre or mobile app, allowing retained control of look, feel and branding and preventing customers from feeling they are being moved to another site to make payment.
Key Product Features:
MasterCard Payment Gateway Services Hosted Pages Solutions capture and transmit sensitive card data (PAN – Card Number, CV2, Expiry Date, Issue Number – where relevant) from within the Merchant’s usual payment workflow/ checkout process.
Sensitive card data is entered within a secure page hosted by MasterCard Payment Gateway Services – Merchants are given the flexibility to display this page using a pop-up, redirect or iframe model.
MasterCard Payment Gateway Services can provide a default page template as a guide, which Merchants are then able to customise as they see fit (providing mandatory data fields remain unchanged).
The solution can be used as an extension to an existing MasterCard Payment Gateway Services integration with minimum changes required to a Merchants payments workflow. For full technical details please see the MasterCard Payment Gateway Services Developers guide.
Placeholders are available to allow the Merchants to display dynamic fields on the payment page – e.g. customer name, or product name.
MasterCard Payment Gateway Services offers 2 variations to the Hosted Pages Solution – difference between each highlighted below:
Hosted Card Capture (HCC) |
Hosted Pages (HPS) |
Dynamic Capture Fields - |
Dynamic Capture Fields -
|
Card Type Identification - |
Card Type identification - |
Merchant controls theauthorisation process by managing the flow of XML requests to MasterCard Payment Gateway Services, including 3-D Secure authorisation if required. |
MasterCard Payment Gateway Services manages authorisation process, including 3-D Secure authorisation if required |
Payments Flow
Hosted Card Capture (HCC) |
Hosted Pages (HPS) |
When a card transaction is processed using HCC hosted model, the three following actions are made, each of which makes a call to the MasterCard Payment Gateway: |
When a card transaction is processed using HPS, the actions are similar to that in the HCC model, there are less calls made to the MasterCard Payment Gateway: |
1. Setting up an HCC Session: |
1. Setting up an HPS Session and Processing the Transaction: |
2. Querying the Captured Data: |
2. Querying the Captured Data: The response to this request will also include card scheme, country of issue, expiry date, card issuer and the masked PAN (card number) where applicable. |
3. Processing a Transaction: |
Fully Hosted Payments
The Hosted Payments Service enables the payment process to be performed on a customisable webpage hosted by MasterCard Payment Gateway Services, rather than capturing sensitive card details on a website or call centre application. Using this method of integration will lessen the responsibilty of complying with PCI DSS, as card details are captured from the outset by MasterCard Payment Gateway Services. Payments can be made using Credit cards, Debit cards and PayPal.
There are four stages to the payment, these are outlined below.
re-direct customer to MasterCard Payment Gateway Services Hosted Payment Page
authorisation
query
settlement
Re-direction of Customer
Once the customer is ready to proceed to payment, your application sends a request to MasterCard Payment Gateway Services. This include information that has been collected on the customer (from the website or call centre application).
A Hosted Payment Session will be created for that transaction and an XML response returned containting details which are used to re-direct the customer to the Hosted Payment Page.
Authorisation
Once diverted to the MasterCard Payment Gateway Services Hosted Payment Page, the customer is presented with your payment page.
Card Payment
On the MasterCard Payment Gateway Services Hosted Payment Page, the customer is presented with the opportunity to enter their card details.
Once the customer has entered these details, they will be stored by MasterCard Payment Gateway Services. If the transaction has been flagged as an e-Commerce payment and 3-D Secure is required, MasterCard Payment Gateway Services will manage the cardholder authentication process. If the card is enrolled, the Hosted Page will display the Authentication page (ACS) provided by the Issuing Bank. This page enables the card holder to authenticate themselves directly with their Issuing bank before being returned to a pre-determined URL.
If the card is not not enrolled for 3-D Secure or 3-D Secure has not been requested, MasterCard Payment Gateway Services will mangage the payment through to completion and then re-direct the customer to a pre-determined URL.
Once complete, the cardholder is re-directed back to your website.
PayPal
If the customer chooses to pay via PayPal, the Hosted Page will re-direct them to the PayPal website. The customer authenticates themselves and is re-directed back to the Hosted Page to confirm the payment.
Once complete, the cardholder is re-directed back to your website.
Query
To obtain details of the outcome of the payment, your website may send a followup transaction. This will returns details of each payment attempt.
Settlement
Card Payment
To transfer the money between you and your customer, the authorised transaction needs to be settled by your Acquiring Bank.
Each day, MasterCard Payment Gateway Services collate all the completed authorised transactions and submit them to your Acquiring Bank, who then settle the transactions. This process takes place every working day at midnight, which means that transactions are settled next working day.
Your Acquirer will typically take three to five working days to settle the transaction. Please contact your Acquirer for more information regarding settlement times.
PayPal
Once a successful PayPal transaction has been completed, the funds are automatically transfered from the Payer's account into your PayPal merchant account.
Requirements
Before you can go live with the Hosted Payment Service, you will need the following:
A MasterCard Payment Gateway Services account
Hosted Payment Service configured on the account
For payments via Cards - A merchant account or merchant ID (MID) with one of the Acquiring Banks that MasterCard Payment Gateway Services are integrated with, for each currency you wish to trade in.
If using PayPal - a PayPal Merchant account and your MasterCard Payment Gateway Services account to be configured for PayPal
A valid secure return URL on your website. Once your customer has entered their payment details, they will be re-directed by MasterCard Payment Gateway Services to this URL
One or more customised Payment Pages configured on your MasterCard Payment Gateway Services account. A default page will be used if you do not provide a customised one
A customised error page configured on your MasterCard Payment Gateway Services account, to be shown if the customer reaches the maximum payment attempts configured on your account
In addition, you may also wish to have:
A valid expired return URL on your website. The user will be re-directed by MasterCard Payment Gateway Services to this URL if they have not completed the payment within three hours
Design of Payment Page
The design of the hosted page is fully customisable. Multiple pages may be configured on a single account, enabling the design of pages for different regions and brandings. Pages could be created in languages other than English and can be designed to return specific errors back to the cardholder in that language. The maximum number of payments attempts may also be configured.
Nine place holders are available to show additional information on the payment page. Examples of information commonly displayed on the payment page via a place holder is Cardholder Name or a Call Centre telephone number. Place holder information is provided in the initial XML request to MasterCard Payment Gateway Services.
Transaction Processing Models
There are two types of Transaction Processing Models which can be used to submit payments to MasterCard Payment Gateway Services.
One Stage processing - the transaction is authorised and then settled automatically. If you are using this model, you do not need to contact the MasterCard Payment Gateway Services servers to initiate settlement.
Two Stage processing - the transaction is authorised, but settlement is delayed until you are ready to proceed. If you are using this model, you will need to contact the MasterCard Payment Gateway Services servers twice - once for authorisation and again for settlement.
Each time a Hosted Payment transaction setup is submitted to the MasterCard Payment Gateway, it contains the information that determines the model to be used for that transaction.
In both models, the authorisation of the payment takes place in real time. The difference between each model lies in the settlement process.
Regardless of the transaction model you employ, each session setup request needs to be flagged with the following transaction type:
Transaction Type |
Payment Type |
Effect |
---|---|---|
setup_full |
All |
Passes transaction information to MasterCard Payment Gateway Services and obtains details used to re-direct the customer to hosted page |
Once the cardholder has successfully completed the payment, it can be refunded or cancelled if required. This is available to both processing models without additional account configuration.
One Stage Processing
The One Stage model will send transaction details to your Acquiring Bank for settlement on the next settlement day. This process will charge the card holder without requiring any additional action from yourselves.
Situations in which this could be implemented include:
Instant access services - such as software downloads
Ticketing systems - such as airline and train reservation services
The transaction types that can be used with the one stage model are:
Transaction Type |
Payment Type |
Effect |
---|---|---|
auth |
Card Payments |
Automatically settles successful card transactions next settlement day |
PayPal Payments cannot be made as one stage transactions.
Two Stage Processing
The delayed settlement model enables you to settle the transaction at your convenience. The transaction is authorised, but is not automatically settled. Settlement takes place once the second stage has been initiated by your systems.
Situations in which this could be implemented include:
Physical goods that will be shipped same day
Ordered Items are not currently available
Additional in-house processes need to be completed prior to settlement
The transaction types that can be used with the two stage model are:
Transaction Type |
Payment Type |
Effect |
---|---|---|
pre |
Card Payments |
Reserves funds on the card, but does not settle the transaction until a valid fulfill request is received |
fulfill |
Card Payments |
Initiates settlement of a valid pre transaction |
set_express_checkout |
PayPal |
Reserves funds on the paypal account, but does not settle the transaction until a valid do_capture request is received |
do_capture |
PayPal |
Initiates settlement of a valid PayPal transaction |
Query Results
Once the cardholder has been redirected back to your website, you will want to know the outcome of the payments attempted within the session. This can be used with both payment models and payment types. The transaction type to use for this is:
Transaction Type |
Payment Type |
Effect |
---|---|---|
query |
All |
Used to determine the overall outcome of the session. Also used to gain detailed information about the individual payment attempts |
Once your system has queried the result of the session, you may also query any of the individual payment attempts to determine more details about those transactions.
Cancelling Payments
Transactions may be cancelled before settlement, if required.
For card payments, one stage transactions and completed two stage transactions can be prevented from debiting (or crediting) the card using the cancel transaction type. This will prevent an authorised transaction from being settled and can therefore only be used before the transaction has been settled.
For PayPal payments, this transaction type also releases the remaining reserved funds.
Situations in which this could be implemented include:
Customer cancellations - for systems allowing the customer to cancel an order after placement
Physical Shipment - if at shipment the goods are found to be damaged, the payment can be cancelled
Partial fulfillment (PayPal only) - if only part of the order can be completed
Transaction Type |
Payment Type |
Effect |
---|---|---|
do_void |
PayPal |
Releases reserved funds back to buyers PayPal account |
cancel |
Card Payments |
Stops one stage and completed two stage transactions from being settled |
Refunding Transaction
MasterCard Payment Gateway Services provide a specific transaction type to allow successful transactions to be refunded without needing the full card or customer details. This enables refunds to be performed on existing transactions without the need to store the full card details or PayPal user information.
Transaction Type |
Payment Type |
Effect |
---|---|---|
txn_refund |
All |
Uses an existing transaction to returns funds to a card or PayPal user. |
The original transaction can either be completely or partially refunded, and multiple refunds can be performed on one transaction until the full value of the transaction has been refunded.
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Session setup
To create a HPS session, the following information needs to be sent to MasterCard Payment Gateway Services:
a unique reference number generated by your system - to allow the transactions to be distinguished from each other
the value and currency of the transaction
the transaction type. Each transaction will contain a transaction type of setup_full, and a transaction type for card payments (auth or pre) and PayPal payments (set_express_checkout) if you offer these
details about which of the payment pages configured on your MasterCard Payment Gateway Services account you wish to present to the customer
You may also include additional information to use additional services and trigger or enhance various fraudscreening techniques:
3-D Secure
Risk
Address and Security Code Verification Service
Query
To obtain details of the outcome of the session, your website may send a query transaction:
the MasterCard Payment Gateway Services_reference of the original setup transaction
method must be query
If the first payment attempt is unsuccessful, the customer may re-attempt payment up the the maximum configured on the account. When performing the query, your website will receive the MasterCard Payment Gateway Services_reference and return code of each payment attempt. To obtain detailed information about these payment attempts, your website may submit a query for each payment attempt.
Completing the Two Stage Process
To settle a card transaction processed using the Two Stage process, a fulfill is needed. To settle a PayPal transaction, a do_capture is needed. This informs MasterCard Payment Gateway Services that you wish to proceed with the transaction. Once this has been done, the card will be charged. Only successful transactions can be fulfilled.
Card Payments
To fulfill a successful payment attempt, information from the result of the query transaction is required, in addition to the transaction type:
the MasterCard Payment Gateway Services_reference of the payment attempt
the authorisation code
the transaction type - fulfill
Transactions are normally fulfilled for the full value of the original transaction. If you wish to perform a partial fulfill, this can be done by specifying theamount in the fulfill request.
Multiple partial fulfill transactions can be submitted against a single pre, if your MasterCard Payment Gateway Services account is configured for Split Shipment.
PayPal Payments
The transfer funds from your customers PayPal account is initiated by your website. This may be performed immediately, or at a later stage:
the MasterCard Payment Gateway Services_reference of the original setup_full transaction
the transaction type - do_capture
the value and currency of the transaction
Multiple partial do_capture transactions can be submitted.
As PayPal accounts can be restricted by the PayPal fraud department at any time, the capture of funds cannot be guaranteed. It is best practise to capture the funds before the goods are shipped and not after.
Refunding Transactions
The txn_refund transaction type uses a successful transaction to perform a refund without requiring the card or PayPal User details.
Any successful auth or completed two stage transaction can be refunded in this fashion.
To txn_refund a transaction, information from the result of the original transaction is required, in addition to the transaction type:
the MasterCard Payment Gateway Services_reference
the transaction type - txn_refund
Transactions are normally refunded for the full value of the original transaction. If you wish to refund a lower value, this can be done by specifying the amount in the txn_refund request. Each transaction can be refunded several times, provided the total refunded does not exceed the value of the original.
Cancelling Transactions
Card Payments
To cancel a card transaction prior to settlement, the following information is required:
the MasterCard Payment Gateway Services_reference
the transaction type - cancel
PayPal Payments
To release reserved PayPal funds back to the buyer, a do_void can be performed, with this information:
the MasterCard Payment Gateway Services_reference
the transaction type - do_void
Response Codes
When using the HPS Service, there are four basic responses for card transactions and two for PayPal transactions:
Accepted
Declined - for card payments only
Referred - for card payments only
Error
Accepted Transactions
Once a transaction is accepted, your system can complete the normal ordering process. If you are using the Two Stage model, please remember that the second stage must be completed to complete the payment.
Declined Transactions
Occasionally, you may find a transaction is declined. There are several general reasons why a card may be declined. These include:
The card has been cancelled
The card is approaching or is past its limit and does not have enough funds to cover the full value
The Issuing bank have noticed unusual patterns of spend on the card
If a transaction is declined, the cardholder may re-attempt payment, assuming the re-try limit configured on your account has not been reached.
Referred Transactions
A referral response is part way between an accepted and a declined response. The Issuing Bank does not wish to automatically issue an authorisation code, but is providing you with the opportunity to receive a manual authorisation instead of simply issuing a decline response. If a referral response is received, the Hosted Payment System will treat this as a decline, thereby enabling the cardholder to re-attempt the payment, assuming the re-try limit configured on your account has not been reached.
The main reasons for a referral are:
the Issuer is performing a spot check
the card is approaching its limit
If none of the remaining payment attempts were successful, you may wish to simply treat these transactions in the same way as a decline. This requires no extra action on your part and enables the system to be fully automated. If you wish to proceed with the payment, you should phone the authorisation centre of your Acquiring Bank - not the cardholders bank - with the card details. The authorisation code should then be submitted to MasterCard Payment Gateway Services in order to proceed with the payment.
Error Messages
There are a small number of error messages which can be displayed to the customer. You may vary the text for each of these using Customised Validation Messages. If a transaction generates an error message, the cardholder may re-attempt payment, assuming the re-try limit configured on your account has not been reached.
A complete list of Response Codes for this service is available here. The Hosted Payment System itself can return a various error codes. In addition, each payment type & fraud screening service utilised during the payment also has it's own error codes.
The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate on how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
PayPal Delayed Settlement
These error codes will not be displayed to the customer, but will be available for you to review if a query transaction is submitted, or via Reporting.
Reporting
Card Payments are detailed in the Bank Card section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Summary - gives a summary of the transactions
List - shows specific details of the transactions
Details - shows full details of each transaction
PayPal Payments are detailed in the PayPal section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Summary - gives a summary of the transactions
List - shows specific details of the transactions
Details - shows full details of each transaction
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Hosted Card Capture
The Hosted Card Capture Service allows the capture of card details to be performed on a webpage hosted by MasterCard Payment Gateway Services, rather than on your own website. This means that the responsibilty for complying with PCI DSS lies with MasterCard Payment Gateway Services, rather than yourself, as your website is not storing or transmitting card details. The solution is easily integrated with any existing Merchant website, call centre or mobile app, allowing retained control of look, feel and branding and preventing customers from feeling they are being moved to another site to make payment. This service is primarily aimed at existing MasterCard Payment Gateway Services merchants.
When using this service, an additional capture of card details stage is introduced to the processing flow. After this step is completed, the 3-D Secure Check, authorisation and settlement proceed as normal.
Capture of Card Details
Once your customer is ready to proceed with payment, your website or call centre application sends to MasterCard Payment Gateway Services basic information about the transaction. The DPG returns information which your system uses to divert the cardholder to the Hosted Card Capture page specified. The cardholder is presented with your card capture page (appearing in the preferred method implemented - pop-up, iFrame or redirect), which will display appropriate branding and custom fields. The cardholder then enters the information as required by the page. Once complete, the cardholder is re-directed back to your website.
Your website may query the status of the capture process and obtain basic details about the card.
Requirements
Before you can go live with the Hosted Card Capture Service, you will need the following:
A MasterCard Payment Gateway Services account
A merchant account or merchant ID (MID) with one of the Acquiring Banks that MasterCard Payment Gateway Services are integrated with, for each currency and environment you wish to trade in.
A valid secure return URL on your website.
The Hosted Card Capture Service configured on the account
In addition, you may also wish to have:
A valid expired return URL on your website. The user will be re-directed by MasterCard Payment Gateway Services to this URL if they have not completed the payment within three hours
One or more customised Payment Pages configured on your MasterCard Payment Gateway Services account
Design of Payment Page
The design of the hosted page is fully customisable to your requirements. Multiple pages may be configured on a single account, enabling you to design pages for different regions and brandings. Pages can be created in languages other than English and can be designed to return any errors back to the cardholder in that language. Dynamic Data Placeholders within the hosted page can be used to specify text or images on the payment page on a per transaction basis - e.g. customer name, or product. Additional information such as cardholder name can be collected using Dynamic Capture Fields.
Transaction Processing Models
Using the Hosted Card Capture Service, you may process transactions with or without 3-D Secure. You may also use either one step auth or two step pre-fulfill settlement.
The new transaction types which are introduced when using the Hosted Card Capture Service are:
Transaction Type |
Effect |
---|---|
setup |
Obtains information which your website utilises to re-direct the cardholder to the hosted page |
query |
Used to determine status of capture and obtain details about the card |
Transactions may be refunded using refund, txn_refund or erp-fulfill. They may also be cancelled.
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Session setup
In order to obtain the URL to which the cardholder is re-directed, the following details are required:
unique reference number generated by your system - to allow the transactions to be distinguished from each other
the value and currency of the transaction
the transaction type of setup
the page_set_ID - which identifies the specific page which should be presented to the cardholder
You may also supply:
return URL - once your customer has entered their payment details, they will be re-directed by MasterCard Payment Gateway Services to this URL
expiry url
details of any additional Dynamic Data fields which are to appear on the page
Query
To obtain the details of the status of the card capture, a query transaction can be sent, this requires:
the MasterCard Payment Gateway Services reference of the original setup transaction
method must be query
Authorising the Payment
Once a customer's data has been captured, a pre or auth transaction can be sent. This will attempt authorisation on the card details entered by the cardholder.
The information needed to perform these transactions remains unchanged, expect for two pieces of information which are supplied in place of the card details:
the MasterCard Payment Gateway Services reference of the original setup transaction
the type from_hps - to identify the transaction as an Hosted Card Capture transaction
Other Transactions
The other transaction types utilised when processing a transaction via the Hosted Card Capture Service remain unchanged:
threedsecure_authorization_request
fulfill
cancel
txn_refund
authorize_referral_request
Response Codes
A complete list of Response Codes is available in the Developers Area. TheSupport Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
When using the Hosted Card Capture Service, the Bank Responses remain the same as if the payment page was hosted within your own website.
Reporting
The transactions performed via the Hosted Card Capture Service are detailed in the Bank Card section of the MasterCard Payment Gateway Services Reporting system.
Split Shipment
The Split Shipment Service allows you to perform multiple settlements against a single authorised transaction, retaining 3-D Secure liability shift for each settlement.
When performing a second or subsequent fulfillment using the Split Shipment Service your Acquiring Bank will be contacted for re-authorisation if 7 or more days have passed since the initial authorisation.
When using this service, an additional re-authorisation stage may be added to the payment flow.
Re-Authorisation
Each time a transaction is fulfilled, the DPG will check the age of the transaction being fulfilled, and the total amount already fulfilled from that transaction. If the value of the fulfill transaction plus the value already fulfilled against the transaction does not exceed the original value authorised by more than ten percent, the DPG will send a re-authorisation request to your Acquirer for the value of the fulfill.
If the transaction is over seven days old and requires a second or subsequent fulfilment, the DPG will also send a re-authorisation request to your Acquiring Bank for the value of the fulfill.
Requirements
Before you can go live with the Split Shipment Service, you will need the following
A MasterCard Payment Gateway Services account
The account to be configured for Split Shipment
Split Shipment is supported for all card types via most Acquiring Banks.
Transaction Processing Models
The Split Shipment Service is an enhancement to the Bank Card Two Stage Processing model. Once the initial pre transaction has been authorised, the funds for that transaction can be settled over several transactions.
Situations in which this could be implemented include:
Shipment of goods will be split, the cardholder can be charged for each individual shipment
Ordered Items are not available at time of original authorisation and will be shipped seven days or more after the original authorisation
Performing Transactions
When performing a second or subsequent fulfill using the Split Shipment Service, one additional element is required in the fulfill request:
Unique reference number generated by your system - to allow the transactions to be distinguished from each other
Response Codes
When using the Split Shipment Service, the response codes and error messages are the same as returned for the Bank Card Service.
Reporting
The transactions are detailed in the Bank Card section of the MasterCard Payment Gateway Services Reporting system. Additional information will be displayed for any transaction processed using this service.
Batch Input Processing
The Batch Input Service allows many of the MasterCard Payment Gateway Services to be utilised by submitting a batch of transactions, instead of submitting individual transactions as they occur.
The following MasterCard Payment Gateway Services can be accessed with the Batch Input Service:
Credit and Debit Cards Payments:
One and Two Stage Card Processing
Pre-Registered Cards
AVS checking
BACS Payments:
Direct Debits
Direct Credits
This document is intended as an overview of the Batch Input Service. Further details about the aspects of the service are available in the links above.
There are three parts to the Batch Input Service; batch submission, batch runand batch query
Batch Submission
The transaction details are first collated by your systems and placed into a file in a format specified by MasterCard Payment Gateway Services. This file is placed within an XML transaction and is submitted to MasterCard Payment Gateway Services. We perform some validation checks on the file - including verifying the security details. The results of this validation are returned within a response document.
Batch Run
Once a batch has passed the validation, it can then be processed by MasterCard Payment Gateway Services - this is called a batch run. During a batch run, additional verification checks are performed on the batch and each transaction in the batch is individually submitted to the DPG. These individual transactions follow the same processing as if they had been submitted from you directly (instead of via Batch Input). The result of each transaction is stored in the DPG and will be settled if appropriate.
Batch Query
To receive the results of the individual transactions within the file, a batch query can be made. This can either be submitted as an XML transaction directly to the DPG, or it can be performed via the Reporting System.
Requirements
Before you can go live with the Batch Input Service, you will need the following:
an account with MasterCard Payment Gateway Services configured for the Batch Input Service
the ablity to collect the results of each batch
In addition, you will also need to satisfy the requirements of each individual service you will be using.
Batch Format
There are two types of Batch Format for the Batch Input Service which can be used to submit transactions to MasterCard Payment Gateway Services:
XML format
CSV format - Comma Separated Values
For each batch, either format can be used for the transactions. There are no restrictions, extra service charges or additional account configuration required. The results of each batch will be available in the same format as the batch itself.
The two formats are available to enable you to select the format that is easiest for you to integrate with. Full details of both formats for each aspect of Batch Input are available in the Developers Guide.
XML Format
The XML format enables you to take advantage of the flexibility of XML. Using the XML format will allow you to create a single batchfile which - for example - contains:
the first stage of a two stage transaction
the second stage of an existing uncompleted two stage transaction
If you have already integrated MasterCard Payment Gateway Services real time processing, choosing the XML format for Batch Input Processing will allow you to re-use existing functionality, as the formats for the individual transactions remain the same for both types.
CSV Format
The CSV format is less flexible than the XML format, but you may find it easier to utilise. As different transaction types require different information to be supplied, only transactions which contain the same type of information can be submitted in the same batch.
For example, this means that if you are using a two stage processing model, you cannot mix first stage and second stage transactions in the same file - two files would be needed.
Performing Transactions
Whether you are using the XML or CSV format, there are two stages to processing a batchfile. The first is to submit the batch, and the second is to collect the results.
Submitting a Batch
Each time a batch is submitted to the MasterCard Payment Gateway, it contains the following information about the file:
the security details to identify your account - the client and password
a count of the number of transactions within the file
a sum of the value of transactions within the file
a unique reference number for the batch
the format name of the file
This information is required for both XML and CSV formats.
The details required for the transactions themselves will depend upon the exact details of the service that you are using. Please follow one of the links for more details:
Credit and Debit Cards Payments
BACS Payments
Once a batch has been submitted to the DPG, we will perform some basic validation to ensure it is a valid batchfile. The results of this validation are returned in real time, allowing you to instantly know if there is a problem with the batch. To allow you to quickly rectify and resubmit the data, MasterCard Payment Gateway Services will not proceed with further processing of any failed batches.
Processing a Batch
The processing of a batch - the batch run - is performed by the DPG. It requires no action on your part.
Collecting the Results of a Batch
The results of each batch can be collected via either the Reporting System or by submitting a query transaction to the DPG.
If you are using the query transaction, you will need to supply the MasterCard Payment Gateway Services reference returned to you when the Batch Input Transaction was originally submitted.
The results of the individual transactions within a successfully processed batchfile will be returned in the same format as the batchfile itself. For example, if an XML format file is submitted, the batch query will return the results of the individual transactions in an XML format.
Response Codes
A complete list of Response Codes for the Batch Input Service is available here. The Support Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate on how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The Batch Input files are detailed in the Batch Input section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
The Batch Input files are detailed in the Batch Input section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Summary - gives a summary of the batches submitted to your account
List - shows specific details of the batch
Details - shows full details of each batch, with links to show the full details of each individual transaction within the batch
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Batch Processing for Bank Cards
The Batch Input Service allows many of the MasterCard Payment Gateway Services Credit and Debit Card Services to be utilised by submitting a batch of transactions, instead of submitting individual transactions as they occur.
The following MasterCard Payment Gateway Services Services can be accessed with Batch Input:
The Card Processing Service, including:
One Stage Processing
Two Stage Processing
Refunds without card details
Cancellations
The Capture Method model of Recurring Transactions
The Pre-Registered Cards Service
As the data which needs to be submitted to perform Batch Input transactions for these services is the same as for real time transactions, please refer to this information via the links above.
Further detailed information to assist integration with the Batch Input Service for Credit and Debit Card Payments is available in the Developers Guide.
AVSCV2 Checking with the Batch Input Service
The Address and Postcode check can be performed - where appropriate - for Batch Input transactions if these details are provided along with the card number. If your Acquiring Bank supports the Extended AVS check, this can be used if you are using the XML format for the batch. The Standard AVS check is available to all Acquiring Banks.
Please Note - as the Card Scheme Rules state that the CV2 should not be stored, this information cannot be accepted when using the Batch Input Service.
Batch Processing for BACS Payments
The Batch Input Service allows the MasterCard Payment Gateway Services BACS Services to be utilised by submitting a batch of transactions, instead of submitting individual transactions to our servers in real time.
The following MasterCard Payment Gateway Services can be accessed with the Batch Input Service:
Direct Debit
One and Two Stage Setups
Drawdowns
Revokes
Direct Credit
Standard Direct Credit
Direct Debit Refund
CreditCard Collection Account Payment
The full functionality of these services are available through the Batch Input Service.
As the data which needs to be submitted to perform transactions for these services is the same as for real time transactions, please refer to this information via the links above.
Further detailed information to assist integration with the Batch Input Service for BACS Payments, is available in the Developers Guide.
PayPal - Express Checkout
MasterCard Payment Gateway Services Merchants can now easily create an express payment lane for Customers by adding PayPal to their checkouts via their existing integration with MasterCard Payment Gateway Services.
PayPal
PayPal, a global leader in online payments, has 157 million active account holders worldwide and is now one of the most common online payment methods. It offers any Customer with an email address a quick, easy and convenient method to pay for goods, using stored PayPal payment information and the PayPal Express Checkout facility.
As you would expect from MasterCard Payment Gateway Services, the integration of PayPal as an additional payment option has been designed to extend the transaction options and payment processing speed offered to Merchants.
Express Checkout Facility
Customers can pay easily, quickly, and securely in as few as three clicks. The Customer initiates and approves PayPal payments earlier in the checkout process, enabling shipping and billing information to be pulled from PayPal to the Merchant's website. This saves the Customer both time and hassle and in turn potentially leads to a higher sales conversion rate for the Merchant's business.
To find out more about PayPal Express Checkout click here.
Enable PayPal through the existing MasterCard Payment Gateway Services API
MasterCard Payment Gateway Services has worked with PayPal to enable the payment option in much the same way as other payment options operate through the MasterCard Payment Gateway Services API. The integration is within the standard UK platform (EDI) and is, for most Merchants, a relatively straightforward extension of their existing connection to MasterCard Payment Gateway Services. There is minimal testing once the payment authorisation call extension has been made, enabling merchants to move swiftly from application to processing payments.
PayPal Merchant Account
In order to accept PayPal payments, Merchants will require a PayPal Merchant Account. MasterCard Payment Gateway Services has worked with PayPal to provide MasterCard Payment Gateway Services Merchants with a streamlined application process. The Merchant rates and charges from PayPal for accepting PayPal payments are published on the PayPal website
To find out how to sign up for a PayPal Merchant Account click here.
Key Features
- Through PayPal, Merchants are able to receive payments online from a comprehensive range of major and localised market debit cards, credit cards and bank transfers.
- All PayPal Express Checkout transactions are PCI DSS compliant.
- PayPal transactional information is available through the consolidated reporting tool used for all MasterCard Payment Gateway Services payment mechanisms.
- Integration to PayPal through the single MasterCard Payment Gateway Services API provides consistent and straightforward integration methods and maintenance.
- A 24/7 test server places no reliance on third parties for testing and integration.
- PayPal resides alongside all products and services available in the MasterCard Payment Gateway Services range on a proven and resilient payments platform.
Key Benefits
- Merchants are able to leverage the growing network of millions of PayPal account holders. An express lane can be used to penetrate the existing 19 million active UK PayPal account holders and over 157 million active around the globe.
- Merchants can increase revenue by opening a new sales channel. Amongst UK online shoppers, more than one in two are PayPal Customers and 35% say they prefer to use PayPal as their online payment method of choice.
- Merchants will gain access to new and more local Customers and international payment methods by entering new territories with ease (203 markets and up to 26 currencies), where credit card penetration is low and acquiring facilities are difficult or impossible.
- Express Checkout, through MasterCard Payment Gateway Services, allows Merchants to remain in control of their checkout, with tight integration to their website and order management process.
- With PayPal Express Checkout, Merchants will convert more browsers into buying Customers and reduce shopping cart abandonment, with buyer conversion averaging 72%**.
- Easy integration through one single point of integration means PayPal can easily be added to a Merchant's existing MasterCard Payment Gateway Services payment page.
*Based on a 2006 survey of 200+ merchants already accepting credit cards online who then added PayPal
**Based on analysis conducted on Top 100 PayPal merchants in UK and US combined (in terms of volume) using Express Checkout.
PayPal Express Checkout -Overview
The PayPal Express Checkout allows you to authenticate a PayPal user and settle funds on their PayPal account in realtime. Successful payments can be refunded without the need to store PayPal user information. The service can be seamlessly integrated into your systems, enabling your customers and Customer Service teams to experience fast and efficient processing and management of transactions.
The default timeline setting for PayPal refunds is up to 60 days. In order to change default settings the merchant is advised to contact their Account Manager.
When using this service, there are three stages to the payment cycle:
- re-direct customer to PayPal
- authorisation of payment
- settlement of funds
Re-direction of Customer
Once the payer's details have been collected and sent to MasterCard Payment Gateway Services, they are immediately sent to PayPal. This information is used by PayPal to generate a token, which is passed back to your sysem by MasterCard Payment Gateway Services. Your systems use this token to re-direct the payer to PayPal.
Authorisation
The payer confirms the payment and is re-directed back to your website.
Settlement of funds
Once the payer is re-directed back to your website, your system sends a request to the DPG which returns details about the customer verification. If these details are in order, a further request is sent to the DPG, which results in the funds being automatically transferred from the Payer's account into your PayPal merchant account.
Requirements
Before you can go live with this Service, you will need the following:
- A PayPal Merchant account
- An account with MasterCard Payment Gateway Services configured for PayPal
Complimentary Services
The following services are complimentary to the PayPal Express Checkout Service:
PayPal Auth Capture - enables the settlement of funds to be delayed until shipment
PayPal Do Reference - enables repeat payments to be performed
Transaction Processing Models
Using this Service the payment flow for each customer needs to be completed within three hours.
Situations in which this could be implemented include:
- Instant access services - such as software downloads
- Ticketing systems - such as airline and train reservation services
The transaction types that can be used with this Service are:
Transaction Type |
Effect |
set_express_checkout |
Initiates transaction |
get_express_checkout_details |
Obtains results of customer verification process |
do_express_checkout_payment |
Transfers funds from PayPal User to PayPal Merchant Account |
txn_refund |
Returns funds from the Merchants PayPal account back to the Users PayPal account |
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Set Express Checkout
To initiate the payment flow, the following details are required:
- unique reference number generated by your system - to allow the transactions to be distinguished from each other
- the value and currency of the transaction
- the transaction type of set_express_checkout
- a return url. Once your customer has entered their details PayPal will re-direct them back to this URL
- a cancel url. The user will be re-directed by PayPal to this URL if they cancel the payment
In addition to these there are also various optional fields which can be submitted if required. These are outlined in the Developers Guide.
Get Express Checkout Details
To obtain details of the payer, the following details should be provided:
- the MasterCard Payment Gateway Services reference of the original set_express_checkout transaction
- method must be get_express_checkout_details
- unique reference number generated by your system - to allow the transactions to be distinguished from each other
Do Express Checkout Payment
To transfer funds from your customers PayPal account, the following information is required:
- the MasterCard Payment Gateway Services reference of the original set_express_checkout transaction
- method must be do_express_checkout_payment
- the value and currency of the transaction
In addition to these, there are also various optional fields which can be submitted. These include:
- shipping address details
- airline and flight details
- details of individual items within the order
Refunding Transactions
To txn_refund a transaction, information from the result of the original transaction is required, in addition to the transaction type:
- the DataCash reference –
- either the set_express_checkout or do_express_checkout for “sale” transactions
- do_capture for “order” transactions
- do_reference_transaction for subsequent payments from a billing agreement
- method must be txn_refund
Transactions are normally refunded for the full value of the original transaction. If you wish to refund a lower value, this can be done by specifying the amount in the txn_refund request. Each transaction can be refunded several times, provided the total refunded does not exceed the value of the original.
The default timeline setting for PayPal refunds is up to 60 days. In order to change default settings the merchant is advised to contact their Account Manager.
Refunds in excess of 100% are now supported. In addition to the txn_refund transaction type, the following information is required:
- the original DataCash reference –
- either the set_express_checkout or do_express_checkout for “sale” transactions
- do_capture for “order” transactions
- do_reference_transaction for subsequent payments from a billing agreement
- refund_type element populated with “other”
Eligibility for this feature will be controlled by PayPal but will explicitly not be available to gambling clients. In order to enable this feature, please consult your PayPal Account Manager to request enablement.
Response Codes
When using the PayPal Express Checkout Service, there are two basic responses for the completed payment flow:
- Accepted
- Error
Accepted Transactions
An accepted response indicates that the PayPal payment flow was successful and the money has been transfered.
These payments will have a PayPal ACK response of one of:
- Success
- SuccessWithWarnings
If a SuccessWithWarnings response is received, we advise you check for the additional warning information returned in the response.
Once a transaction is accepted, your system can complete the normal ordering process.
Error Messages
There are various errors which could be generated for this Service.
In addition to errors generated by the DPG, there are also various errors which can be generated by PayPal. For payments with a PayPal error, the PayPal ACK response will be one of:
- Warning
- Failure
- FailureWithWarning
- Error
In the event of one of these PayPal errors occuring, the DPG will return full details of the errors to your system.
A complete list of Response Codes is available in the Developers Area. TheSupport Centre also contains extensive examples for most error codes. Illustrations are given to demonstrate how they would appear in both Reporting and an XML Response. Suggestions are also given to help you prevent them from occurring.
Reporting
The transactions are detailed in the PayPal section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
PayPal - Do Reference
The PayPal Do Reference allows you to authenticate a PayPal user using Express Checkout. Repeat payments can then be taken from that PayPal account.
This service may also be used in conjunction with the PayPal Auth Capture Service to delay settlement of funds until shipment.
When using this service, there are four stages to the payment cycle:
- re-direct customer to PayPal
- authorisation of billing agreement
- creation of billing agreement (with initial payment, if required)
- collection of subsequent payments
The first stage is as outlined in the PayPal Express Checkout Service.
Payer Authorises Billing Agreement
The payer authorises the billing agreement. If you are performing an initial payment, they will also confirm that payment. PayPal will then re-direct the payer back to your website.
Creation of Billing Agreement
Once the payer is re-directed back to your website, your system sends a request to the DPG which returns details about the customer verification. If these details are in order, a further request is sent to the DPG. This results in the billing agreement being created. If you are performing an initial payment, funds for this will also be automatically transferred from the Payer's account into your PayPal merchant account.
Collection of Subsequent Payments
When you wish to take a subsequent payment from the payer, the details of the original transaction are passed to MasterCard Payment Gateway Services by your system. The DPG locates the billing agreement details and forwards the transaction to PayPal. PayPal transfer the funds and the result of this transaction is then passed back to your system.
Requirements
Before you can go live with this Service, you will need the following:
- A PayPal Merchant account
- An account with MasterCard Payment Gateway Services configured for PayPal
Transaction Processing Models
There are two payment processing models which can be used to implement the PayPal Do Reference Service. Either model can be used for each transaction. There are no restrictions, extra service charges or additional account configuration.
With Initial Payment. The billing agreement is set up and an initial payment is taken from the payer.
Without Initial Payment. The billing agreement is setup without an initial payment being taken.
In addition there are two Billing Types:
- Merchant Initiated Billing. A new billing agreement will be created for all customers.
- Merchant Initiated Billing Single Source. A new billing agreement will be created for all new customers. If an existing customer already has an active billing agreement with you, this agreement will be utilised, instead of creating a new one.
The subsequent payments which are taken from the agreement may be instant, or delayed if using the PayPal Auth Capture service.
Once the billing agreement has been setup at PayPal, it can be amended or cancelled if required. Any payments which are taken may also be refunded in exactly the same way as normal PayPal Express Checkout transactions. These features are available to both processing models without additional account configuration.
The default timeline setting for PayPal refunds is up to 60 days. In order to change default settings the merchant is advised to contact their Account Manager.
Create Billing Agreement with Initial Payment
When using this transaction processing model, the creation of the billing agreement and initial payment are triggered in the same transaction.
The transaction types that are used to create a billing agreement with this model are:
Transaction Type |
Effect |
set_express_checkout |
Initiates transaction |
get_express_checkout_details |
Obtains results of customer verification process |
do_express_checkout_payment |
Transfers funds for initial payment from PayPal User to PayPal Merchant Account. Also creates billing agreement |
Create Billing Agreement without Initial Payment
When using this transaction processing model, the billing agreement is created without performing an initial payment. Situations in which this could be implemented include:
- Payment in installments
- Charity donations
- Utility payments, such as Council Tax, mobile phones or electricity
The transaction types that are used with this model are:
Transaction Type |
Effect |
set_express_checkout |
Initiates transaction |
get_express_checkout_details |
Obtains results of customer verification process |
create_billing_agreement |
Creates billing agreement |
Take Subsequent Payment
Once the billing agreement has been successfully created, your systems initiate the subsequent payments. The subsequent payments may be instant, or delayed if using the PayPal Auth Capture service.
Transaction Type |
Effect |
do_reference_transaction |
Initiates subsequent payment from billing agreement |
Update Billing Agreement
Enables the billing agreement description or custom annotation to be updated. It also enables the billing agreement to be cancelled.
Situations in which this could be implemented include:
- billing agreement description is updated to reflect a new item or subscription added onto it
- subscription expires
- billing agreement description is updated to reflect an item or subscription removed from it
- subscription is cancelled by customer
Transaction Type |
Effect |
update_billing_agreement |
Updates information about the billing agreement, or cancels agreement |
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Set Express Checkout
The information required for the set_express_checkout is nearly the same as for the PayPal Express Checkout Service. There is one additional piece of information which is required which specifies the billing_type. This will be one of:
- MerchantInitiatedBilling - creates a new billing agreement
- MerchantInitiatedBillingSingleSource - creates a new billing agreement if the payer does not already have another billing agreement with you
If an initial payment is not to be taken, the amount supplied with the transaction must be zero.
In addition to these, there are also various optional fields which can be submitted which relate to the billing agreement.
Get Express Checkout Details
The information required for the get_express_checkout_details is the same as for the PayPal Express Checkout Service.
Do Express Checkout Payment
This transaction type will only be used if a payment is being taken immediately. The information required for the do_express_checkout_payment is the same as for the PayPal Express Checkout Service. If successful, this transaction will create the billing agreement and take the initial payment.
Create Billing Agreement
If an initial payment is not being taken, a create_billing_agreement is required to set up the agreement. To perform this, the following information is required:
- unique reference number generated by your system - to allow the transactions to be distinguished from each other
- the MasterCard Payment Gateway Services reference of the set_express_checkout
- the transaction method create_billing_agreement
- the PayPal token from the set_express_checkout
Subsequent Payments: Do Reference Transaction
To collect a subsequent payment from the billing agreement, a do_reference_transaction is required with the following information:
- unique reference number generated by your system - to allow the transactions to be distinguished from each other
- the MasterCard Payment Gateway Services reference or billing agreement ID from the do_express_checkout or create_billing_agreement transaction
- method must be do_reference
- the value to be taken from the Payers account
If you wish to use the Auth Capture service to reserve funds and take payment later, the payment_action must be set to order. In this case, a do_authorization and a docapture will also be required to reserve and settle the funds.
In addition to these, there are also various optional fields which can be submitted. These include item and shipping data.
Update a Billing Agreement
To update a billing agreement, information from the transaction which created the agreement is required, in addition to the transaction type and details to be amended:
- a unique reference number generated by your system - to allow the transactions to be distinguished from each other
- the MasterCard Payment Gateway Services reference of the create_billing_agreement or do_express_checkout_payment
- the transaction method update_billing_agreement
One or both of these fields should also be presented:
- billing_agreement_description - the new description of goods or services associated with the billing agreement
- billing_agreement_custom - the new custom annotation
Cancelling a Billing Agreement
To cancel a billing agreement, information from the transaction which created the agreement is required, in addition to the transaction type:
- a unique reference number generated by your system - to allow the transactions to be distinguished from each other
- the MasterCard Payment Gateway Services reference of the create_billing_agreement or do_express_checkout_payment
- the transaction method update_billing_agreement
- the billing_agreement_status of cancelled
Once an agreement has been cancelled, no further updates can be made to it.
Response Codes
When using this Service, the basic responses and error codes are the same as for the PayPal Express Checkout Service.
Reporting
Like the Express Checkout Service, transactions are detailed in the PayPal section of the MasterCard Payment Gateway Services Reporting system. Agreements are also visible within the PayPal Billing Agreement section of the MasterCard Payment Gateway Services Reporting system:
PayPal - Auth Capture
The PayPal Auth Capture Service allows you to authenticate a PayPal user and reserve funds on their PayPal account using Express Checkout. Settlement of the funds takes place at a later time, once you are ready to ship.
When using this service, there are four stages to the payment cycle:
re-direct customer PayPal
authorisation of payment
reservation of funds
settlement / capture of funds
The first and second stages are as outlined in the PayPal Express Checkout Service
Reservation of Funds
Once the payer is re-directed back to your website, your system sends a request to the DPG which returns details about the customer verification.
If these details are in order, further requests are sent to the DPG, which result in the funds for the full order amount being reserved on the Payer's account.
Capture of funds
Once the items within the order have been shipped, your system sends a capture request which results in the funds for that shipment being automatically transfered from the Payer's account into your PayPal merchant account.
Multiple or split shipments may be made and charged separately, if required.
It is also possible to cancel outstanding funds, if the order or part of the order is not shipped.
Requirements
Before you can go live with the Service, you will need the following:
A PayPal Merchant account
An account with MasterCard Payment Gateway Services configured for PayPal
Transaction Processing Models
Using this Service the payment flow for each customer does not need to be completed within three hours. Settlement may be delayed until goods are ready to be shipped and funds debitted from the Payers account for each shipment.
Situations in which this could be implemented include:
Physical goods that will be shipped same day
Ordered Items are not currently available
Additional in-house processes need to be completed prior to settlement
Shipment of goods will be split, the cardholder can be charged for each individual shipment
Several of the transaction methods used for this service are the same as for the Express Checkout Service. These are:
Transaction Type |
Effect |
set_express_checkout |
Initiates transaction |
get_express_checkout_details |
Obtains results of customer verification process |
do_express_checkout_payment |
Verifies payment details and creates a 29 day long order period |
txn_refund |
Uses an existing transaction to returns funds to a Payer |
Reserve Funds
Once the 29 day order period has been created, the value of the payment needs to be reserved on their PayPal Account.
Transaction Type |
Effect |
do_authorization |
Reserves funds for total value of transaction on Payers account |
A successful authorization includes an honor period of 3 days, during which PayPal will honor 100% of the authorized funds. You may request an authorization on an order up to 10 times, up to 115% of the originally authorized amount (not to exceed an increase of $75 USD). If the payment has not been captured after day 4 of the authorization period, you may initiate another authorization, which will start a new three-day honor period. However, it will not extend the authorization period past 29 days.
Capture Funds
When using this Service, no funds are settled to the merchant's account until a successful capture is complete.
Transaction Type |
Effect |
do_capture |
Transfers funds from PayPal User to PayPal Merchant Account |
Multiple do_capture requests may be performed against a single do_authorization. This enables orders which will be completed in several shipments to be individually charged as they are shipped.
As PayPal accounts can be restricted by the PayPal fraud department at any time, the capture of funds cannot be guaranteed outside of the 3 day honour period. It is best practice to capture the funds during the honour period and before the goods are shipped.
Void Outstanding Funds
Once all required funds have been captured, any remaining amount on the authorisation may be voided. This allows your system to free up the outstanding balance of the authorisation.
Situations in which this could be implemented include:
Customer cancellations - for systems allowing the customer to cancel an order after placement
Physical Shipment - not all items with the order can be shipped, the value of the outstanding funds can be cancelled
Transaction Type |
Effect |
do_void |
Releases remaining reserved funds back to the Payers account |
Performing Transactions
Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.
Set Express Checkout
The information required for the set_express_checkout is nearly the same as for the PayPal Express Checkout Service. There is one additional piece of information to provide:
payment_action needs to be set to order
Get Express Checkout Details
The information required for the get_express_checkout_details is the same as for the PayPal Express Checkout Service.
Do Express Checkout Payment
The information required for the do_express_checkout_payment is nearly the same as for the PayPal Express Checkout Service. There is one additional piece of information to provide:
payment_action needs to be set to order
If you wish to process the payment using Express Checkout, you may convert the existing transaction by specifying the payment_action to be sale.
Do Authorisation
To reserve the full value of the transaction on the Payers account, the following details are required:
the full value to be reserved on the Payers account
the transaction type of do_authorization
the MasterCard Payment Gateway Services reference of the set_express_checkout transaction. If you are using this service in conjunction with the Do Reference Service, this reference number will be taken from the do_reference transaction.
Do Capture
Once your are ready to ship items within the order, your system submits a request to initiate settlement of the funds. The information which is required for this is:
the MasterCard Payment Gateway Services reference of the do_authorization transaction
method must be do_capture
the value to be taken from the Payers account
In addition to these, there are also various optional fields which can be submitted. These include airline and flight data
If the do_capture completes the payments, you may cancel any remaining reserved funds on the account by supplying the completed field. This will mean you do not need to perform an additional do_void transaction.
Void Outstanding Funds
To release reserved PayPal funds back to the buyer, a do_void can be performed, with this information:
the MasterCard Payment Gateway Services reference of the do_authorization or do_express_checkout_payment transaction
method must be do_void
Refunding Transaction
Any successfully captured funds may be refunded using the txn_refund. The process for this is the same as PayPal Express Checkout, however the MasterCard Payment Gateway Services reference number provided in the request should the that of the do_capture.
The default timeline setting for PayPal refunds is up to 60 days. In order to change default settings the merchant is advised to contact their Account Manager.
Response Codes
When using this Service, the basic responses and error codes are the same as for the PayPal Express Checkout Service.
Reporting
Like the Express Checkout Service, transactions are detailed in the PayPal section of the MasterCard Payment Gateway Services Reporting system.
Corporate Purchasing
Purchasing Cards are issued to employees who make purchases on behalf of their company/organisation. The company guarantees the card and pays the administration costs. In return they have a paperless mechanism for tracking the purchase made by their employees.
These Purchasing Cards are linked to special accounts that produce detailed statements containing full line item detail. These statements are acceptable by Customs and Excise for VAT reporting. They are also used for submission of expense reports. Both of these uses reduce the amounts of administration associated with business purchasing.
Purchasing cards are also referred to as Corporate Cards. If your staff regularly incur business travel and entertainment expenses in the UK or whilst abroad - and if they need detailed management reporting - this is the card for your company.
Line Item Detail
VISA and MasterCard have defined three different levels of data capture and reporting for credit card transactions:
Level 1 is a traditional credit card transaction, usually including either address verification information or card swipe data.
Level 2 adds a few additional elements to the data that is captured as part of a Level 1 transaction (usually tax information and an invoice number). Information about Level 2 transactions is reported back to the company or institution that made the original purchase. This data can be used by that entity to sort, reconcile and report transactions.
Level 3 Line Item Detail is the highest of the three levels of data capture defined by Visa and MasterCard for credit card transactions. It applies only to corporate purchasing card transactions, and incorporates item by item descriptions of each component of the purchase, including full VAT details.
The company originating the transaction receives a monthly report of all captured information from their card issuer. This forms a consolidated VAT report containing all the information contained in a VAT receipt. For all transactions, irrespective of value, it eliminates the need for purchasers to collect and submit conventional VAT invoices for VAT reclamation. The data can also be used to sort, reconcile and report transactions.
The monthly consolidated VAT report is also available in electronic format, making it possible for order reconciliation, VAT reclamation and accounting to be automated. This is the level that MasterCard Payment Gateway Services supports.
Acquiring Banks
MasterCard Payment Gateway Services are currently accredited to process Corporate Purchasing Card transactions with Royal Bank of Scotland Group (NatWest Streamline), Barclaycard Merchant Services and American Express. The process of converting XML requests to the format required by the acquirers is proven and dependable. That means your own accreditation process should be smooth and uneventful.
What cards can the service process?
The MasterCard Payment Gateway Services Corporate Purchasing Card service can process all Visa Purchasing Cards, including the UK Government Procurement Cards. It does not currently support the processing of non-Visa purchasing cards.