MasterCard Payment Gateway API Reference: Operations -
Version 15,
Protocol: PAGE

Pay (with Hosted Payment Page)

This protocol is being deprecated by the Hosted Checkout JavaScript integration. Please see details here - Hosted Checkout.

Request to initiate a Hosted Payment Page interaction on the gateway. When the payer submits the Hosted Payment Page, the gateway initiates an Authorize or a Pay transaction depending on your transaction mode. You can customize the Hosted Payment Page displayed to the payer for business information (logo, merchant name, phone number, email address, etc.) and the display of order details.

URL https://ap-gateway.mastercard.com/api/page/version/15/pay
HTTP Method GET, POST
Authentication None required.

Request Parameters

merchant  Alphanumeric + additional characters = COMPULSORY

The unique identifier issued to you by your payment provider.
Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

order   = COMPULSORY

Information about the order associated with this transaction.
Fixed value

order.amount  Decimal = COMPULSORY

The total amount for the order.
If you provide both this value and any of the sub-total amounts (order.itemAmount, order.shippingAndHandlingAmount, order.taxAmount) then the sum of the sub-total amounts MUST equal the order.amount.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
XSD type
string
minimum length
1
maximum length
14

order.currency  Upper case alphabetic text = COMPULSORY

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.description  String = COMPULSORY

Short textual description of the contents of the order.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
127

paymentPage   = COMPULSORY

Information that controls the payer's interaction on the payment page.
Fixed value

paymentPage.cancelUrl  URI = COMPULSORY

The URL to which you want to redirect the payer's browser if they cancel their payment.
This could be a link to the payer's shopping cart, or the home page of your website.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must be an absolute URI conforming to the URI syntax published by IETF RFC 2396. The following schemes are forbidden : javascript
XSD type
string

paymentPage.merchant   = COMPULSORY

Information that allows you to display your brand and business details on the payment page.
Fixed value

paymentPage.merchant.name  String = COMPULSORY

The name of your business for display to the payer on the payment page
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

billing.address   = OPTIONAL

Information on the billing address including the contact details of the payer.
Fixed value

billing.address.city  String = OPTIONAL

The city portion of the payers address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.country  Upper case alphabetic text = OPTIONAL

The 3 letter ISO standard alpha country code of the payers address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

billing.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

The post code or zip code of the payers address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

billing.address.stateProvince  String = OPTIONAL

The state or province of the payers address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

billing.address.street  String = OPTIONAL

The first line of the address.
For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

billing.address.street2  String = OPTIONAL

The second line of the address (if provided).
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

customer.email  Email = OPTIONAL

The email address of the customer.
The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

merchant  Alphanumeric + additional characters = COMPULSORY

The unique identifier issued to you by your payment provider.
Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

order   = COMPULSORY

Information about the order associated with this transaction.
Fixed value

order.amount  Decimal = COMPULSORY

The total amount for the order.
If you provide both this value and any of the sub-total amounts (order.itemAmount, order.shippingAndHandlingAmount, order.taxAmount) then the sum of the sub-total amounts MUST equal the order.amount.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
XSD type
string
minimum length
1
maximum length
14

order.currency  Upper case alphabetic text = COMPULSORY

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.description  String = COMPULSORY

Short textual description of the contents of the order.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
127

order.shippingAndHandlingAmount  Decimal = OPTIONAL

The total shipping and handling amount for the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
XSD type
string
minimum length
1
maximum length
14

order.taxAmount  Decimal = OPTIONAL

The total tax amount for the order.
If you do not provide this value but provide line item data, then this amount is calculated as the sum of the item.quantity times the item.unitTaxAmount for all the line items (total tax amount).
If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount.
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
XSD type
string
minimum length
1
maximum length
14

order.id  String = OPTIONAL

A unique identifier for this order to distinguish it from any other order you create.
Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order you create using your merchant profile.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

paymentPage   = COMPULSORY

Information that controls the payer's interaction on the payment page.
Fixed value

paymentPage.billingAddress.displayControl  Enumeration = OPTIONAL

Indicates if you require the payer to provide their billing address on the payment page.
By default, it will be assumed that this field will be OPTIONAL.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
HIDE
Hides data fields from the payer.
MANDATORY
Displays data fields and allows the payer to enter data into these fields.
OPTIONAL
Displays data fields and allows the payer to opt out of data entry for these fields.
READ_ONLY
Data is displayed but cannot be modified.

paymentPage.cancelUrl  URI = COMPULSORY

The URL to which you want to redirect the payer's browser if they cancel their payment.
This could be a link to the payer's shopping cart, or the home page of your website.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must be an absolute URI conforming to the URI syntax published by IETF RFC 2396. The following schemes are forbidden : javascript
XSD type
string

paymentPage.customer.email.displayControl  Enumeration = OPTIONAL

Indicates if you require the payer to provide their email address on the payment page.
By default, it will be assumed that this field will be READ_ONLY.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
HIDE
Hides data fields from the payer.
MANDATORY
Displays data fields and allows the payer to enter data into these fields.
OPTIONAL
Displays data fields and allows the payer to opt out of data entry for these fields.
READ_ONLY
Data is displayed but cannot be modified.

paymentPage.googleAnalytics.propertyId  String = OPTIONAL

This is the property ID for your shop site provided by Google Analytics in the form UA-XXXXX-Y.
Provide this ID if you want to track interactions with your payment page using Google Analytics, see www.google.com/analytics.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

paymentPage.merchant   = COMPULSORY

Information that allows you to display your brand and business details on the payment page.
Fixed value

paymentPage.merchant.address   = OPTIONAL

Information on your business address.
Fixed value

paymentPage.merchant.address.line1  String = OPTIONAL

The first line of your business address for display to the payer on the payment page.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
100

paymentPage.merchant.address.line2  String = OPTIONAL

The second line of your business address for display to the payer on the payment page.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
100

paymentPage.merchant.address.line3  String = OPTIONAL

The third line of your business address for display to the payer on the payment page.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
100

paymentPage.merchant.address.line4  String = OPTIONAL

The fourth line of your business address for display to the payer on the payment page.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
100

paymentPage.merchant.email  Email = OPTIONAL

The email address of your business for display to the payer on the payment page.
For example, email address for customer service.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

paymentPage.merchant.name  String = COMPULSORY

The name of your business for display to the payer on the payment page
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

paymentPage.merchant.phone  String = OPTIONAL

The phone number of your business for display to the payer on the payment page.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
20

shipping   = OPTIONAL

Information on the shipping address including the contact details of the addressee.
Fixed value

shipping.address   = OPTIONAL

The address to which the goods contained in this order are being shipped.
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
Fixed value

shipping.address.city  String = OPTIONAL

The city portion of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.address.country  Upper case alphabetic text = OPTIONAL

The 3 letter ISO standard alpha country code of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

shipping.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

The post code or zip code of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

shipping.address.stateProvince  String = OPTIONAL

The state or province of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

shipping.address.street  String = OPTIONAL

The first line of the address.
For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.address.street2  String = OPTIONAL

The second line of the address (if provided).
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

shipping.firstName  String = OPTIONAL

The first name of the person to whom the order is being shipped.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

shipping.lastName  String = OPTIONAL

The last name or surname of the person to whom the order is being shipped.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

shipping.method  Enumeration = OPTIONAL

The shipping method code to indicate the time frame and the priority of the order.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
ELECTRONIC
Electronic delivery.
GROUND
Ground (4 or more days).
OVERNIGHT
Overnight (next day).
PRIORITY
Priority (2-3 days).
SAME_DAY
Same day.

shipping.phone  String = OPTIONAL

The phone number of the person to whom the order is being shipped.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

Copyright © 2023 MasterCard