Create or Update Browser Payment Token

Request the gateway to create or update a token that references a source of funds stored with a payment provider such as PayPal.

Use this operation to initiate a browser interaction, in which the payer authorizes you to make subsequent payments against their account. For PayPal, the token wraps a PayPal Billing Agreement. Like all gateway tokens, you can:

use them for subsequent payments (PayPal calls these reference transactions)
have a token repository that includes a mix of tokenized cards, tokenized PayPal and other tokenized accounts
update a token with a different account - for example, your payer moves from PayPal to/from card as their preferred payment method, then you can retain the same token.
Your payment service provider will configure your token repository for you (see How to Configure Tokenization for details). This will determine:

If you can supply the token yourself, or if the gateway will generate one for you.
If you can update a token with a different account.
The form of the token that the gateway will generate. The generated token id is a random number. It begins with a '9' (so that is does not create a valid card number) and passes a Luhn (Mod-10) check.
When the same account is retokenized, whether the gateway return the same token or a new token.

URL https://na.gateway.mastercard.com/api/rest/version/58/merchant/{merchantId}
HTTP Method POST
Authentication This operation requires authentication via one of the following methods:
  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request Parameters

apiOperation  String =TOKENIZE_BROWSER_PAYMENT FIXED

Existence
FIXED
Fixed value
TOKENIZE_BROWSER_PAYMENT
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string

browserPayment   = COMPULSORY

Information required by the gateway to manage interactions with a browser payment provider's website.
Fixed value

browserPayment.returnUrl  Url = COMPULSORY

The same redirect URL will be used by the gateway to redirect the payer's browser irrespective of the success or otherwise of the payment.
Existence
COMPULSORY
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

session.id  ASCII Text = COMPULSORY

Values provided in the request will override values contained in the session.
Existence
COMPULSORY
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
31
maximum length
35

sourceOfFunds   = COMPULSORY

Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
Fixed value

sourceOfFunds.type  Enumeration = COMPULSORY

If you are passing card data (in any form) on the API, then you need to set this value, and also provide the card details in the sourceOfFunds.provided.card group. In the case of digital wallets or device payment methods, you must also populate the order.walletProvider field.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ALIPAY
The payer selected the payment method Alipay.
BOLETO_BANCARIO
The payer selected the payment method Boleto Bancario.
ENETS
The payer selected the payment method eNETS.
GIROPAY
The payer selected the payment method giropay.
IDEAL
The payer selected the payment method iDEAL.
KLARNA
The payer selected the payment method Klarna.
OXXO
The payer selected the payment method OXXO.
PAYPAL
The payer selected the payment method PayPal.
POLI
The payer selected the payment method POLi.
SEPA
The payer selected the payment method SEPA.
SOFORT
The payer selected the payment method Sofortbanking.
UNION_PAY
The payer selected the payment method UnionPay.
WECHAT_PAY
The payer selected the payment method WeChatPay.

apiOperation  String =TOKENIZE_BROWSER_PAYMENT FIXED

Existence
FIXED
Fixed value
TOKENIZE_BROWSER_PAYMENT
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string

browserPayment   = COMPULSORY

Information required by the gateway to manage interactions with a browser payment provider's website.
Fixed value

browserPayment.paypal   = OPTIONAL

Additional information you can provide to control the user interaction flow presented to the payer by PayPal.
Fixed value

browserPayment.paypal.agreementConfirmation  Enumeration = OPTIONAL

This field is only required when requesting a PayPal billing agreement.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AGREE
After the payer has approved the billing agreement and their browser has been returned to your website, you will not process a payment against this billing agreement at that time.
AGREE_AND_PAY
After the payer has approved the billing agreement and their browser has been returned to your website, you will process a payment against this billing agreement.

browserPayment.paypal.displayShippingAddress  Boolean = OPTIONAL

