v1

latestOpenAPI 3.0.12026-07-2353480642.4 KB

Ecom Payments

Initiate a payment

Initiate a card payment or card verification request when amount is set to 0 (zero).

Transactions business models

Business model	Transaction type	Shopper Interaction	Stored Credential Contract	Stored Credential Processing Model
Online purchase with shopper present	One-off online purchase without storing card payment details for future use.	ECOMMERCE
Online purchase with shopper present	Online purchase where shopper agrees to store card details for future use. This can be a zero-value transaction account verification.	ECOMMERCE		CREDENTIAL_ON_FILE
Online purchase with shopper present	Online purchase where shopper uses previously stored card payment details.	ECOMMERCE	ONE_CLICK	CREDENTIAL_ON_FILE
Subscriptions	Initial transaction to sign up for a subscription.	ECOMMERCE		RECURRING
Subscriptions	Subsequent subscription charge.	ECOMMERCE	MERCHANT_INITIATED	RECURRING
Non-fixed in time contracts (such as auto account top-ups)	Initial transaction to sign up for the terms and conditions of later subsequent charges.	ECOMMERCE		UNSCHEDULED_CREDENTIAL_ON_FILE
Non-fixed in time contracts (such as auto account top-ups)	Subsequent charges as described in the initial terms and conditions during the sign-up transaction.	ECOMMERCE	MERCHANT_INITIATED	UNSCHEDULED_CREDENTIAL_ON_FILE

post/api/v2/transactions/card

Headers

x-vfi-api-idempotencykeystring uuid

A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.

Request body

Response

Ecommerce Payment Result

idstring uuid-flexible

The ID of the transaction.

payment_provider_contractstring uuid-flexible

The identifier of payment provider contract you want to process the transaction request with.

amountinteger

Amount is charged without a decimal place e.g. $1.5 = 150. Currencies can have different decimals/exponentials, see Currencies Section for more details. For Account Verification transactions, provide 0 as value for this field.

blockedboolean

True if the transaction has been blocked by a ruleset, false otherwise

created_atstring date-time

The time at which the transaction was created.

customerstring

The ID of a customer

merchant_referencestring

A reference specified by the merchant to identify the transaction

payment_productstring

The payment product corresponding to this transaction

payment_product_typestring

The name of the processor used for this transaction

processor_referencestring

Reference identifying the transaction, as provided by the processor.

processor_detailsobject

Stores all details specific for the processor of the transaction.

The outcome of the payment request.

status_reasonstring

Message provided by the 3rd party service as additional information, when the transaction does not succeed.

arnstring

Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions.

authorization_codestring

When the payment is authorized successfully, this field holds the authorization code for the payment.
When the payment is not authorized, this field is not returned.

avs_result'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'I' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'R' | 'S' | 'T' | 'U' | 'W' | 'X' | 'Y' | 'Z'

Address verification services result, which provides information about the outcome of the AVS check. The full list of codes and descriptions can be found <a href="https://docs.verifone.com/online-payments/fraud-management/address-verification-service-avs">here</a>

cardstring

The token representing the payment card

created_bystring

The ID of the user who initiated the transaction. Only set when shopper_interaction = moto, mail_order or telephone_order

cvv_presentboolean

True if the card was used with a cvv

cvv_result'0' | '1' | '2' | '3' | '4' | '5' | '6' | '9' | 'M' | 'Y' | 'N' | 'P' | 'S' | 'U'

The CVC verification result, which provides information about the outcome of the CVC check.

CVC-CVV result codes:

0 Unknown
1 Matches.
2 Doesn't match.
3 Not checked.
4 No CVC/CVV provided, but was required.
5 Issuer not certified for CVC/CVV.
6 No CVC/CVV provided.

The following are included only for backwards compatibility. They are deprecated and will be removed in the next major release. The client must take action now to ensure ongoing support.

M Match
Y Match
N No Match
P Not Processed
S CVV Should be present, but Merchant indicates not present.
U Issuer not certified or registered to process card verification.

cavv_result'0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '99' | 'A' | 'B' | 'C' | 'D' | 'I' | 'U' | 'NA'

This field will be populated for any Verified by Visa transaction and AVV Authorisation message sent by MasterCard SecureCode: This includes CAVV and AEVV from American Express SafeKey.

