Verify
Request to verify the cardholder's account before processing the financial transaction. The card is verified using the verification method supported by the acquirer and the data provided in the request.
URL | https://secure.uat.tnspayments.com/api/nvp/version/62 |
HTTP Method | POST |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =VERIFY FIXED
merchant Alphanumeric + additional characters = COMPULSORY
order = COMPULSORY
order.currency Upper case alphabetic text = COMPULSORY
order.id String = COMPULSORY
session.id ASCII Text = OPTIONAL
sourceOfFunds = COMPULSORY
sourceOfFunds.token Alphanumeric = OPTIONAL
On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.
sourceOfFunds.type Enumeration = OPTIONAL
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.
transaction.id String = COMPULSORY
- 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.
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.
agreement = OPTIONAL
You must provide this data for some types of payments (such as recurring), but you can provide it for any cases where you want to link orders together.
agreement.amountVariability Enumeration = OPTIONAL
agreement.expiryDate Date = OPTIONAL
agreement.id String = OPTIONAL
- Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
- Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
- Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
agreement.maximumAmountPerPayment Decimal = OPTIONAL
agreement.minimumDaysBetweenPayments Integer = OPTIONAL
agreement.numberOfPayments Integer = OPTIONAL
agreement.paymentFrequency Enumeration = OPTIONAL
agreement.type Enumeration = OPTIONAL
The gateway will use the value you specify for subsequent payments in the series.
apiOperation String =VERIFY FIXED
billing = OPTIONAL
billing.address = OPTIONAL
billing.address.city String = OPTIONAL
billing.address.company String = OPTIONAL
billing.address.country Upper case alphabetic text = OPTIONAL
billing.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
billing.address.stateProvince String = OPTIONAL
billing.address.stateProvinceCode String = OPTIONAL
billing.address.street String = OPTIONAL
billing.address.street2 String = OPTIONAL
correlationId String = OPTIONAL
customer = OPTIONAL
customer.email Email = OPTIONAL
customer.firstName String = OPTIONAL
customer.lastName String = OPTIONAL
customer.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.taxRegistrationId String = OPTIONAL
debtRepayment = OPTIONAL
debtRepayment.paymentRecipient = OPTIONAL
debtRepayment.paymentRecipient.accountIdentifier String = COMPULSORY
debtRepayment.paymentRecipient.dateOfBirth Date = COMPULSORY
debtRepayment.paymentRecipient.lastName String = COMPULSORY
debtRepayment.paymentRecipient.postcodeZip String = COMPULSORY
device = OPTIONAL
device.ani String = OPTIONAL
device.aniCallType String = OPTIONAL
device.browser String = OPTIONAL
device.fingerprint String = OPTIONAL
device.hostname String = OPTIONAL
device.ipAddress String = OPTIONAL
initiator.userId String = OPTIONAL
merchant Alphanumeric + additional characters = COMPULSORY
order = COMPULSORY
order.amount Decimal = OPTIONAL
The value of this field in the response is zero if payer funds are not transferred.
order.currency Upper case alphabetic text = COMPULSORY
order.custom String = OPTIONAL
order.customerNote String = OPTIONAL
order.customerOrderDate Date = OPTIONAL
order.customerReference ASCII Text = OPTIONAL
order.description String = OPTIONAL
order.discount = OPTIONAL
order.discount.amount Decimal = OPTIONAL
order.discount.code String = OPTIONAL
order.discount.description String = OPTIONAL
order.invoiceNumber String = OPTIONAL
order.localTaxRegistrationId String = OPTIONAL
order.marketplace = OPTIONAL
order.marketplace.retailerLocation Enumeration = OPTIONAL
order.merchantCategoryCode Digits = OPTIONAL
order.notificationUrl Url = OPTIONAL
order.owningEntity String = OPTIONAL
order.owningEntity String = OPTIONAL
order.purchaseType Enumeration = OPTIONAL
6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY.
6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES.
6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT.
You may set purchase type to OTHER for any other type of payment.
order.reference String = OPTIONAL
order.requestorName String = OPTIONAL
order.shippingAndHandlingAmount Decimal = OPTIONAL
order.subMerchant = OPTIONAL
order.subMerchant.address = OPTIONAL
order.subMerchant.address.city String = OPTIONAL
order.subMerchant.address.company String = OPTIONAL
order.subMerchant.address.country Upper case alphabetic text = OPTIONAL
order.subMerchant.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.subMerchant.address.stateProvince String = OPTIONAL
For an address in Canada provide the 2-letter ISO 3166-2 province code.
order.subMerchant.address.stateProvinceCode String = OPTIONAL
order.subMerchant.address.street String = OPTIONAL
order.subMerchant.address.street2 String = OPTIONAL
order.subMerchant.bankIndustryCode Digits = OPTIONAL
order.subMerchant.email Email = OPTIONAL
order.subMerchant.identifier String = COMPULSORY
order.subMerchant.phone String = OPTIONAL
order.subMerchant.registeredName String = OPTIONAL
order.subMerchant.tradingName String = COMPULSORY
order.tax[n] = OPTIONAL
order.tax[n].amount Decimal = OPTIONAL
order.tax[n].rate Decimal = OPTIONAL
order.tax[n].type String = OPTIONAL
order.taxAmount Decimal = OPTIONAL
This amount is the sum of the tax amount for all the items contained in the order. If you supply both this value and any line item details, then this amount MUST equal the sum of the item.quantity times the item.unitTaxAmount for all the line items.
order.taxRegistrationId String = OPTIONAL
order.taxStatus Enumeration = OPTIONAL
order.transactionFiltering = OPTIONAL
order.transactionFiltering.avsResponseCodeRules[n] = OPTIONAL
order.transactionFiltering.avsResponseCodeRules[n].action Enumeration = COMPULSORY
order.transactionFiltering.avsResponseCodeRules[n].avsResponseCode Enumeration = COMPULSORY
order.walletIndicator String = OPTIONAL
order.walletProvider Enumeration = OPTIONAL
order.id String = COMPULSORY
partnerSolutionId String = OPTIONAL
posTerminal = OPTIONAL
posTerminal.address = OPTIONAL
posTerminal.address.city String = OPTIONAL
posTerminal.address.company String = OPTIONAL
posTerminal.address.country Upper case alphabetic text = OPTIONAL
posTerminal.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
posTerminal.address.stateProvince String = OPTIONAL
posTerminal.address.street String = OPTIONAL
posTerminal.address.street2 String = OPTIONAL
posTerminal.attended Enumeration = OPTIONAL
You must provide a value for this field for chip transactions with UK acquirers.
This field corresponds to EMV tag 9F35
posTerminal.cardPresenceCapability Enumeration = OPTIONAL
posTerminal.cardholderActivated Enumeration = OPTIONAL
There are seven types (levels) of CAT devices. Each level has specific card scheme requirements.
If you do not provide a value for this field for a Card Present payment the gateway defaults the value to NOT_CARDHOLDER_ACTIVATED.
This field corresponds to EMV tag 9F35
posTerminal.inputCapability Enumeration = OPTIONAL
This field corresponds to EMV tag 9F33
posTerminal.lane String = OPTIONAL
This field corresponds to EMV tag 9F1C
posTerminal.location Enumeration = OPTIONAL
posTerminal.mobile = OPTIONAL
posTerminal.mobile.cardInputDevice Enumeration = OPTIONAL
posTerminal.onlineReasonCode Enumeration = OPTIONAL
Where more than one reason applies, then the order of priority used for the enumeration list applies.
posTerminal.panEntryMode Enumeration = OPTIONAL
posTerminal.pinEntryCapability Enumeration = OPTIONAL
posTerminal.pinLengthCapability Integer = OPTIONAL
posTerminal.serialNumber ASCII Text = OPTIONAL
posTerminal.store = OPTIONAL
posTerminal.store.id String = OPTIONAL
posTerminal.store.name String = OPTIONAL
posTerminal.terminalId Alphanumeric = OPTIONAL
responseControls = OPTIONAL
responseControls.sensitiveData String = OPTIONAL
risk = OPTIONAL
risk.bypassMerchantRiskRules Enumeration = OPTIONAL
risk.custom String = OPTIONAL
Field: risk.custom.headOfficeLocation
Value: London UK
session.id ASCII Text = OPTIONAL
session.version ASCII Text = OPTIONAL
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.
shipping = OPTIONAL
shipping.address = OPTIONAL
shipping.address.city String = OPTIONAL
shipping.address.company String = OPTIONAL
shipping.address.country Upper case alphabetic text = OPTIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
shipping.address.source Enumeration = OPTIONAL
shipping.address.stateProvince String = OPTIONAL
shipping.address.stateProvinceCode String = OPTIONAL
shipping.address.street String = OPTIONAL
shipping.address.street2 String = OPTIONAL
shipping.address.sameAsBilling Enumeration = OPTIONAL
The default value for this field is:
SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
shipping.contact = OPTIONAL
shipping.contact.email Email = OPTIONAL
shipping.contact.firstName String = OPTIONAL
shipping.contact.lastName String = OPTIONAL
shipping.contact.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.method Enumeration = OPTIONAL
shipping.origin.postcodeZip Alphanumeric + additional characters = OPTIONAL
sourceOfFunds = COMPULSORY
sourceOfFunds.provided = OPTIONAL
sourceOfFunds.provided.ach = OPTIONAL
sourceOfFunds.provided.ach.accountType Enumeration = OPTIONAL
- Consumer (checking or savings), or
- Business
For pre-arranged payments (sourceOfFunds.provided.ach.secCode=PPD) retrieve this information from the payer.
If payments were telephone-initiated (sourceOfFunds.provided.ach.secCode=TEL) or internet-initiated (sourceOfFunds.provided.ach.secCode=WEB) you may choose to limit the payer's options (e.g. only support consumer checking accounts), depending on your type of business (e.g. B2C online webshop).
sourceOfFunds.provided.ach.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters = OPTIONAL
sourceOfFunds.provided.ach.routingNumber Digits = OPTIONAL
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
sourceOfFunds.provided.ach.secCode Enumeration = OPTIONAL
sourceOfFunds.provided.card = OPTIONAL
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).
sourceOfFunds.provided.card.devicePayment = OPTIONAL
- • 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).
sourceOfFunds.provided.card.devicePayment.3DSecure = OPTIONAL
- • 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.
sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator Digits = OPTIONAL
This field is not applicable for payments using digital wallets or card scheme tokens.
sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram Base64 = COMPULSORY
- • Device payments: source this field directly from the decrypted payment token.
- • Card scheme tokens: source this field directly from the decrypted transaction credentials.
sourceOfFunds.provided.card.emvRequest String = OPTIONAL
For the list of field tags to include (if provided by the terminal), see Card Present Payments. Requests with any other tags are rejected by the gateway.
Some of the tags represent data that can occur on explicit fields in this API. You can submit the value either in this field, or in both places. For example, the PAN can be presented as EMV tag 5A in this field, or included both the sourceOfFunds.provided.card.number API field and in EMV tag 5A in this field.
If you specify the EMV tag only, we can populate the explicit field in the API. Fields where this is supported have the text "This field corresponds to EMV tag <tag name>" in their field descriptions.
If you specify both places, there will be no population of the explicit field or validation that the data matches.
The API response will not contain PCI sensitive fields.
sourceOfFunds.provided.card.expiry = OPTIONAL
sourceOfFunds.provided.card.expiry.month Digits = COMPULSORY
sourceOfFunds.provided.card.expiry.year Digits = COMPULSORY
sourceOfFunds.provided.card.nameOnCard String = OPTIONAL
sourceOfFunds.provided.card.number Digits = OPTIONAL
- Request
On request, populate this field based on the payment method you are using for the payment:- • Card: the account number embossed onto the card. This field corresponds to EMV tag 5A.
- • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay. Normally for device payments, you would populate sourceOfFunds.provided.card.devicePayment.paymentToken and the gateway will decrypt and extract this field. However, you can populate this field if you decrypt the payment token yourself. In this case use the Device PAN (DPAN) provided in the payment token.
- • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout. In this case, provide the PAN retrieved from the wallet.
- • Scheme tokens such as MDES (Mastercard Digital Enablement Service). Supply the value called the "Token PAN".
- Response
On return, the card number will be populated in 6.4 masking format, for example, 000000xxxxxx0000. If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.
When a DPAN or scheme token was provided in the transaction request, then this field will represent the PAN of the associated payer's account (when supported by the acquirer). This is also referred to as the Funding PAN (FPAN).
sourceOfFunds.provided.card.p2pe = OPTIONAL
sourceOfFunds.provided.card.p2pe.cardBin Digits = OPTIONAL
If you do not provided this, the gateway will not perform this check.
sourceOfFunds.provided.card.p2pe.encryptionState String = OPTIONAL
sourceOfFunds.provided.card.p2pe.initializationVector Hex = OPTIONAL
sourceOfFunds.provided.card.p2pe.keySerialNumber Hex = COMPULSORY
sourceOfFunds.provided.card.p2pe.payload Hex = COMPULSORY
sourceOfFunds.provided.card.pin = OPTIONAL
sourceOfFunds.provided.card.pin.encryptionState Enumeration = OPTIONAL
sourceOfFunds.provided.card.pin.keySerialNumber Hex = COMPULSORY
sourceOfFunds.provided.card.pin.payload Hex = COMPULSORY
sourceOfFunds.provided.card.securityCode Digits = OPTIONAL
sourceOfFunds.provided.card.storedOnFile Enumeration = OPTIONAL
If you use Scheme Tokenization services like MDES and store the tokens provided, you have to provide the value STORED and if you pass the token value with out storing them, provide the value NOT_STORED.
If you store yourself, you have to provide the TO_BE_STORED or STORED values for all payments.
sourceOfFunds.provided.card.track1 Track 1 Data = OPTIONAL
Provide this for stripe and EMV fallback to stripe cases.
This field corresponds to EMV tag 56
Data may consist of the characters: ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ]]>
sourceOfFunds.provided.card.track2 Track 2 Data = OPTIONAL
Provide this for stripe and EMV fallback to stripe cases.
The contents of this field must match the PAN and expiry fields included in the Transaction Request.
This field corresponds to EMV tag 57
Data may consist of the characters: ? ]]>
sourceOfFunds.provided.giftCard = OPTIONAL
sourceOfFunds.provided.giftCard.expectedLocalBrand String = OPTIONAL
sourceOfFunds.provided.giftCard.number Digits = OPTIONAL
sourceOfFunds.provided.giftCard.pin Digits = OPTIONAL
sourceOfFunds.token Alphanumeric = OPTIONAL
On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.
sourceOfFunds.tokenRequestorID Alphanumeric = OPTIONAL
sourceOfFunds.type Enumeration = OPTIONAL
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.
transaction = OPTIONAL
transaction.acquirer = OPTIONAL
transaction.acquirer.customData String = OPTIONAL
transaction.acquirer.traceId String = OPTIONAL
For a Mastercard transaction this identifier must contain the scheme issued transaction identifier, network code and network date, and is also known as the Trace ID. For a Visa or American Express transaction this identifier matches the scheme issued transaction identifier, also known as Transaction Identifier or TID. Refer to the scheme's documentation for more details.
Payment in a Series
You must provide the information returned in the Authorization/Payment/Verification response for the last payer-initiated transaction in the series (CIT).
Refund
You must provide the information returned in the Authorization/Payment response for the payment for which you are issuing a refund.
transaction.merchantNote String = OPTIONAL
transaction.reference String = OPTIONAL
transaction.source Enumeration = OPTIONAL
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.
transaction.id String = COMPULSORY
- 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.
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.
Response Parameters
browserPayment = CONDITIONAL
browserPayment.redirectUrl Url = CONDITIONAL
merchant Alphanumeric + additional characters = Always Provided
order = Always Provided
order.amount Decimal = Always Provided
The value of this field in the response is zero if payer funds are not transferred.
order.creationTime DateTime = Always Provided
order.currency Upper case alphabetic text = Always Provided
order.id String = Always Provided
order.lastUpdatedTime DateTime = Always Provided
order.merchantAmount Decimal = Always Provided
order.merchantCurrency Upper case alphabetic text = Always Provided
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.
order.totalAuthorizedAmount Decimal = Always Provided
order.totalCapturedAmount Decimal = Always Provided
order.totalDisbursedAmount Decimal = Always Provided
order.totalRefundedAmount Decimal = Always Provided
response = Always Provided
response.gatewayCode Enumeration = Always Provided
result Enumeration = Always Provided
transaction = Always Provided
transaction.amount Decimal = Always Provided
transaction.currency Upper case alphabetic text = Always Provided
transaction.id String = Always Provided
- 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.
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.
transaction.type Enumeration = Always Provided
Response parameters are the same as Transaction: Retrieve Transaction