By default, the shipping address is displayed to the payer. For more detailed information about displaying the shipping address on the PayPal website, see PayPal Integration: Display/Override Shipping Address.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

browserPayment.paypal.overrideShippingAddress  Boolean = OPTIONAL

By default, the payer is allowed to change the shipping address. For more detailed information about the payer overriding the shipping address on the PayPal website, see PayPal Integration: Display/Override Shipping Address.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

browserPayment.returnUrl  Url = COMPULSORY

The same redirect URL will be used by the gateway to redirect the payer's browser irrespective of the success or otherwise of the payment.
Existence
COMPULSORY
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

correlationId  String = OPTIONAL

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

session.id  ASCII Text = COMPULSORY

Values provided in the request will override values contained in the session.
Existence
COMPULSORY
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
31
maximum length
35

shipping   = OPTIONAL

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

shipping.address   = OPTIONAL

The address to which this order will be shipped.
Fixed value

shipping.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

shipping.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

shipping.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
JSON type
String
minimum length
1
maximum length
10

shipping.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

shipping.address.street  String = OPTIONAL

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
JSON type
String
minimum length
1
maximum length
100

shipping.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

shipping.contact   = OPTIONAL

Details of the contact person at the address the goods will be shipped to.
Fixed value

shipping.contact.firstName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

shipping.contact.lastName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

shipping.origin.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
JSON type
String
minimum length
1
maximum length
10

sourceOfFunds   = COMPULSORY

Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
Fixed value

sourceOfFunds.provided   = OPTIONAL

For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.
Fixed value

sourceOfFunds.provided.ideal   = OPTIONAL

When processing an iDEAL payment you can also provide the payer's bank identification code (ideal.bic),
Fixed value

sourceOfFunds.provided.ideal.bic  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
8
maximum length
11

sourceOfFunds.provided.paypal   = OPTIONAL

It is provided to you when the payer successfully makes a payment using PayPal or when you have established a billing agreement with the payer.
Fixed value

sourceOfFunds.provided.paypal.billingAgreement   = OPTIONAL

Details about the agreement you have established with the payer that allows you to bill the payer's PayPal account for goods or services.
Fixed value

sourceOfFunds.provided.paypal.billingAgreement.cardinality  Enumeration = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
MULTIPLE
Indicates that you have multiple billing agreements with this payer. This means that a new agreement ID will be returned in response to each request.
SINGLE
Indicates that you have a single billing agreement with this payer. This means that the same agreement ID will be returned in response to each request.

sourceOfFunds.provided.paypal.billingAgreement.description  String = OPTIONAL

This description is displayed to the payer when they are asked to approve the billing agreement.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement.name  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.type  Enumeration = COMPULSORY

If you are passing card data (in any form) on the API, then you need to set this value, and also provide the card details in the sourceOfFunds.provided.card group. In the case of digital wallets or device payment methods, you must also populate the order.walletProvider field.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ALIPAY
The payer selected the payment method Alipay.
BOLETO_BANCARIO
The payer selected the payment method Boleto Bancario.
ENETS
The payer selected the payment method eNETS.
GIROPAY
The payer selected the payment method giropay.
IDEAL
The payer selected the payment method iDEAL.
KLARNA
The payer selected the payment method Klarna.
OXXO
The payer selected the payment method OXXO.
PAYPAL
The payer selected the payment method PayPal.
POLI
The payer selected the payment method POLi.
SEPA
The payer selected the payment method SEPA.
SOFORT
The payer selected the payment method Sofortbanking.
UNION_PAY
The payer selected the payment method UnionPay.
WECHAT_PAY
The payer selected the payment method WeChatPay.

token  Alphanumeric = OPTIONAL

You can only supply this value when creating a token if your token repository is configured to support merchant-supplied tokens.

On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
40

{merchantId}  Alphanumeric + additional characters COMPULSORY

Existence
COMPULSORY
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

Response Parameters

browserPayment   = Always Provided