CAVV Transaction Response Code Values:

0 CAVV or AEVV Not Validated due to erroneous data submitted.
1 CAVV or AEVV Failed Validation - Authentication Transaction. This is an indication of potential bad or fraudulent data submitted.
2 CAVV or AEVV Passed Validation – Authentication Transaction.
3 CAVV or AEVV Passed Validation – Attempted Authentication Transaction. (Determined that the Issuer ACS generated this value from the use of the Issuer’s CAVV/AEVV key[s]).
4 CAVV or AEVV Failed Validation – Attempted Authentication Transaction. Attempted Authentication Transaction. This is an indication of potential bad or fraudulent data submitted as the CAVV/AEVV. (Determined that Visa generated this value from the use of CAVV/AEVV key[s]).
5 Reserved.
6 CAVV or AEVV Not Validated – Issuer not participated. This value is generated when an Issuer requests the do not verify flag to be established for its BINs. This parameter enables an Issuer to temporarily stop CAVV/AEVV verification while resolving CAVV/AEVV key issues. VisaNet processes this value as a valid CAVV/AEVV.
7 CAVV or AEVV Failed Validation – Attempted Authentication Transaction. This is an indication of potential bad or fraudulent data submitted as the CAVV/AEVV. (CAVV/AEVV generated with Visa Key).
8 CAVV or AEVV Passed Validation – Attempted Authentication Transaction. (CAVV/AEVV generated with Visa Key).
9 CAVV or AEVV Failed Validation – Attempted Authentication Transaction. This is an indication of potential bad or fraudulent data submitted as the CAVV/AEVV (CAVV/AEVV generated with Visa Key – Issuer ACS unavailable).
99 An unknown value was returned from the processor.
A CAVV or AEVV Passed Validation – Attempted Authentication Transaction. (CAVV/AEVV generated with Visa Key – Issuer ACS unavailable).
B CAVV or AEVV Failed Validation – Attempted Authentication Transaction. This is an indication of potential bad or fraudulent data submitted as the CAVV/AEVV. (CAVV/AEVV generated with Visa Key).
C CAVV or AEVV Not Validated – Attempted Authentication Transaction. Issuer did not return a CAVV/AEVV results code in the authorisation response. VisaNet will treat this as valid CAVV/AEVV if the Issuer approves the authorisation.
D CAVV or AEVV Not Validated – Authentication. Issuer did not return a CAVV/AEVV results code in the authorisation response. VisaNet will treat this as valid CAVV/AEVV if the Issuer approves the authorisation.
I Invalid Security Data.
U Issuer does not participate or 3-D Secure data not utilised.
NA Blank CAVV or AEVV Not Present.

invoice_numberstring

Optional. The invoice number to track this payment.

reason_codestring

A reason code assigned by the acquiring platform; '0000' in case of success

rrnstring

A client (user friendly) identifier for the transaction generated at the outset of a business event. The format will be dependent on the calling system.

A reference supplied by the system retaining the original source information and used to assist in locating that transaction or a copy of the transaction. This value is critical in matching values that are sent to other Payment processors or Acquirers. This value would correspond to the ISO8583 specification as RRN in attribute DE 37, which limits the value to being an alphanumeric value 12 characters.

For the GSC client android application the format will correspond to YYMMdd<stan 6 digits>.

shopper_interaction'ECOMMERCE' | 'MAIL' | 'TELEPHONE'

Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth

stanstring

System Trace Audit Number.

reversal_status'NONE' | 'REQUIRED' | 'COMPLETED'

Indicates to the API client if a technical reversal has been completed by Verifone.

geo_locationnumber[]

The latitude / longitude resolved from the customer's ip address.

citystring

The city resolved from the customer's ip address.

country_codestring

The country code resolved from the customer's ip address.

promo_codestring

A code defined by the merchant that affects the calculation of the total amount.

purchase_order_numberstring

The purchase order number. It can be provided in transactions with purchase or procurement cards for the cardholder to get better interchange rates (note that this functionality needs alignment with the acquirer and the scheme). This field is part of so-called Level 2 data.

balance_amountinteger

Balance amount is the amount remaining on a card or account of cardholder without a decimal place e.g. $1.5 = 150.

The required number of decimal places for a currency code is according to ISO 4217. However the following table takes precedence over ISO 4217: