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.

GET https://credimax.gateway.mastercard.com/api/page/version/15 / pay

Authentication

None required.

Request

Fields

billing.address OPTIONAL

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

billing.address.city String OPTIONAL

The city portion of the payers address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the payers address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
billing.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the payers address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
billing.address.stateProvince String OPTIONAL

The state or province of the payers address.

Data can consist of any characters

Min length: 1 Max 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.

Note: The transaction response will contain a concatenation of street and street2 data. If the concatenated value is more than the maximum field length, street2 data will be truncated.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.street2 String OPTIONAL

The second line of the address (if provided).

Note: This field will be empty in the transaction response, as street2 data will be concatenated into the street field.

Data can consist of any characters

Min length: 1 Max 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.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

merchant Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
order REQUIRED

Information about the order associated with this transaction.

order.amount Decimal REQUIRED

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.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.currency Upper case alphabetic text REQUIRED

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.description String REQUIRED

Short textual description of the contents of the order.

Data can consist of any characters

Min length: 1 Max length: 127
order.shippingAndHandlingAmount Decimal OPTIONAL

The total shipping and handling amount for the order.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max 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.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max 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.

Data can consist of any characters

Min length: 1 Max length: 40
paymentPage REQUIRED

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

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.

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 REQUIRED

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.

Data must be an absolute URI conforming to the URI syntax published by IETF RFC 2396. The following schemes are forbidden : javascript

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.

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.

Data can consist of any characters

Min length: 1 Max length: 20
paymentPage.merchant REQUIRED

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

paymentPage.merchant.address OPTIONAL

Information on your business address.

paymentPage.merchant.address.line1 String OPTIONAL

The first line of your business address for display to the payer on the payment page.

Data can consist of any characters

Min length: 0 Max length: 100
paymentPage.merchant.address.line2 String OPTIONAL

The second line of your business address for display to the payer on the payment page.

Data can consist of any characters

Min length: 0 Max length: 100
paymentPage.merchant.address.line3 String OPTIONAL

The third line of your business address for display to the payer on the payment page.

Data can consist of any characters

Min length: 0 Max length: 100
paymentPage.merchant.address.line4 String OPTIONAL

The fourth line of your business address for display to the payer on the payment page.

Data can consist of any characters

Min length: 0 Max 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.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

paymentPage.merchant.name String REQUIRED

The name of your business for display to the payer on the payment page

Data can consist of any characters

Min length: 1 Max length: 40
paymentPage.merchant.phone String OPTIONAL

The phone number of your business for display to the payer on the payment page.

Data can consist of any characters

Min length: 0 Max length: 20
shipping OPTIONAL

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

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.

shipping.address.city String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.country Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
shipping.address.postcodeZip Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
shipping.address.stateProvince String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max 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.

Note: The transaction response will contain a concatenation of street and street2 data. If the concatenated value is more than the maximum field length, street2 data will be truncated.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.address.street2 String OPTIONAL

The second line of the address (if provided).

Note: This field will be empty in the transaction response, as street2 data will be concatenated into the street field.

Data can consist of any characters

Min length: 1 Max length: 100
shipping.firstName String OPTIONAL

The first name of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.lastName String OPTIONAL

The last name or surname of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.method Enumeration OPTIONAL

The shipping method code to indicate the time frame and the priority of the order.

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.

Data can consist of any characters

Min length: 1 Max length: 20

Response

Fields

session.id ASCII Text ALWAYS PROVIDED

The session identifier for the hosted payment.

Include this identifier in the payment page request if you wish to return the payer to the merchant's website after completing the payment attempt.

Data consists of ASCII characters

Min length: 31 Max length: 35

Errors

error

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

Value must be a member of the following list. The values are case sensitive.

INVALID_REQUEST

The request was rejected because it did not conform to the API protocol.

REQUEST_REJECTED

The request was rejected due to security reasons such as firewall rules, expired certificate, etc.

SERVER_BUSY

The server did not have enough resources to process the request at the moment.

SERVER_FAILED

There was an internal system failure.

error.explanation String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field String

Indicates the name of the field that failed validation.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode String

Indicates the code that helps the support team to quickly identify the exact cause of the error.

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Enumeration

Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Value must be a member of the following list. The values are case sensitive.

INVALID

The request contained a field with a value that did not pass validation.

MISSING

The request was missing a mandatory field.

UNSUPPORTED

The request contained a field that is unsupported.

result Enumeration

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

ERROR

The operation resulted in an error and hence cannot be processed.