Disbursement

Use this operation to pay out funds to a payer, for example when you want to disburse gaming winnings or pay a payer's credit card bill.

Note that this differs from a refund, where you are returning funds to the payer for parts or all of a purchase that they did not receive or where they returned the goods.

URL https://evopaymentsmexico.gateway.mastercard.com/api/nvp/version/67
HTTP Method POST
Authentication This operation requires authentication via one of the following methods:
  • Certificate authentication.
  • To authenticate to the API two additional NVP parameters must be supplied in the request. Provide 'merchant.<your gateway merchant ID>' in the apiUsername field and your API password in the apiPassword field.

Request Parameters

apiOperation  String =DISBURSEMENT FIXED

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

disbursementType  Enumeration = COMPULSORY

If your Merchant Category Code is 7995 (Gambling Transactions) and you are paying out gaming winnings, set the value to GAMING_WINNINGS. If your Merchant Category Code is 6536 (MoneySend Intracountry) and you are paying a credit card bill, set the value to CREDIT_CARD_BILL_PAYMENT and provide the payment sender details.
Existence
COMPULSORY
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CREDIT_CARD_BILL_PAYMENT
Indicates that you are paying a credit card bill.
GAMING_WINNINGS
Indicates that you are paying out gaming winnings to a payer.

merchant  Alphanumeric + additional characters = COMPULSORY

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 value of this field in the response is zero if payer funds are not transferred.
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

Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.id  String = COMPULSORY

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
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

transaction.id  String = COMPULSORY

An order can have transactions representing:
  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

apiOperation  String =DISBURSEMENT FIXED

Existence
FIXED
Fixed value
DISBURSEMENT
Validation Rules
Any sequence of zero or more unicode characters.
XSD 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

creditCardBillPayment   = OPTIONAL

Details about credit card bill payments.
Fixed value

creditCardBillPayment.paymentSender   = OPTIONAL

The details about the person who is requesting that you pay the credit card bill.
Fixed value

creditCardBillPayment.paymentSender.address   = COMPULSORY

The payment sender's address.
Fixed value

creditCardBillPayment.paymentSender.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
25

creditCardBillPayment.paymentSender.address.country  Upper case alphabetic text = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

creditCardBillPayment.paymentSender.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

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

creditCardBillPayment.paymentSender.address.stateProvinceCode  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
2
maximum length
3

creditCardBillPayment.paymentSender.address.street  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

creditCardBillPayment.paymentSender.bankAccountNumber  Digits = OPTIONAL

For a split payment where both a debit card and bank account were used, you must provide both the creditCardBillPayment.paymentSender.cardNumber and the creditCardBillPayment.paymentSender.bankAccountNumber field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
20

creditCardBillPayment.paymentSender.cardNumber  Digits = OPTIONAL

For a split payment where both a debit card and bank account were used, you must provide both the creditCardBillPayment.paymentSender.cardNumber and the creditCardBillPayment.paymentSender.bankAccountNumber field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
9
maximum length
19

creditCardBillPayment.paymentSender.firstName  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

creditCardBillPayment.paymentSender.lastName  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

customer   = OPTIONAL

Information about the customer, including their contact details.
Fixed value

customer.email  Email = OPTIONAL

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

customer.firstName  String = OPTIONAL

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

customer.lastName  String = OPTIONAL

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

customer.mobilePhone  Telephone Number = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
XSD type
string
mandatory country code
true
maximum total digits
15

customer.phone  Telephone Number = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
XSD type
string
mandatory country code
true
maximum total digits
15

customer.taxRegistrationId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

device   = OPTIONAL

Information about the device used by the payer for this transaction.
Fixed value

device.ani  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
10

device.aniCallType  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
2

device.browser  String = OPTIONAL

For example, MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

device.fingerprint  String = OPTIONAL

For example, session ID, blackbox ID.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
4000

device.hostname  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
60

device.ipAddress  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
7
maximum length
15

disbursementType  Enumeration = COMPULSORY

If your Merchant Category Code is 7995 (Gambling Transactions) and you are paying out gaming winnings, set the value to GAMING_WINNINGS. If your Merchant Category Code is 6536 (MoneySend Intracountry) and you are paying a credit card bill, set the value to CREDIT_CARD_BILL_PAYMENT and provide the payment sender details.
Existence
COMPULSORY
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CREDIT_CARD_BILL_PAYMENT
Indicates that you are paying a credit card bill.
GAMING_WINNINGS
Indicates that you are paying out gaming winnings to a payer.

initiator.userId  String = OPTIONAL

This field is automatically populated by the gateway if the transaction was created via Merchant Administration (gatewayEntryPoint=MERCHANT_ADMINISTRATION) or Merchant Manager (MERCHANT_MANAGER). In this case this is the name that the person used to log in to Merchant Administration or Merchant Manager respectively.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
256

merchant  Alphanumeric + additional characters = COMPULSORY

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 value of this field in the response is zero if payer funds are not transferred.
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

Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.custom  String = OPTIONAL

For example order.custom.X, where 'X' is defined by you and must be less than 100 characters from the set A-Z, a-z, 0-9. For example, order.custom.salesRegion. You can specify up to 50 such fields. They are not sent to acquirers.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
250

order.customerNote  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
250

order.description  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
127

order.merchantCategoryCode  Digits = OPTIONAL

You only need to provide the MCC if you want to override the default value configured for your acquirer link.The value you provide must match one of those configured by your payment service provider.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
4

order.notificationUrl  Url = OPTIONAL

To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS
Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
XSD type
string

order.reference  String = OPTIONAL

For example, a shopping cart number, an order number, or an invoice number.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.id  String = COMPULSORY

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
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

partnerSolutionId  String = OPTIONAL

If your payment service provider has not provided you with a solution ID, you should ignore this field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

responseControls   = OPTIONAL

Container for fields that control the response returned for the request.
Fixed value

responseControls.sensitiveData  String = OPTIONAL

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

session.id  ASCII Text = OPTIONAL

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

session.version  ASCII Text = OPTIONAL

Do this if you make business decisions based on data from the session and wish to ensure that the same data is being used for the request operation.

To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.

If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.

See Making Business Decisions Based on Session Content.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
XSD type
string
minimum length
10
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.card   = OPTIONAL

Use this parameter group when you have sourced payment details using:
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
Fixed value

sourceOfFunds.provided.card.devicePayment   = OPTIONAL

Use this parameter group when you have sourced payment details using:
  • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
  • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
  • • Card scheme tokens. This applies when you have tokenized the payer's card number using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
Fixed value

sourceOfFunds.provided.card.devicePayment.3DSecure   = OPTIONAL

Use this parameter group for:
  • • Device payments: if you decrypt the payment token yourself. In this case, you source these fields directly from the decrypted payment token.
    You do not need to use this parameter group if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken.
  • • Card scheme tokens: if you decrypt the transaction credentials yourself.
Fixed value

sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator  Digits = OPTIONAL

You source this field directly from the decrypted payment token.

This field is not applicable for payments using digital wallets or card scheme tokens.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
2

sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram  Base64 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is Base64 encoded
XSD type
string
minimum length
1
maximum length
128

sourceOfFunds.provided.card.expiry   = OPTIONAL

Expiry date, as shown on the card.
Fixed value

sourceOfFunds.provided.card.expiry.month  Digits = COMPULSORY

Months are numbered January=1, through to December=12.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
XSD type
string

sourceOfFunds.provided.card.expiry.year  Digits = COMPULSORY

The Common Era year is 2000 plus this value.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
2
maximum length
2

sourceOfFunds.provided.card.nameOnCard  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
256

sourceOfFunds.provided.card.number  Digits = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
9
maximum length
19

sourceOfFunds.provided.card.securityCode  Digits = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
3
maximum length
4

sourceOfFunds.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
XSD type
string
minimum length
1
maximum length
40

sourceOfFunds.type  Enumeration = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CARD
Use this value for payments that obtained the card details either directly from the card, or from a POS terminal, or from a wallet, or through a device payment method.
SCHEME_TOKEN
Use this value for payments using scheme tokens provided by Mastercard Digital Enablement Service (MDES), or Visa Token Service (VTS), or American Express Token Service (AETS).

transaction   = OPTIONAL

Information about this transaction.
Fixed value

transaction.acquirer   = OPTIONAL

Additional information to be passed to acquirer.
Fixed value

transaction.acquirer.transactionId  String = OPTIONAL

Ideally this will be the order.id, however if that value cannot be used directly, it will be transformed by the gateway to a unique value that the acquirer will accept. If that behavior is not suitable, you can directly provide the value in this field and it will be passed to the acquirer. You then take responsibility for its correctness. (Note: contact your payment provider to see if this is supported for your acquirer).
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters, but sensitive data will be rejected
XSD type
string
minimum length
1
maximum length
100

transaction.reference  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

transaction.source  Enumeration = OPTIONAL

For example, set this value to INTERNET if the payer initiated the payment online.

If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.You only need to provide transaction.source if you want to override the default value configured for your acquirer link.

Note:

  • You can only override the default value if you have the requisite permission.
  • The value you provide must match one of those configured by your payment service provider.
  • You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
INTERNET
Transaction conducted over the Internet.

transaction.id  String = COMPULSORY

An order can have transactions representing:
  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

Response Parameters

browserPayment   = CONDITIONAL

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

browserPayment.redirectUrl  Url = CONDITIONAL

The redirect URL is not applicable for PayPal. For PayPal payments implement the createOrder callback in the JavaScript SDK instead.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
XSD 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, '-', '_'
XSD type
string
minimum length
1
maximum length
40

order   = Always Provided

Information about the order associated with this transaction.
Fixed value

order.amount  Decimal = Always Provided

