Acquiring · Paynetics Docs

AVS

POST /v1/avs/{init}

Address Verification Service check

Operation avs

Verifies the cardholder's billing address and ZIP / postal code with the issuer without charging the card. Used for risk checks prior to a payment. AVS performs an authorization which is not connected with any other transaction — it corresponds to an ISO8583 0100 message with amount 0, so no funds are blocked and no transaction is created. The amount and currency are still required (they resolve the merchant configuration and routing), but the amount forwarded to the processor is always 0. The card can be supplied as a raw PAN (card_number), as a saved card token (card), or via an init session token (from POST/v1/init, passed as the {init} path parameter); with an init token the card, amount and currency are taken from the session. address and zip are always required — they are the values being verified. In response you will receive the raw AVS status returned by the issuer and the parsed meaning of that raw status. Authentication: HMAC (avs).

Path parameters

Name	Example	Description
`init` string required	`—`	Session token from POST /v1/init. Not required. When supplied, the card, amount and currency are taken from the session; address and zip must still be sent in the body.

Request body

Field Type Description

zip string (0,any) required Cardholder ZIP / postal code to be verified with the issuer.

address string (0,any) required Cardholder billing address to be verified with the issuer.

mpg_id string (0,any) Merchant Payment Gateway ID at processor level. When a merchant has more than one MID configured, partners can route the transaction through the corresponding MID by submitting the specific value. Maximum 11 numeric characters.

card_expiration_month string (0,any) Card expiry month in MM format (01 = January, 12 = December). Required for new card (PAN) payments. Must not be sent when using saved card token.

card_expiration_year string (0,any) Card expiry year in YY format. Must be the current or a future year. Must not be expired in combination with card_expiration_month. Required for new card (PAN) payments. Must not be sent when using saved card token.

merchant string (0,any) Merchant identifier. Required unless a configuration object is provided.

terminal string (0,any) Terminal identifier. When not provided, resolved from the merchant default terminal.

user string (0,any) User token in Paynetics.

amount number (0,any) required Transaction amount in major currency units (e.g. 50.00 = fifty euros). Must be a positive number with up to 2 decimal places.

currency string (0,any) required Transaction currency in ISO 4217 format (exactly 3 characters). Must be a supported currency.

card string (0,any) Saved card token for returning customers. Returned from a previous /v1/init, purchase, or POST /v1/cards call. Required for saved card (token) payments. Must not be sent when using new card PAN.

card_number string (0,any) Full Primary Account Number (PAN) as printed on the card (12–19 digits, Luhn-validated). Required for new card (PAN) payments. Must not be sent when using saved card token.

cardholder_name string (0,any) Name as printed on the card (2–45 characters). Required for new card (PAN) payments. Must not be sent when using saved card token.

cvv2 string (0,any) Card security code (CVV2/CVC2/CID). Must be 3–4 digits. Pattern: [0-9]{3,4}.

mid string (0,any) Merchant ID at processor level. When a merchant has more than one MID configured, partners can route the transaction through the corresponding MID by submitting the specific value.

card_acceptor object Card acceptor (merchant) details.

Field	Type	Description
`name`	string (0,any)	Merchant name on the cardholder's card statement. Maximum 25 characters. Allowed characters: a-z, A-Z, 0-9, space and the symbols . , ! ? ( ) _ : ; / @ # % & * + = < > { } ~ \| ^ $ [ ] " ' - with no leading or trailing space. Pattern: ^(?! )[0-9a-zA-Z .,!?()_:;/@#%&*+=<>{}~\|^\$\[\]"'\-]+(?<! )$

Example request

The full PAN and card details are supplied directly in the body together with the address and ZIP to verify. No init token is used.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 50,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "address": "123 Main St",
    "zip": "1000"
}

The card, amount and currency are taken from the session created by POST /v1/init (passed as the {init} path parameter), so only the address and ZIP to verify are sent.

{
    "address": "123 Main St",
    "zip": "1000"
}

A saved card token (from /v1/init, a previous payment, or POST /v1/cards) is supplied instead of the raw PAN. No init token is used, so the amount and currency travel in the body.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 50,
    "currency": "EUR",
    "card": "c6ff4cec-e9e8-4ff3-830b-6d282e08b5db",
    "address": "123 Main St",
    "zip": "1000"
}

Response

Field Type Description

code integer (0,any) Result code. 0 = success.

data object

Field	Type	Description
`raw`	string (0,any)	Raw AVS status returned by the issuer / processor.
`authorization_entity`	string (0,any)	Entity which performed the verification: Issuer or Intermediate processor.
`result_code`	string (0,any)	Parsed AVS result: No Match, Unavailable or Exact Match. Unknown is returned when the issuer replies with a status outside that set.

Example response

{
    "code": 0,
    "data": {
        "raw": "5F",
        "authorization_entity": "Issuer",
        "result_code": "Exact Match"
    }
}

Pre-authorization

POST /v1/pre-authorization/{init}

Reserve funds on a card (pre-authorization)

Operation pre_authorization

Pre-authorization blocks (reserves) an amount on the cardholder account without capturing it. This corresponds to an ISO8583 0100 message with processing code 000000. In response you will receive a transaction token in data.transaction, which must be used to settle the hold via POST/v1/capture/{transaction} or to release it via POST/v1/reversal/{transaction}. A transaction is approved when data.response_code is 00, 10 or 85: 00 = approved, 10 = partial approval (the authorized amount is returned in data.amount and is lower than the requested amount), 85 = no reason to decline. All other codes are declines and their meaning is listed in the AcquiringResponse model below. Card data, amount and currency are taken from the {init} session token when it is supplied, otherwise they are sent in the request body. The endpoint supports 3-D Secure (cavv, eci, version, directory_transaction_id from the Secure 3D result), recurring and credential-on-file classification (recurring_type), Visa AFT / Mastercard Funding, tokenized transactions (Visa TCOF / Mastercard SCOF), digital wallets and MOTO. When the instance is configured to require 3-D Secure, a transaction without cavv is rejected unless it is a MOTO transaction, a subsequent recurring / credential-on-file transaction, or carries an sca_exemption. Authentication: HMAC (pre_authorization).

Path parameters

Name	Example	Description
`init` string required	`—`	Session token from POST /v1/init. Not required. When supplied, the card, amount and currency are taken from the session and are not sent in the body.

Request body

Field Type Description

reference2 string (0,any) Extended partner reference, forwarded to the processor next to reference.

industry_specific_transaction

string (0,any)

Industry specific transaction indicator. Only 06 is accepted — used for crypto merchants (MCC 6051), together with aft.bai = LA.

06

zip string (0,any) Cardholder ZIP / postal code, submitted to the issuer for address verification (AVS).

address string (0,any) Cardholder billing address, submitted to the issuer for address verification (AVS).

moto boolean Mail Order / Telephone Order transaction. MOTO transactions are exempt from the 3-D Secure requirement.

financial_institution_service_data object contains required Financial institution service data — cardholder details required by some issuers for financial institution merchants.

Field	Type	Description
`date_of_birth`	string (0,any) required	Date of birth of the cardholder.
`postal_code`	string (0,any)	Postal code of the cardholder.
`surname`	string (0,any)	Surname of the cardholder.

client_fingerprint object Device and risk fingerprint of the cardholder (IP, geolocation, device, operating system and browser).

Field	Type	Description
`location_finger_print`	string (0,any)	Location fingerprint of the cardholder device. Maximum 64 characters.
`ip_address`	string (0,any)	IP address the cardholder used for the transaction. Maximum 32 characters.
`geo_location`	string (0,any)	Geolocation of the cardholder device. Maximum 255 characters.
`device_type`	string (0,any)	Device type used by the cardholder: 01 - mobile, 02 - desktop.
`operating_type_and_version`	string (0,any)	Windows - WI iOS - IO Mac OS - MA Linux - LI Android - AN
`browser_type_and_version`	string (0,any)	Chrome - CH Safari - SA Edge - ED Firefox - FI Opera - OP Internet Explorer - IE Samsung Internet - SI
`email`	string (0,any)	Cardholder email address. Maximum 50 characters.

delivery_details object Delivery details of the goods or services being purchased.

Field	Type	Description
`delivery_name`	string (0,any)	Name of the person receiving the delivery.
`delivery_street_name`	string (0,any)	Street of the delivery address.
`delivery_zip`	string (0,any)	ZIP / postal code of the delivery address. Maximum 10 characters.
`delivery_city`	string (0,any)	City of the delivery address.
`delivery_country`	string (0,any)	Country of the delivery address in ISO 3166-1 alpha-2 format.

sca_exemption string (0,any) Strong Customer Authentication exemption indicator. Only low-value is accepted. Allows a non-3DS transaction when the instance otherwise requires 3-D Secure.

wallet_payment object Digital wallet or network token data. Send it for Apple Pay, Google Pay and Click to Pay wallets, and for tokenized stored-credential transactions (Visa TCOF / Mastercard SCOF) with wallet_identifier = network.

Field	Type	Description
`wallet_identifier`	string (0,any)	Wallet / token type: apple-pay, google-pay or click-to-pay for digital wallets, network for tokenized stored-credential transactions (Visa TCOF / Mastercard SCOF).
`digital_payment_cryptogram`	string (0,any)	Wallet / network token cryptogram. Exactly 28 characters. Mandatory for apple-pay, for click-to-pay unless recurring_type is 2, and for network unless recurring_type is 2, 4 or 5.
`remote_commerce_acceptor_identifier`	string (0,any)	Remote commerce acceptor identifier assigned to the merchant. Maximum 150 characters. Required for Mastercard wallet and SCOF transactions.

aft object contains required Visa Account Funding Transaction (AFT) data. Send this object when initiating an AFT (wallet top-up, P2P funding, prepaid reload, A2A transfer) where the cardholder funds an account belonging to themselves. Conditional fields inside this object depend on whether the transaction is domestic or cross-border, and on country-specific rules (Canada, US, Australia). See AftDto schema for field-level rules.

Field	Type	Description
`account_owner_address1`	string (0,99)	Full address of the funded account holder (line 1). EBCDIC ANS. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_address2`	string (0,99)	Additional address of the funded account holder (line 2). EBCDIC ANS. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_street`	string (0,50)	Street name only of the funded account holder. EBCDIC ANS. Used in specific processor mappings separately from address lines. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_postal_code`	string (0,16)	Postal code of the funded account holder. EBCDIC ANS. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_city`	string (0,25)	City of the funded account holder. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_country`	string (3,3)	ISO 3166-1 alpha-3 country code of the funded account holder. Used together with MID country and issuer country to classify the transaction as domestic or cross-border. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`merchant_postal_code`	string (1,8)	Postal code of the acquiring merchant processing the AFT (not the partner). EBCDIC ANS. Conditional: mandatory for cross-border transactions destined to Canada or Australia.
`merchant_state`	string (3,3)	State/region of the acquiring merchant processing the AFT. EBCDIC ANS. Conditional: mandatory for cross-border transactions destined to Canada or Australia.
`acceptor_legal_name`	string (0,25)	Official registered business name of the merchant accepting the AFT. EBCDIC ANS. Different from card_acceptor.name (statement descriptor). Optional.
`sender_address`	string (0,35)	Address of the cardholder whose Visa card is being charged. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions.
`sender_city`	string (0,25)	City of the cardholder whose Visa card is being charged. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions.
`sender_state`	string (2,2)	State/region of the cardholder. EBCDIC AN. Conditional: required for cross-border transactions where the card is issued in Canada or the US. Optional for other cross-border transactions.
`sender_country`	string (3,3)	ISO 3166-1 alpha-3 country code of the cardholder whose Visa card is being charged. Conditional: mandatory for cross-border transactions.
`sender_name`	string (0,30)	Full name of the cardholder whose Visa card is being charged. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions.
`sender_account_number`	string (0,34) required	Destination account being funded (IBAN, wallet ID, bank account). EBCDIC ANS. Despite the name, this is the receiving account. Required for both domestic and cross-border transactions.
`recipient_name`	string (0,71) required	Full name of the person receiving the funds into the funded account. EBCDIC ANS. * Cannot contain all spaces or all numeric values. Required for domestic, cross-border and mastercard funding transactions. * Max length for mastercard is 71 symbols (two words separated by space) otherwise 30.
`bai`	string (0,any) required	Business Application Identifier. EBCDIC AN. Required by Visa for all AFTs globally (domestic and cross-border). Allowed values: AA = Account-to-Account, FT = Funds Transfer, TU = Top-Up/Reload, PP = Person-to-Person, LA = Liquid Assets. Crypto use case: for MCC 6051, bai must be LA and the field industry_specific_transaction must also be sent in the main request body (outside the aft object) with value 06. `AAFTTUPPLA`
`account_owner_subdivision_code`	string (1,3)	ISO 3166-2 state/province code of the funded account holder. EBCDIC ANS. Cannot contain all spaces. Conditional: required if account_owner_country is CAN or USA (e.g. CA, NY, ON).
`mvv`	string (1,10)	Merchant Verification Value. EBCDIC Hex. Required only for staged digital wallet funding.

partner_data object Partner data forwarded to the processor.

Field	Type	Description
`independent_sales_organization_id`	string (0,any)	Independent Sales Organization ID of the partner. Maximum 11 characters.

market_specific_extensions object Market specific data, currently the merchant category code used for the transaction.

Field	Type	Description
`mcc`	string (0,any)	Merchant category code used for the transaction. Exactly 4 characters.

additional_clearing_data object Additional merchant data forwarded in clearing.

Field	Type	Description
`merchant_street`	string (0,any)	Merchant street forwarded in clearing. Maximum 40 characters.
`merchant_postcode`	string (0,any)	Merchant postcode forwarded in clearing. Maximum 10 characters.

mpg_id string (0,any) Merchant Payment Gateway ID at processor level. When a merchant has more than one MID configured, partners can route the transaction through the corresponding MID by submitting the specific value. Maximum 11 numeric characters. Resolved for Mastercard transactions from the instance configuration when not supplied.

card_expiration_month string (0,any) Card expiry month in MM format (01 = January, 12 = December). Required for new card (PAN) payments. Must not be sent when using saved card token.

card_expiration_year string (0,any) Card expiry year in YY format. Must be the current or a future year. Must not be expired in combination with card_expiration_month. Required for new card (PAN) payments. Must not be sent when using saved card token.

merchant string (0,any) Merchant identifier. Required unless a configuration object is provided.

terminal string (0,any) Terminal identifier. When not provided, resolved from the merchant default terminal.

user string (0,any) User token in Paynetics.

amount number (0,any) required Transaction amount in major currency units (e.g. 50.00 = fifty euros). Must be a positive number with up to 2 decimal places.

currency string (0,any) required Transaction currency in ISO 4217 format (exactly 3 characters). Must be a supported currency.

card string (0,any) Saved card token for returning customers. Returned from a previous /v1/init, purchase, or POST /v1/cards call. Required for saved card (token) payments. Must not be sent when using new card PAN.

card_number string (0,any) Full Primary Account Number (PAN) as printed on the card (12–19 digits, Luhn-validated). Required for new card (PAN) payments. Must not be sent when using saved card token.

reference string (0,any) Partner reference for the transaction, returned in the transaction details and reporting.

cardholder_name string (0,any) Name as printed on the card (2–45 characters). Required for new card (PAN) payments. Must not be sent when using saved card token.

cvv2 string (0,any) Card security code (CVV2/CVC2/CID). Must be 3–4 digits. Pattern: [0-9]{3,4}.

mid string (0,any) Merchant ID at processor level. When a merchant has more than one MID configured, partners can route the transaction through the corresponding MID by submitting the specific value.

card_acceptor object Card acceptor (merchant) details.

Field	Type	Description
`name`	string (0,any)	Merchant name on the cardholder's card statement. Maximum 25 characters. Allowed characters: a-z, A-Z, 0-9, space and the symbols . , ! ? ( ) _ : ; / @ # % & * + = < > { } ~ \| ^ $ [ ] " ' - with no leading or trailing space. Pattern: ^(?! )[0-9a-zA-Z .,!?()_:;/@#%&*+=<>{}~\|^\$\[\]"'\-]+(?<! )$

xid string (0,any) 3-D Secure transaction identifier (XID), taken from the Secure 3D result. Exactly 28 characters. Required together with cavv for 3DS v1 transactions; not used for 3DS v2.

cavv string (0,any) Cardholder Authentication Verification Value returned by the Secure 3D result. Exactly 28 characters. Send it to submit the transaction as 3-D Secure authenticated; eci and version must be sent with it.

version integer (0,any) 3-D Secure protocol version from the Secure 3D result: 1 or 2. Required when cavv is sent.

directory_transaction_id string (0,any) 3-D Secure Directory Server transaction ID from the Secure 3D result. Exactly 36 characters. Required together with cavv for 3DS v2 transactions.

resolution string (0,any) 3-D Secure resolution as returned by the Secure 3D authentication result: proceed, reject, proceed_ssl, proceed_3ds or proceed_3ds_attempted.

eci string (0,any) Electronic Commerce Indicator from the Secure 3D result. Allowed values: 00, 01, 02, 05, 06, 07 (Visa uses 05/06, Mastercard uses 02/01). Required when cavv is sent.

recurring_type integer (0,any) Recurring / credential-on-file classification. 0 - non-recurring (default); 1 - recurring initial; 2 - recurring subsequent; 3 - credential-on-file initial; 4 - credential-on-file subsequent; 5 - unscheduled credential-on-file payment. Initial transactions (1, 3) must be 3-D Secure authenticated when the instance requires 3DS. Subsequent transactions (2, 4, 5) are 3DS-exempt and must reference the initial one through initial_transaction, or through transaction_stamp and settlement_date.

initial_transaction string (0,any) Transaction token of the initial recurring / credential-on-file transaction processed in Paynetics. Required for subsequent transactions (recurring_type 2, 4, 5) unless transaction_stamp and settlement_date are sent instead.

transaction_stamp string (0,any) Reference to an initial transaction processed outside Paynetics, used instead of initial_transaction for subsequent transactions (recurring_type 2, 4, 5). Must be sent together with settlement_date. Accepted only for instances configured with allow_custom_transaction_stamp.

settlement_date string (0,any) Settlement date of the initial transaction referenced by transaction_stamp, in MMDD format. Must be sent together with transaction_stamp. Accepted only for instances configured with allow_custom_transaction_stamp.

Example request

The card, amount and currency are taken from the session created by POST /v1/init (passed as the {init} path parameter). Only the 3-D Secure data of the transaction is sent in the body.

{
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "05",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b"
}

New card (PAN) pre-authorization carrying the Visa 3-D Secure result (eci 05).

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 200,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "cvv2": "123",
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "05",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b"
}

New card (PAN) pre-authorization carrying the Mastercard 3-D Secure result (eci 02).

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 200,
    "currency": "EUR",
    "card_number": "5454545454545454",
    "cardholder_name": "Jane Doe",
    "card_expiration_month": "11",
    "card_expiration_year": "26",
    "cvv2": "123",
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "02",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b"
}

New card (PAN) pre-authorization without 3-D Secure. Accepted only when the instance does not require 3-D Secure.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 80,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "cvv2": "123"
}

Billing address and postal code are verified by the issuer and the result returned in avs_status. A normal pre-authorization — an AVS mismatch does not by itself decline it.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 80,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "cvv2": "123",
    "address": "123 Main St",
    "zip": "1000"
}

A saved card token is sent instead of the PAN; the card details are resolved from the stored card.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 25,
    "currency": "EUR",
    "card": "c6ff4cec-e9e8-4ff3-830b-6d282e08b5db"
}

Mail Order / Telephone Order transaction. MOTO transactions are exempt from the 3-D Secure requirement.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 75,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "moto": true
}

Apple Pay transaction. The wallet cryptogram is mandatory for apple-pay, and the remote commerce acceptor identifier is required for Mastercard.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 120,
    "currency": "EUR",
    "card_number": "5454545454545454",
    "card_expiration_month": "11",
    "card_expiration_year": "26",
    "wallet_payment": {
        "wallet_identifier": "apple-pay",
        "digital_payment_cryptogram": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
        "remote_commerce_acceptor_identifier": "MERCHANT-ACCEPTOR-12345"
    }
}

Account Funding Transaction where card issuer, MID and acquirer are in the same country. Only the three required AFT fields are sent.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 100,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "05",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b",
    "aft": {
        "bai": "TU",
        "sender_account_number": "BG80BNBG96611020345678",
        "recipient_name": "Ivan Petrov"
    }
}

Cross-border Account Funding Transaction destined to Canada. Sender details, account owner address / subdivision and merchant postal code / state are required.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 250,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "05",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b",
    "aft": {
        "bai": "FT",
        "sender_name": "John Smith",
        "sender_address": "123 Main Street",
        "sender_city": "Toronto",
        "sender_state": "ON",
        "sender_country": "CAN",
        "sender_account_number": "CA1234567890123456",
        "recipient_name": "Ivan Petrov",
        "account_owner_address1": "123 Main Street",
        "account_owner_street": "Main Street",
        "account_owner_postal_code": "M5V 2T6",
        "account_owner_city": "Toronto",
        "account_owner_country": "CAN",
        "account_owner_subdivision_code": "ON",
        "merchant_postal_code": "1407",
        "merchant_state": "SOF"
    }
}

Mastercard Funding transaction. The business application identifier (bai) is not used; the account owner country is required.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 100,
    "currency": "EUR",
    "card_number": "5454545454545454",
    "cardholder_name": "Jane Doe",
    "card_expiration_month": "11",
    "card_expiration_year": "26",
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "02",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b",
    "aft": {
        "sender_account_number": "BG80BNBG96611020345678",
        "account_owner_country": "BGR",
        "recipient_name": "Ivan Petrov"
    }
}

Establishes a scheduled recurring series. The initial transaction must be 3-D Secure authenticated when the instance requires 3DS.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 9.99,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "recurring_type": 1,
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "05",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b"
}

Subsequent payment of a recurring series. It is 3DS-exempt and references the initial transaction processed in Paynetics.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 9.99,
    "currency": "EUR",
    "card": "c6ff4cec-e9e8-4ff3-830b-6d282e08b5db",
    "recurring_type": 2,
    "initial_transaction": "db68c6f5-0cab-4113-9c18-a9f2a6584b02"
}

Subsequent payment whose initial transaction was processed outside Paynetics. Available only for instances configured with allow_custom_transaction_stamp.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 9.99,
    "currency": "EUR",
    "card": "c6ff4cec-e9e8-4ff3-830b-6d282e08b5db",
    "recurring_type": 2,
    "transaction_stamp": "120312472701006",
    "settlement_date": "0609"
}

Stores the card credentials for later unscheduled payments. The initial transaction must be 3-D Secure authenticated when the instance requires 3DS.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 15,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "recurring_type": 3,
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "05",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b"
}

Unscheduled payment on stored credentials. It is 3DS-exempt and references the initial transaction.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 15,
    "currency": "EUR",
    "card": "c6ff4cec-e9e8-4ff3-830b-6d282e08b5db",
    "recurring_type": 5,
    "initial_transaction": "db68c6f5-0cab-4113-9c18-a9f2a6584b02"
}

Network token transaction. With wallet_identifier network the cryptogram is mandatory unless recurring_type is 2, 4 or 5.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 33,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "version": 2,
    "cavv": "AAABAmkAAAAAAASwhAJHdQAAAAA=",
    "eci": "05",
    "directory_transaction_id": "48df129e-3795-412b-ab2f-bffbb12bb00b",
    "wallet_payment": {
        "wallet_identifier": "network",
        "digital_payment_cryptogram": "AwAAAAAA3i/8YH7QQ22kQHsAAAA="
    }
}

Network token transaction without 3-D Secure data. Accepted only when the instance does not require 3-D Secure.

{
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 33,
    "currency": "EUR",
    "card_number": "4111111111111111",
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "wallet_payment": {
        "wallet_identifier": "network",
        "digital_payment_cryptogram": "AwAAAAAA3i/8YH7QQ22kQHsAAAA="
    }
}

Response

Field Type Description

code integer (0,any)

data object required

Field	Type	Description
`card_number`	string (0,any)	Masked PAN of the card used for the transaction.
`processing_code`	string (0,any)	ISO 8583 processing code of the transaction.
`amount`	number (0,any)	The amount actually processed, in major currency units. On a partial approval (response_code 10) this is the amount the issuer authorized, which is lower than the amount you requested — the requested figure is kept as requested_amount on the transaction record and is readable through GET /v1/transactions/{token}.
`stan`	string (0,any)	System Trace Audit Number of the transaction.
`local_time`	string (0,any)	Local transaction time in hhmmss format.
`local_date`	string (0,any)	Local transaction date in MMDD format.
`auth_code`	string (0,any)	Issuer authorization code. Returned on approval.
`response_code`	string (0,any)	ISO 8583 response code of the transaction. 00, 10 and 85 mean approved (10 = partial approval, the authorized amount is in amount; 85 = no reason to decline), any other value is a decline — the full list is below.
`card_acceptor_terminal_id`	string (0,any)	Card acceptor terminal ID used for the transaction.
`card_acceptor_identification_code`	string (0,any)	Card acceptor identification code used for the transaction.
`currency`	string (0,any)	Currency of the processed amount as an ISO 4217 numeric code (e.g. 978 for EUR).
`transaction`	string (0,any)	Paynetics transaction token. Use it as the {transaction} path parameter in capture, refund and reversal.
`external_transaction_id`	string (0,any)	Transaction reference at the processor.
`error_details`	string (0,any)	Human readable text for original_network_response_code. Not limited to declines — an approved transaction with response code 85 returns "Not Declined" here.
`cvv_status`	string (0,any)	Result of the CVV2 check performed by the issuer.
`avs_status`	string (0,any)	Result of the address verification (AVS) check performed by the issuer.
`ccti_id`	string (0,any)	Cross-border Credit Transaction Identifier returned by the processor.
`transaction_stamp`	string (0,any)	Transaction stamp of the transaction, used to link subsequent recurring / credential-on-file payments.
`retrieval_reference_number`	string (0,any)	Retrieval Reference Number (RRN) of the transaction.
`tlid`	string (0,any)	Transaction Link ID (Mastercard TLID, ans-22). Returned only for Mastercard transactions when provided by the processor.
`card`	string (0,any)	Card token of the card used for the transaction. Can be reused for saved-card payments.
`original_network_response_code`	string (0,any)	Raw response code returned by the card scheme.
`action_code`	string (0,any)	Action code returned by the processor.
`order`	string (0,any)	Order reference returned by the processor.

Example response

The issuer approved the pre-authorization. data.transaction is used for the subsequent capture or reversal.

{
    "code": 0,
    "data": {
        "response_code": "00",
        "auth_code": "007680",
        "transaction": "d428a647-12db-43f9-900c-c5f0779beb67",
        "external_transaction_id": "032511455501007488680123608411748868",
        "retrieval_reference_number": "608411748868",
        "stan": "748868",
        "amount": 200,
        "currency": "978",
        "card_number": "400552XXXXXX0123",
        "card": "c6ff4cec-e9e8-4ff3-830b-6d282e08b5db",
        "processing_code": "000000",
        "local_date": "0325",
        "local_time": "114556",
        "avs_status": "5F",
        "cvv_status": "M",
        "card_acceptor_terminal_id": "12345678",
        "card_acceptor_identification_code": "PAYNETICS0001",
        "original_network_response_code": "00",
        "action_code": "000"
    }
}

The issuer declined the pre-authorization. response_code is different from 00, auth_code is not returned and error_details carries the reason.

{
    "code": 0,
    "data": {
        "response_code": "05",
        "transaction": "d428a647-12db-43f9-900c-c5f0779beb67",
        "external_transaction_id": "032511455501007488680123608411748869",
        "retrieval_reference_number": "608411748869",
        "stan": "748869",
        "amount": 200,
        "currency": "978",
        "card_number": "400552XXXXXX0123",
        "processing_code": "000000",
        "local_date": "0325",
        "local_time": "114600",
        "original_network_response_code": "05",
        "action_code": "000",
        "error_details": "Do not honour"
    }
}

Capture

POST /v1/capture/{transaction}

Operation capture

Path parameters

Name	Example	Description
`transaction` string required	`—`	Initial Pre Authorization Transaction Token

Request body

Field Type Description

amount number (0,any)

reference string (0,any)

reference2 string (0,any)

sca_exemption

string (0,any)

low-value

delivery_details object

Field	Type	Description
`delivery_name`	string (1,any)	Name of the person receiving the delivery.
`delivery_street_name`	string (1,any)	Street of the delivery address.
`delivery_zip`	string (1,10)	ZIP / postal code of the delivery address. Maximum 10 characters.
`delivery_city`	string (1,any)	City of the delivery address.
`delivery_country`	string (0,any)	Country of the delivery address in ISO 3166-1 alpha-2 format.

client_fingerprint object

Field	Type	Description
`location_finger_print`	string (1,64)	Location fingerprint of the cardholder device. Maximum 64 characters.
`ip_address`	string (1,32)	IP address the cardholder used for the transaction. Maximum 32 characters.
`geo_location`	string (1,255)	Geolocation of the cardholder device. Maximum 255 characters.
`device_type`	string (2,2)	Device type used by the cardholder: 01 - mobile, 02 - desktop. `0102`
`operating_type_and_version`	string (1,4)	Windows - WI iOS - IO Mac OS - MA Linux - LI Android - AN
`browser_type_and_version`	string (1,4)	Chrome - CH Safari - SA Edge - ED Firefox - FI Opera - OP Internet Explorer - IE Samsung Internet - SI
`email`	string (1,50)	Cardholder email address. Maximum 50 characters.

partner_data object

Field	Type	Description
`payment_facilitator_id`	string (0,any)
`independent_sales_organization_id`	string (0,11)	Independent Sales Organization ID of the partner. Maximum 11 characters.
`sub_merchant_id`	string (0,any)

market_specific_extensions object

Field	Type	Description
`mcc`	string (4,4)	Merchant category code used for the transaction. Exactly 4 characters.

additional_clearing_data object

Field	Type	Description
`merchant_street`	string (0,40)	Merchant street forwarded in clearing. Maximum 40 characters.
`merchant_postcode`	string (0,10)	Merchant postcode forwarded in clearing. Maximum 10 characters.

mpg_id string (0,any)

Example request

{
    "amount": "number",
    "reference": "string",
    "reference2": "string",
    "sca_exemption": "string",
    "delivery_details": {
        "delivery_name": "John Doe",
        "delivery_street_name": "James Bourchier 76A",
        "delivery_zip": "1407",
        "delivery_city": "Sofia",
        "delivery_country": "BG"
    },
    "client_fingerprint": {
        "location_finger_print": "",
        "ip_address": "127.0.0.1",
        "geo_location": "42.6977,23.3219",
        "device_type": "02",
        "operating_type_and_version": "WI11",
        "browser_type_and_version": "CH88",
        "email": "john@example.com"
    },
    "partner_data": {
        "payment_facilitator_id": "string",
        "independent_sales_organization_id": "00001111222",
        "sub_merchant_id": "string"
    },
    "market_specific_extensions": {
        "mcc": "0000"
    },
    "additional_clearing_data": {
        "merchant_street": "James Bourchier",
        "merchant_postcode": "ABCDE12345"
    },
    "mpg_id": "string"
}

Response

Field Type Description

code integer (0,any)

data object required

Field	Type	Description
`card_number`	string (0,any)	Masked PAN of the card used for the transaction.
`processing_code`	string (0,any)	ISO 8583 processing code of the transaction.
`amount`	number (0,any)	The amount actually processed, in major currency units. On a partial approval (response_code 10) this is the amount the issuer authorized, which is lower than the amount you requested — the requested figure is kept as requested_amount on the transaction record and is readable through GET /v1/transactions/{token}.
`stan`	string (0,any)	System Trace Audit Number of the transaction.
`local_time`	string (0,any)	Local transaction time in hhmmss format.
`local_date`	string (0,any)	Local transaction date in MMDD format.
`auth_code`	string (0,any)	Issuer authorization code. Returned on approval.
`response_code`	string (0,any)	ISO 8583 response code of the transaction. 00, 10 and 85 mean approved (10 = partial approval, the authorized amount is in amount; 85 = no reason to decline), any other value is a decline — the full list is below.
`card_acceptor_terminal_id`	string (0,any)	Card acceptor terminal ID used for the transaction.
`card_acceptor_identification_code`	string (0,any)	Card acceptor identification code used for the transaction.
`currency`	string (0,any)	Currency of the processed amount as an ISO 4217 numeric code (e.g. 978 for EUR).
`transaction`	string (0,any)	Paynetics transaction token. Use it as the {transaction} path parameter in capture, refund and reversal.
`external_transaction_id`	string (0,any)	Transaction reference at the processor.
`error_details`	string (0,any)	Human readable text for original_network_response_code. Not limited to declines — an approved transaction with response code 85 returns "Not Declined" here.
`cvv_status`	string (0,any)	Result of the CVV2 check performed by the issuer.
`avs_status`	string (0,any)	Result of the address verification (AVS) check performed by the issuer.
`ccti_id`	string (0,any)	Cross-border Credit Transaction Identifier returned by the processor.
`transaction_stamp`	string (0,any)	Transaction stamp of the transaction, used to link subsequent recurring / credential-on-file payments.
`retrieval_reference_number`	string (0,any)	Retrieval Reference Number (RRN) of the transaction.
`tlid`	string (0,any)	Transaction Link ID (Mastercard TLID, ans-22). Returned only for Mastercard transactions when provided by the processor.
`card`	string (0,any)	Card token of the card used for the transaction. Can be reused for saved-card payments.
`original_network_response_code`	string (0,any)	Raw response code returned by the card scheme.
`action_code`	string (0,any)	Action code returned by the processor.
`order`	string (0,any)	Order reference returned by the processor.

Example response

{
    "code": "integer",
    "data": {
        "card_number": "400552XXXXXX0123",
        "processing_code": "000000",
        "amount": 200,
        "stan": "748868",
        "local_time": "114556",
        "local_date": "0325",
        "auth_code": "007680",
        "response_code": "00",
        "card_acceptor_terminal_id": "12345678",
        "card_acceptor_identification_code": "PAYNETICS0001",
        "currency": "978",
        "transaction": "d428a647-12db-43f9-900c-c5f0779beb67",
        "external_transaction_id": "032511455501007488680123608411748868",
        "error_details": "Do not honour",
        "cvv_status": "M",
        "avs_status": "5F",
        "ccti_id": "string",
        "transaction_stamp": "120312472701006",
        "retrieval_reference_number": "608411748868",
        "tlid": "string",
        "card": "c6ff4cec-e9e8-4ff3-830b-6d282e08b5db",
        "original_network_response_code": "00",
        "action_code": "000",
        "order": "string"
    }
}

Purchase

POST /v1/purchase/{init}

Operation purchase

Path parameters

Name	Example	Description
`init` string required	`—`	Token returned from /v1/init. Not required

Request body

Field Type Description

reference2 string (0,any)

industry_specific_transaction

string (0,any)

06

moto boolean

zip string (0,any)

address string (0,any)

balance string (0,any)

fee number (0,any)

financial_institution_service_data object contains required

Field	Type	Description
`date_of_birth`	string (0,any) required	Date of birth of the cardholder.
`postal_code`	string (0,any)	Postal code of the cardholder.
`surname`	string (0,any)	Surname of the cardholder.

client_fingerprint object

Field	Type	Description
`location_finger_print`	string (0,any)	Location fingerprint of the cardholder device. Maximum 64 characters.
`ip_address`	string (0,any)	IP address the cardholder used for the transaction. Maximum 32 characters.
`geo_location`	string (0,any)	Geolocation of the cardholder device. Maximum 255 characters.
`device_type`	string (0,any)	Device type used by the cardholder: 01 - mobile, 02 - desktop.
`operating_type_and_version`	string (0,any)	Windows - WI iOS - IO Mac OS - MA Linux - LI Android - AN
`browser_type_and_version`	string (0,any)	Chrome - CH Safari - SA Edge - ED Firefox - FI Opera - OP Internet Explorer - IE Samsung Internet - SI
`email`	string (0,any)	Cardholder email address. Maximum 50 characters.

delivery_details object

Field	Type	Description
`delivery_name`	string (0,any)	Name of the person receiving the delivery.
`delivery_street_name`	string (0,any)	Street of the delivery address.
`delivery_zip`	string (0,any)	ZIP / postal code of the delivery address. Maximum 10 characters.
`delivery_city`	string (0,any)	City of the delivery address.
`delivery_country`	string (0,any)	Country of the delivery address in ISO 3166-1 alpha-2 format.

sca_exemption string (0,any)

wallet_payment object

Field	Type	Description
`wallet_identifier`	string (0,any)	Wallet / token type: apple-pay, google-pay or click-to-pay for digital wallets, network for tokenized stored-credential transactions (Visa TCOF / Mastercard SCOF).
`digital_payment_cryptogram`	string (0,any)	Wallet / network token cryptogram. Exactly 28 characters. Mandatory for apple-pay, for click-to-pay unless recurring_type is 2, and for network unless recurring_type is 2, 4 or 5.
`remote_commerce_acceptor_identifier`	string (0,any)	Remote commerce acceptor identifier assigned to the merchant. Maximum 150 characters. Required for Mastercard wallet and SCOF transactions.

aft object contains required Visa Account Funding Transaction (AFT) data. Send this object when initiating an AFT (wallet top-up, P2P funding, prepaid reload, A2A transfer) where the cardholder funds an account belonging to themselves. Conditional fields inside this object depend on whether the transaction is domestic or cross-border, and on country-specific rules (Canada, US, Australia). See AftDto schema for field-level rules.

Field	Type	Description
`account_owner_address1`	string (0,99)	Full address of the funded account holder (line 1). EBCDIC ANS. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_address2`	string (0,99)	Additional address of the funded account holder (line 2). EBCDIC ANS. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_street`	string (0,50)	Street name only of the funded account holder. EBCDIC ANS. Used in specific processor mappings separately from address lines. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_postal_code`	string (0,16)	Postal code of the funded account holder. EBCDIC ANS. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_city`	string (0,25)	City of the funded account holder. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`account_owner_country`	string (3,3)	ISO 3166-1 alpha-3 country code of the funded account holder. Used together with MID country and issuer country to classify the transaction as domestic or cross-border. Conditional: mandatory for cross-border transactions originating from or destined to Canada.
`merchant_postal_code`	string (1,8)	Postal code of the acquiring merchant processing the AFT (not the partner). EBCDIC ANS. Conditional: mandatory for cross-border transactions destined to Canada or Australia.
`merchant_state`	string (3,3)	State/region of the acquiring merchant processing the AFT. EBCDIC ANS. Conditional: mandatory for cross-border transactions destined to Canada or Australia.
`acceptor_legal_name`	string (0,25)	Official registered business name of the merchant accepting the AFT. EBCDIC ANS. Different from card_acceptor.name (statement descriptor). Optional.
`sender_address`	string (0,35)	Address of the cardholder whose Visa card is being charged. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions.
`sender_city`	string (0,25)	City of the cardholder whose Visa card is being charged. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions.
`sender_state`	string (2,2)	State/region of the cardholder. EBCDIC AN. Conditional: required for cross-border transactions where the card is issued in Canada or the US. Optional for other cross-border transactions.
`sender_country`	string (3,3)	ISO 3166-1 alpha-3 country code of the cardholder whose Visa card is being charged. Conditional: mandatory for cross-border transactions.
`sender_name`	string (0,30)	Full name of the cardholder whose Visa card is being charged. EBCDIC ANS. Cannot contain all spaces or all numeric values. Conditional: mandatory for cross-border transactions.
`sender_account_number`	string (0,34) required	Destination account being funded (IBAN, wallet ID, bank account). EBCDIC ANS. Despite the name, this is the receiving account. Required for both domestic and cross-border transactions.
`recipient_name`	string (0,71) required	Full name of the person receiving the funds into the funded account. EBCDIC ANS. * Cannot contain all spaces or all numeric values. Required for domestic, cross-border and mastercard funding transactions. * Max length for mastercard is 71 symbols (two words separated by space) otherwise 30.
`bai`	string (0,any) required	Business Application Identifier. EBCDIC AN. Required by Visa for all AFTs globally (domestic and cross-border). Allowed values: AA = Account-to-Account, FT = Funds Transfer, TU = Top-Up/Reload, PP = Person-to-Person, LA = Liquid Assets. Crypto use case: for MCC 6051, bai must be LA and the field industry_specific_transaction must also be sent in the main request body (outside the aft object) with value 06. `AAFTTUPPLA`
`account_owner_subdivision_code`	string (1,3)	ISO 3166-2 state/province code of the funded account holder. EBCDIC ANS. Cannot contain all spaces. Conditional: required if account_owner_country is CAN or USA (e.g. CA, NY, ON).
`mvv`	string (1,10)	Merchant Verification Value. EBCDIC Hex. Required only for staged digital wallet funding.

partner_data object

Field	Type	Description
`independent_sales_organization_id`	string (0,any)	Independent Sales Organization ID of the partner. Maximum 11 characters.

market_specific_extensions object

Field	Type	Description
`mcc`	string (0,any)	Merchant category code used for the transaction. Exactly 4 characters.

additional_clearing_data object

Field	Type	Description
`merchant_street`	string (0,any)	Merchant street forwarded in clearing. Maximum 40 characters.
`merchant_postcode`	string (0,any)	Merchant postcode forwarded in clearing. Maximum 10 characters.