Initial

Open a transaction context. Every acquiring flow begins with an init call followed by an operation page.

Init

POST /v1/init

Initialize a payment session

Operation init

Initializes a payment session by validating and tokenizing card data. Returns a session token (data.token) to be passed as the {init} path parameter in the next operation, and a card token (data.card) for future payments. No financial transaction occurs. /v1/init is optional — partners can submit card data directly in each operation. Authentication: HMAC (init) or Encryption (AES-256-CBC) — depending on instance configuration. The returned token can be passed as the {init} path parameter in:
POST/v1/purchase/{init}
POST/v1/pre-authorization/{init}
POST/v1/avs/{init}
POST/v1/credit/{init}
POST/v1/oct/{init}
POST/v1/3d/enrollment/{init}
POST/v1/3d/authenticate/{init}
POST/v1/3d/result/{version}/{init}.

Request body

Field Type Description

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

{
    "card_expiration_month": "09",
    "card_expiration_year": "27",
    "merchant": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "terminal": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "user": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "amount": 50,
    "currency": "EUR",
    "card": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "card_number": "4111111111111111",
    "cardholder_name": "John Smith",
    "cvv2": "123",
    "mid": "123456789",
    "card_acceptor": {
        "name": "Partner Shop Ltd"
    }
}

Response

Field Type Description

code integer (0,any)

data object required

Field	Type	Description
`token`	string (0,any)	Session token to be passed as the {init} path parameter in the next payment operation (purchase, pre-authorization, avs, credit, oct, 3d/enrollment, etc.).
`card`	string (0,any)	Card token representing the tokenized card. Can be used as the card field in future payment requests for returning customers.

Example response

{
    "code": "integer",
    "data": {
        "token": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
        "card": "df1f946a-8b03-4a21-8eb7-dab86a77a027"
    }
}

Operation

POST /v1/{operation}/page

Generate a hosted payment page URL/HTML

Operation init_web

Generates a URL/HTML for a Paynetics-hosted payment page where the customer enters card details and completes the payment. No financial transaction occurs until the customer submits the page. After payment, the customer is redirected to success_url or error_url. Intended for partners who prefer not to handle card data directly (reducing PCI DSS scope). Authentication: HMAC (init_web).

Path parameters

Name	Example	Description
`operation` string required	`payment`	Type of hosted page. payment = standard payment page. `paymentlinkcard`

Request body

Field Type Description

amount number (0,any) required Transaction amount in major currency units. Decimal with 2 decimal places. Must be a positive number.

currency string (3,3) required Transaction currency. ISO 4217 alpha code. Must be a supported currency.

language

string (0,any)

Language of the payment page UI. bg = Bulgarian, en = English, ro = Romanian, fr = French, es = Spanish. Defaults to bg.

bgenrofres

transaction_type

string (0,any)

Transaction type. purchase = immediate payment. preauthorization = reserve funds, partner must call capture later. Defaults to purchase.

purchasepreauthorization

reference string (0,30) required Partner's transaction reference. Alphanumeric. Returned in next-day reporting.

reference2 string (0,any) Extended reference. Additional order info.

card string (10,any) Saved card token. Must be a valid card token. When provided, the payment page may pre-populate card info.

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

success_url string (0,any) Customer redirect after successful payment. Must be a valid URL.

error_url string (0,any) Customer redirect after failed payment. Must be a valid URL.

redirect boolean If true, the response is a 302 redirect to the payment page. If false, the response is a JSON body containing the payment page URL. Defaults to true.

balance string (0,any) Balance token of the client's account in Paynetics. Must be a valid balance token.

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.

recurring_end_date string (0,any) End date for the recurring schedule. ISO 8601 datetime. Must be a valid future datetime.

recurring_frequency integer (0,any) Recurring interval. Must be a positive integer.

Example request

Standard payment page for a one-time purchase. Customer enters card details on the Paynetics-hosted page.

