The Bank Card Service allows you to authorize 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: authorization and settlement.
Obtaining an Authorization Code
Once the payment details have been collected and sent to Mastercard Payment Gateway Services, they are immediately sent to your Acquiring Bank for authorization. Your bank forwards the request to the Card Issuing Bank. The Issuing bank check the card details against their own systems and return an authorization code if they approve the transaction. The full transaction response including the authorization 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 authorization 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 authorization 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 authorized transaction needs to be settled by your Acquiring Bank.
Each day, Mastercard Payment Gateway Services collate all the authorized 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:
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 authorized 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 authorized, 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 authorization 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 authorization 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:
The transaction types that can be used with the one stage model are:
Transaction type |
Affect |
Uses |
Auth |
Debits the card |
Requests authorization 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 authorized, 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:
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 fulfill request is received. |
ERP |
Credits the card |
Creates a refund request, but does not settle the transaction until a valid fulfill request is received. |
Fulfill |
Completes the two stage process |
Initiates settlement of a valid pre or erp transaction. 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 to be 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 authorized transaction from being settled and can therefore only be used before the transaction has been settled.
Situations in which this could be implemented include:
Transaction Type |
Affect |
Uses |
Cancel |
Prevents settlement of a transaction |
Stops one stage and completed two stage transactions from being settled. |
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:
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 utilized 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:
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 and erp transactions can be fulfilled.
To fulfill a transaction, information from the result of the original pre / erp transaction is required, in addition to the transaction type:
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 the amount 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:
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:
Response Codes
There are three basic Bank Responses for transactions:
In addition there are various error codes that can be produced by this service.
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:
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 retry 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 authorization code, but is providing you with the opportunity to receive a manual authorization instead of simply issuing a decline response. To proceed with the payment, you should phone the authorization center 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 authorization code provided by the authorization 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 authorization code.
Additional services, such as AVSCV2 or ReD may also prevent the transaction being authorized. If this is the case, you will not be able to issue fulfill or authorize_referral_request transactions to continue processing.
Like the declines Mastercard Payment Gateway Services return the full bank response to you.
The main reasons for a referral are:
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.
Reporting
The transactions are detailed in the Bank Card section of the Mastercard Payment Gateway Services Reporting system. There are three main pages:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
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.
AVSCV2
AVSCV2 can be used with any Card Payment Service transaction, provided:
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 authorization 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:
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 authorization 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.
How does 3-D Secure work?
3-D Secure uses Three Domain and SSL Technology to provide a standardized 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 unauthorized 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
Benefits
Potential to negotiate lower rates for 3-D secure transactions with your acquiring bank.
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 authorization if required.
Authorization
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 authorization. Your bank forwards the request to the Issuing Bank, who return an authorization 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 authorization.
The full transaction response - including the authorization code if the transaction is successfully authorized - is then passed back to your system by the DPG.
Settlement
Successfully authorized 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:
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 authorized 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 authorized, 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 authorization 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:
The transaction types that can be used with this model are:
Transaction type |
Effect |
Auth |
Requests a card enrolment check |
threedsecure_authorization_request |
Submits the PARes and initiates the authorization 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 authorized, 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:
The transaction types that can be used with the two stage model are:
Transaction Type |
Effect |
Pre |
Requests a card enrolment check. |
threedsecure_authorization_request |
Submits the PARes and initiates the authorization 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 Authorization
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 conferred by the check and means the card details do not need to be re-entered.
Transaction Type |
Effect |
threedsecure_authorize_referral_request |
Enables an authorization 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:
Authorization Request
In order to proceed to authorization, a threedsecure_authorization_requesttransaction is needed. This needs two pieces of information:
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 authorization request.
Referred Authorization
To process a threedsecure_authorize_referral_request, three pieces of information are required:
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:
Examples of each response type are available in the Developers Guide.
Authorization Requests
An authorization request may generate the three basic bank responses described in the Bank Card Service:
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.
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 authorization if required.
Authorization
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 authorization. Your bank forwards the request to the Issuing Bank, who return an authorization code if they approve the transaction.
The full transaction response - including the authorization code if the transaction is successfully authorized - is then passed back to your system by the DPG.
Settlement
Successfully authorized 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 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:
Plus if the card was registered, these pieces of information taken from the PARes:
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 authorization request may generate the three basic bank responses described in the Bank Card Service:
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.
Obtaining an Authorization 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 authorization. Your Bank forwards the request to the Card Issuing Bank.
The Issuing bank authorizes 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:
The authorization code and the results of the AVSCV2 check are then both passed back to Mastercard Payment Gateway Services. If the Issuer is unable to authorize 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 authorization code of the transaction, ensuring that there are no funds reserved against the card. Most Issuers will reverse authorization 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.
Transaction Processing Models
There are three different ways in which the policy can be specified for card payments.
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 AVS information 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:
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:
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 either matched 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:
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:
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 authorized 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 authorization code and the result of the request to reverse the authorization code.
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
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 Details page.
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:
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:
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.
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:
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:
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 dependent 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.
Key Features
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
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:
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:
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.
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:
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:
In addition, these details are required:
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:
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:
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 wish to 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:
Cancelling a Drawdown
To cancel an unsettled drawdown, the following fields are required:
Response Codes
There are two basic Response types for all transactions.
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:
o Setup Summary - gives a summary of the DDIs
o Setup List - shows specific details of the DDIs
o Setup Details - shows full details of each DDI
o Drawdown Summary - gives a summary of the drawdowns
o Drawdown List - shows specific details of the drawdowns
o 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.
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:
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:
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:
Response Codes
There are two basic Response types for all transactions.
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:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Requirements
Before you can go live with this service, you will need the following:
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:
Transaction Type |
Effect |
Uses |
Ddrefund |
Refunds a DDI |
Returns funds to the account |
Cancelling a Refund
The cancel transaction prevents any unsettled refund 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:
Cancelling a refund
To cancel a ddrefund prior to settlement, the following information is required:
Response Codes
There are two basic Response types for all transactions.
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. 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 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.
Validating the Transaction
Once the details of the transaction have been sent to the DGP, a BACS approved database is used to determine whether the card Issuing Bank allows 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:
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 card account payment 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
In addition to the card information collected from the customer, these details about the transaction are also required:
Cancelling a refund
To cancel a card account payment prior to settlement, the following information is required:
Response Codes
There are two basic Response types for all transactions.
Accepted
A successful response indicates that the card collection account details have been validated and the card account ayment 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 card account payment transactions are detailed in the Direct Credit section of the Mastercard Payment Gateway Services Reporting system. There are three main pages:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
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 authorization 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 authorization 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:
Key Benefits:
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.
1. Direct Debit transactions
2. Credit Card transactions
(historic txns refer to card details of initial setup)
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
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 test server 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.
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:
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:
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:
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 flavor. All account types are set up using the transaction type drawdown.
Situations in which this could be implemented include:
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:
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:
o weekly
o monthly
o quarterly
o annually
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:
Initial Payment
To set an initial payment to be different from the regular payments, these fields should also be provided:
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:
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 the client and password - are required:
Response Codes
There are two basic Response types for all transactions.
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. 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 Continuous Authority Accounts are detailed in the DD. Cont. Auth section of the Mastercard Payment Gateway Services Reporting system. There are five main pages:
o Account Summary - gives a summary of the accounts
o Account List - shows specific details of the accounts
o Account Details - shows full details of each account, with links to view the original DDI and the full details of each drawdown taken from the account
o Notification Summary - gives a summary of the notifications sent
o 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.
Creating a Fire and Forget Continuous Authority Account
For each set of payments, a 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 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 authorization. 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:
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:
Using these, the regular payments will be taken from your customer's account. If a particular payment date falls on a non-calendar 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:
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:
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:
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:
Initial Payment
To set an initial payment to be different from the regular payments, these fields should also be provided:
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:
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:
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:
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:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
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: authorization of the first payment, authorization of subsequent payments and settlement.
Authorization 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 authorization. Your Bank forwards the request to the Card Issuing Bank. The Issuing bank checks the card details against their own systems and return an authorization code if they approve the transaction.
For successfully authorized 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.
Authorization 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 authorization 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:
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:
Taking Subsequent Payments
When you wish to take subsequent payments, the following information is presented in the place of the card details:
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 authorization are the same as for the Bankcard service. This means the basic Response types for this service are:
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:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
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:
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:
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 Card section 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 solution enables merchants to convert Bank Card numbers into tokens either during a Bank Card authorization (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 authorization |
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 authorize 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 authorize 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 authorization 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 authorization request, to the MasterCard Payment Gateway. ii) MasterCard Payment Gateway Services processes the transaction request and communicates with the Merchant’s acquiring bank for authorization iii) If successful, an auth code and 16 digit reference is returned in the authorization 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 authorization 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 authorization request to the Merchants’ acquiring bank. iii) On receipt of a successful transaction, the authorization 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 authorization 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 authorizing a payment References used for the purposes of an authorization request can only be obtained as a bi-product of the transaction authorization process.
|
3. Requesting a token without authorizing 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. |
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 authorization 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 authorization 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:
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.
The Existing Transaction
Any transaction which has been successfully authorized 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:
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.
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:
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:
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:
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:
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 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 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.
The MasterCard Payment Gateway supports Card Holder Present transactions using the following input methods:
There are three different ways in which authorizations 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 authorization. The transactions are manually authorized 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 authorization 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 authorization 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:
Transaction Processing Models
There are two different models for processing transactions:
The transaction types which are used for the Service are:
Transaction Type |
Effect |
Uses |
creditcheck |
Obtains authorization without settlement |
The initial transaction of the two transaction on-line model |
auth |
Obtains authorization and is automatically settled |
One transaction on-line model |
Uses previously issued authorization 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 authorized 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 authorization:
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 authorized 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.
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:
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 authorized, the authorization 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 authorization requests are the same as for the Bank Card:
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:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
Pre-allocated Reference Chip & Pin
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:
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 credit check 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 client and 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:
Once allocated, a reference must be used within five minutes or else 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 Card section of Reporting. There are three main pages:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
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 theauthorization process by managing the flow of XML requests to MasterCard Payment Gateway Services, including 3-D Secure authorization if required. |
MasterCard Payment Gateway Services manages authorization process, including 3-D Secure authorization 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: |
sing this method of integration will lessen the responsibility 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-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.
Authorization
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 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 authorized transaction needs to be settled by your Acquiring Bank.
Each day, MasterCard Payment Gateway Services collate all the completed authorized 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:
In addition, you may also wish to have:
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 authorized 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 authorized, 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 authorization 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 authorization 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:
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 authorized, 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:
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 authorized 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:
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:
You may also include additional information to use additional services and trigger or enhance various fraudscreening techniques:
Query
To obtain details of the outcome of the session, your website may send a query transaction:
If the first payment attempt is unsuccessful, the customer may re-attempt payment up 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:
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:
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:
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:
PayPal Payments
To release reserved PayPal funds back to the buyer, a do_void can be performed, with this information:
Response Codes
When using the HPS Service, there are four basic responses for card transactions and two for PayPal transactions:
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:
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 authorization code, but is providing you with the opportunity to receive a manual authorization 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:
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 authorization centre of your Acquiring Bank - not the cardholders bank - with the card details. The authorization 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.
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:
PayPal Payments are detailed in the PayPal section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
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, authorization 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:
In addition, you may also wish to have:
Design of Payment Page
The design of the hosted page is fully customizable 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:
You may also supply:
Query
To obtain the details of the status of the card capture, a query transaction can be sent, this requires:
Authorizing the Payment
Once a customer's data has been captured, a pre or auth transaction can be sent. This will attempt authorization 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:
Other Transactions
The other transaction types utilised when processing a transaction via the Hosted Card Capture Service remain unchanged:
Response Codes
A complete list of Response Codes is available in the Developers Area. 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.
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.
When performing a second or subsequent fulfillment using the Split Shipment Service your Acquiring Bank will be contacted for re-authorization if 7 or more days have passed since the initial authorization.
When using this service, an additional re-authorization stage may be added to the payment flow.
Re-Authorization
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 authorized by more than ten percent, the DPG will send a re-authorization 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-authorization 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
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 authorized, the funds for that transaction can be settled over several transactions.
Situations in which this could be implemented include:
Performing Transactions
When performing a second or subsequent fulfill using the Split Shipment Service, one additional element is required in the fulfill request:
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.
The following MasterCard Payment Gateway Services can be accessed with the Batch Input Service:
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 run and 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:
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:
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:
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 utilize. 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:
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:
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:
The Support Centre contains full hints and tips to help you get the most out of Reporting.
The following MasterCard Payment Gateway Services Services can be accessed with Batch Input:
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.
The following MasterCard Payment Gateway Services can be accessed with the Batch Input Service:
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, 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 authorization 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
Key Benefits
*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-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.
Authorization
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:
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:
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:
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:
Do Express Checkout Payment
To transfer funds from your customers PayPal account, the following information is required:
In addition to these, there are also various optional fields which can be submitted. These include:
Refunding Transactions
To txn_refund a transaction, information from the result of the original transaction is required, in addition to the transaction type:
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:
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 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:
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:
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. 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 transactions are detailed in the PayPal section of the MasterCard Payment Gateway Services Reporting system. There are three main pages:
Details - shows full details of each transaction
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:
The first stage is as outlined in the PayPal Express Checkout Service.
Payer Authorizes Billing Agreement
The payer authorizes 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:
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:
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:
This service may also be used in conjunction with the PayPal Auth Capture Service to delay settlement of funds until shipment. |
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: |
When using this service, there are four stages to the payment cycle: |
re-direct customer to PayPal |
re-direct customer to PayPal |
authorization of billing agreement |
authorization of 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:
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:
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:
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:
Subsequent Payments: Do Reference Transaction
To collect a subsequent payment from the billing agreement, a do_reference_transaction is required with the following information:
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:
One or both of these fields should also be presented:
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:
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:
When using this service, there are four stages to the payment cycle:
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:
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:
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 authorization may be voided. This allows your system to free up the outstanding balance of the authorization.
Situations in which this could be implemented include:
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:
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:
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 Authorization
To reserve the full value of the transaction on the Payers account, the following details are required:
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:
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:
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.
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.