Information required by the gateway to manage interactions with a browser payment provider's website.
Fixed value

browserPayment.redirectUrl  Url = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

merchant  Alphanumeric + additional characters = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'
JSON type
String
minimum length
1
maximum length
40

response.gatewayCode  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
BASIC_VERIFICATION_SUCCESSFUL
The card number format was successfully verified and the card exists in a known range.
EXTERNAL_VERIFICATION_BLOCKED
The external verification was blocked due to risk rules.
EXTERNAL_VERIFICATION_DECLINED
The card details were sent for verification, but were was declined.
EXTERNAL_VERIFICATION_DECLINED_AUTHENTICATION_REQUIRED
The card details were sent for verification, but were declined as authentication required.
EXTERNAL_VERIFICATION_DECLINED_EXPIRED_CARD
The card details were sent for verification, but were declined as the card has expired.
EXTERNAL_VERIFICATION_DECLINED_INVALID_CSC
The card details were sent for verification, but were declined as the Card Security Code (CSC) was invalid.
EXTERNAL_VERIFICATION_PROCESSING_ERROR
There was an error processing the verification.
EXTERNAL_VERIFICATION_SUCCESSFUL
The card details were successfully verified.
NO_VERIFICATION_PERFORMED
The card details were not verified.

result  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
FAILURE
The operation was declined or rejected by the gateway, acquirer or issuer
PENDING
The operation is currently in progress or pending processing
SUCCESS
The operation was successfully processed
UNKNOWN
The result of the operation is unknown

session.id  ASCII Text = Always Provided

Values provided in the request will override values contained in the session.
Existence
Always Provided
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
31
maximum length
35

browserPayment   = Always Provided

Information required by the gateway to manage interactions with a browser payment provider's website.
Fixed value

browserPayment.redirectUrl  Url = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

correlationId  String = CONDITIONAL

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

merchant  Alphanumeric + additional characters = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.'
JSON type
String
minimum length
1
maximum length
40

response.gatewayCode  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
BASIC_VERIFICATION_SUCCESSFUL
The card number format was successfully verified and the card exists in a known range.
EXTERNAL_VERIFICATION_BLOCKED
The external verification was blocked due to risk rules.
EXTERNAL_VERIFICATION_DECLINED
The card details were sent for verification, but were was declined.
EXTERNAL_VERIFICATION_DECLINED_AUTHENTICATION_REQUIRED
The card details were sent for verification, but were declined as authentication required.
EXTERNAL_VERIFICATION_DECLINED_EXPIRED_CARD
The card details were sent for verification, but were declined as the card has expired.
EXTERNAL_VERIFICATION_DECLINED_INVALID_CSC
The card details were sent for verification, but were declined as the Card Security Code (CSC) was invalid.
EXTERNAL_VERIFICATION_PROCESSING_ERROR
There was an error processing the verification.
EXTERNAL_VERIFICATION_SUCCESSFUL
The card details were successfully verified.
NO_VERIFICATION_PERFORMED
The card details were not verified.

result  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
FAILURE
The operation was declined or rejected by the gateway, acquirer or issuer
PENDING
The operation is currently in progress or pending processing
SUCCESS
The operation was successfully processed
UNKNOWN
The result of the operation is unknown

session.id  ASCII Text = Always Provided

Values provided in the request will override values contained in the session.
Existence
Always Provided
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
31
maximum length
35

error   = CONDITIONAL

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

error.cause  Enumeration = CONDITIONAL

For example, errors may occur due to invalid requests or internal system failures.
Fixed value
Validation Rules
JSON type
String
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 = CONDITIONAL

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1000

error.field  String = CONDITIONAL

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

error.supportCode  String = CONDITIONAL

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

error.validationType  Enumeration = CONDITIONAL

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
JSON type
String
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 = CONDITIONAL

Fixed value
Validation Rules
JSON type
String
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.

Copyright © 2023 Mastercard