{
    "amount": 99.9,
    "currency": "EUR",
    "language": "en",
    "transaction_type": "purchase",
    "reference": "ORDER-2026-04-001",
    "success_url": "https://partner.com/payment/success",
    "error_url": "https://partner.com/payment/error"
}

Payment page that reserves funds on the customer's card. Partner must call capture later to complete the payment.

{
    "amount": 200,
    "currency": "EUR",
    "language": "en",
    "transaction_type": "preauthorization",
    "reference": "HOTEL-BOOKING-5521",
    "success_url": "https://partner.com/booking/confirmed",
    "error_url": "https://partner.com/booking/failed"
}

Payment page pre-populated with a saved card token for a repeat purchase.

{
    "amount": 50,
    "currency": "EUR",
    "reference": "REPEAT-PURCHASE-334",
    "card": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "success_url": "https://partner.com/success",
    "error_url": "https://partner.com/error"
}

Payment page pre-populated with a saved card token used for pre-authorization (e.g. hotel booking).

{
    "amount": 50,
    "currency": "EUR",
    "transaction_type": "preauthorization",
    "reference": "HOTEL-BOOKING-5521",
    "card": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "success_url": "https://partner.com/success",
    "error_url": "https://partner.com/error"
}

Partner initiates a payment page with Account Funding Transaction data. Domestic transaction (card issuer, MID, and acquirer are in the same country). Only the three required AFT fields are sent.

{
    "amount": 100,
    "currency": "EUR",
    "reference": "AFT-DOMESTIC-1122",
    "balance": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "user": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "success_url": "https://partner.com/topup/success",
    "error_url": "https://partner.com/topup/error",
    "aft": {
        "sender_account_number": "BG80BNBG96611020345678",
        "recipient_name": "Ivan Petrov",
        "bai": "TU"
    }
}

Partner initiates a payment page with AFT data for a cross-border transaction destined to Canada. All conditional fields (account owner address/state, sender details, merchant postal code/state) are required.

{
    "amount": 250,
    "currency": "EUR",
    "reference": "AFT-CROSSBORDER-001",
    "balance": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "user": "df1f946a-8b03-4a21-8eb7-dab86a77a027",
    "success_url": "https://partner.com/topup/success",
    "error_url": "https://partner.com/topup/error",
    "aft": {
        "account_owner_address1": "123 Main Street",
        "account_owner_address2": "Suite 400",
        "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",
        "acceptor_legal_name": "Paynetics AD",
        "sender_address": "123 Main Street",
        "sender_city": "Toronto",
        "sender_state": "ON",
        "sender_country": "CAN",
        "sender_name": "John Smith",
        "sender_account_number": "CA1234567890123456",
        "recipient_name": "John Smith",
        "bai": "TU"
    }
}

Payment page that sets up a recurring schedule. Recurring interval. Must be a positive integer.

{
    "amount": 9.99,
    "currency": "EUR",
    "reference": "SUBSCRIPTION-MONTHLY-001",
    "success_url": "https://partner.com/subscription/active",
    "error_url": "https://partner.com/subscription/failed",
    "recurring_end_date": "2027-04-06T00:00:00Z",
    "recurring_frequency": 30
}

Response

Field Type Description

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

data object required

Field	Type	Description
`url`	string (0,any) required	URL of the hosted payment page. Returned when redirect=false; the partner is expected to redirect the cardholder to this URL.

Example response

{
    "code": 0,
    "data": {
        "url": "https://secure.payoo.cloud/payment/page/abc123def456"
    }
}

Errors

Code	Description
`302`	Redirect — direct browser redirect to the hosted payment page URL. Returned when redirect=true (default). The Location header contains the payment page URL (e.g. https://secure.payoo.cloud/payment/page/abc123def456).

Base URL · Production

GET https://acquiring.paynetics.net

Base URL · Sandbox

GET https://secure.payoo.cloud

On this page

Init Operation