The value of this field in the response is zero if payer funds are not transferred.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.creationTime  DateTime = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

order.currency  Upper case alphabetic text = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.id  String = Always Provided

Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order created by your merchant profile.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.lastUpdatedTime  DateTime = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

order.merchantAmount  Decimal = Always Provided

This is derived from the rate quote and order.amount for this order when Multi-Currency Pricing was used.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.merchantCurrency  Upper case alphabetic text = Always Provided

This value (along with merchantAmount) is applicable if you are doing Multi-Currency Pricing, as it gives you a consistent currency across all your orders that involve foreign exchange (FX).

If there is FX on this order, this is based on the rate quote you provided on the payment transactions, if not then this is the order.currency.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.totalAuthorizedAmount  Decimal = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalCapturedAmount  Decimal = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalDisbursedAmount  Decimal = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalRefundedAmount  Decimal = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

response   = Always Provided

Fixed value

response.gatewayCode  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
ABORTED
Transaction aborted by payer
ACQUIRER_SYSTEM_ERROR
Acquirer system error occurred processing the transaction
APPROVED
Transaction Approved
APPROVED_AUTO
The transaction was automatically approved by the gateway. it was not submitted to the acquirer.
APPROVED_PENDING_SETTLEMENT
Transaction Approved - pending batch settlement
AUTHENTICATION_FAILED
Payer authentication failed
AUTHENTICATION_IN_PROGRESS
The operation determined that payer authentication is possible for the given card, but this has not been completed, and requires further action by the merchant to proceed.
BALANCE_AVAILABLE
A balance amount is available for the card, and the payer can redeem points.
BALANCE_UNKNOWN
A balance amount might be available for the card. Points redemption should be offered to the payer.
BLOCKED
Transaction blocked due to Risk or 3D Secure blocking rules
CANCELLED
Transaction cancelled by payer
DECLINED
The requested operation was not successful. For example, a payment was declined by issuer or payer authentication was not able to be successfully completed.
DECLINED_AVS
Transaction declined due to address verification
DECLINED_AVS_CSC
Transaction declined due to address verification and card security code
DECLINED_CSC
Transaction declined due to card security code
DECLINED_DO_NOT_CONTACT
Transaction declined - do not contact issuer
DECLINED_INVALID_PIN
Transaction declined due to invalid PIN
DECLINED_PAYMENT_PLAN
Transaction declined due to payment plan
DECLINED_PIN_REQUIRED
Transaction declined due to PIN required
DEFERRED_TRANSACTION_RECEIVED
Deferred transaction received and awaiting processing
DUPLICATE_BATCH
Transaction declined due to duplicate batch
EXCEEDED_RETRY_LIMIT
Transaction retry limit exceeded
EXPIRED_CARD
Transaction declined due to expired card
INSUFFICIENT_FUNDS
Transaction declined due to insufficient funds
INVALID_CSC
Invalid card security code
LOCK_FAILURE
Order locked - another transaction is in progress for this order
NOT_ENROLLED_3D_SECURE
Card holder is not enrolled in 3D Secure
NOT_SUPPORTED
Transaction type not supported
NO_BALANCE
A balance amount is not available for the card. The payer cannot redeem points.
PARTIALLY_APPROVED
The transaction was approved for a lesser amount than requested. The approved amount is returned in order.totalAuthorizedAmount.
PENDING
Transaction is pending
REFERRED
Transaction declined - refer to issuer
SYSTEM_ERROR
Internal system error occurred processing the transaction
TIMED_OUT
The gateway has timed out the request to the acquirer because it did not receive a response. Points redemption should not be offered to the payer.
UNKNOWN
The transaction has been submitted to the acquirer but the gateway was not able to find out about the success or otherwise of the payment. If the gateway subsequently finds out about the success of the payment it will update the response code.
UNSPECIFIED_FAILURE
Transaction could not be processed

result  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
XSD 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

transaction   = Always Provided

Information about this transaction.
Fixed value

transaction.amount  Decimal = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

transaction.currency  Upper case alphabetic text = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

transaction.id  String = Always Provided

An order can have transactions representing:
  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

transaction.type  Enumeration = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AUTHENTICATION
Authentication
AUTHORIZATION
Authorization
AUTHORIZATION_UPDATE
Authorization Update
CAPTURE
Capture
CHARGEBACK
Chargeback
DISBURSEMENT
Disbursement
FUNDING
The transaction transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
PAYMENT
Payment (Purchase)
REFUND
Refund
REFUND_REQUEST
Refund Request
VERIFICATION
Verification
VOID_AUTHORIZATION
Void Authorization
VOID_CAPTURE
Void Capture
VOID_PAYMENT
Void Payment
VOID_REFUND
Void Refund

Response parameters are the same as Transaction: Retrieve Transaction

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
XSD 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
XSD 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
XSD 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
XSD 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
XSD 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
XSD 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 © 2022 Mastercard