Skip to main content

Charge Items Request

POST 
/charge/v2 - Quix Charge Request - Item
Send payment

Header Parameters

  • Accept string required

    Data Type

    Example: application/json
  • Content-Type string required

    Content Type

    Example: application/json
  • prepayToken string required

    payment preparation reference received from AP

    Example: e686282e-fad0-45d7-84b6-eff5bf0c126d

Body

Encode all the information in UTF-8, format it in JSON, and send it by POST to the enabled AP endpoint for its reception.
    merchantId Integer numeric 4~7 digitsrequired

    Your merchant identifier on the AP platform.

    • It is a numerical code provided by Support in the welcome email.
    • It has 4 to 7 digits and is common for both environments (testing/production).
    merchantKey Alphanumeric Max 45 characters

    Javascript password.

    • Used to verify that the request is legitimate (sent from the merchant).
    • Must match the one stored in AP.
    operationType stringrequired

    Possible values: [DEBIT, CREDIT]

    Type of operation.

    merchantTransactionId Alphanumeric Max 45 charactersrequired

    Identifier of the transaction in your e-commerce platform. It is used for your platform to link received notifications with the customer's order.

    • Cannot be repeated between transactions.
    • Max. 45 characters - Latin-1 code page (ISO-8859-1)
    customerId Alphanumeric Max 80 charactersrequired

    Customer ID on your e-commerce platform.

    • Alphanumeric - Max. 80 characters.
    amount Decimal numeric 0~1000000.00required

    Transaction amount.

    • If the amount has decimals, use a period (.) as the decimal separator.
    • Thousands separator cannot be included.
    • In transactions that do not involve monetary movement, such as registering a customer's card, zero (0) should be sent as the amount.
    • For example, 1,234.56€ would be sent as 1234.56
    currency stringrequired

    Possible values: [EUR]

    Transaction currency.

    • ISO-4217.3 code of the transaction currency (EUR, USD, GBP, etc.).
    country Countryrequired

    Possible values: [AF, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, TP, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IL, IT, JM, JP, JO, KZ, KE, KI, KP, KR, KV, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, MS, ME, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, SH, KN, LC, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW]

    Country from which the transaction is sent. * ISO 3166-1 alpha-2 code (ES, US, UK, etc.).

    paymentSolution stringrequired

    Name of the payment solution through which the transaction should be processed (creditcards, bizum, paypal, etc.).

    apiVersion stringrequired

    Possible values: [5]

    Addon Payments Gateway API version by which the transaction should be processed.

    productId Integer numeric 6~11 digitsrequired

    Highly recommended Identifier of the product created in your AP commerce for which the transaction should be processed.

    • Provided in the welcome email.
    • Has 6 to 11 numerical digits.
    • The product limits which payment solutions activated for the commerce are offered to the customer.
    • AP allows merchants to have multiple products configured to their needs.
    • If not sent, AP will use the first product of the commerce marked in the database as "default".
      • If the commerce has no product marked "default" and the parameter is not sent, the request will generate an error.
    • May be different depending on the environment (testing and production).
    • For example:
      • A commerce has the payment solutions card, Bizum, and Quix activated.
      • The commerce has two products, one for national customers with all payment solutions activated, and another for international customers with only card payment.
      • The commerce indicates the identifier of one or the other product in the request depending on the nationality of its customer.
      • This avoids offering payment solutions like Bizum or Quix, which can only operate with national customers, to international customers.
    statusURL Alphabetical ISO 639-1required

    Highly recommended URL of your e-commerce platform where AP will send the notification with the transaction status.

    • If sent in the request, it will take priority over the one configured in the Addon Payments administration panel.
    • Alphanumeric - Max. 2048 characters.
    successURL Alphabetical ISO 639-1required

    Highly recommended URL to redirect the customer to if the transaction is authorized.

    • Alphanumeric - Max. 2048 characters.
    • If sent in the request, it will take priority over the one configured in the Addon Payments administration panel.
    • If not sent in the request, the customer will be redirected to the URL configured in the administration module.
    errorURL Alphabetical ISO 639-1required

    Highly recommended URL to redirect the customer to if the transaction is denied.

    • Alphanumeric - Max. 2048 characters.
    • If sent in the request, it will take priority over the one configured in the Addon Payments administration panel.
    • If not sent in the request, the customer will be redirected to the URL configured in the administration module.
    cancelURL Alphabetical ISO 639-1required

    Highly recommended URL to redirect the customer to if the transaction is canceled.

    • Alphanumeric - Max. 2048 characters.
    • If sent in the request, it will take priority over the one configured in the Addon Payments administration panel.
    • If not sent in the request, the customer will be redirected to the URL configured in the administration module.
    merchantParams string

    Parameters sent by your e-commerce platform to modify the transaction management in AP.

    • Alphanumeric - Max. 500 characters.
    • Parameters are sent in the following format:
      • Key1:Value1;Key2:Value2;KeyN:ValueN
    • The parameters sent will be received back in the "optionalTransactionParams" field of the response.
    description string

    Transaction description.

    • Max. 1000 characters, Latin-1 code page (ISO-8859-1)
    • Can be useful for locating or identifying it later in the AP management panel.
    awaitingURL Alphabetical ISO 639-1required

    URL to redirect the customer to if the transaction is pending processing by the payment solution.

    • Alphanumeric - Max. 2048 characters.
    firstName Alphabetical Maximum 100 charactersrequired

    First name.

    • Alphabetic - Max. 100 characters.
    • If there is more than one (1), they are separated by spaces.
    lastName Alphabetical Maximum 100 charactersrequired

    Last name(s).

    • Alphabetic - Max. 100 characters.
    • If there is more than one (1), they are separated by spaces.
    customerEmail Alphabetical Maximum 100 charactersrequired

    Email address.

    • Alphanumeric - Max. 100 characters.
    telephone Alphanumeric Maximum 45 characters

    Telephone number. Should not include the international prefix.

    • Numeric - Max. 45 characters.
    customerCountry stringrequired

    Possible values: [ES]

    ISO-3166.2 code of the customer's country (ES, US, UK, etc.).

    customerNationalId Alphanumeric Maximum 100 charactersrequired

    Identifier of the national identity document.

    • Alphanumeric - Max. 100 characters.
    • DNI number (with letter) in the case of Spanish customers.
    dob DD-MM-AAAArequired

    Date of birth.

    • Alphanumeric - Max. 10 characters.
    • Format: DD-MM-YYYY
    ipAddress IPv4 or IPv6 formatrequired

    Customer's IP address.

    • Alphanumeric - Max. 45 characters.
    • Format: IPv4 or IPv6
    paysolExtendedData objectrequired
    Extended data for Paysol processing, including product details, billing, shipping, and cart details.
    product stringrequired

    Product type, for example, 'installments'.

    billing objectrequired
    Billing information.
    first_name string

    First name for billing.

    last_name string

    Last name for billing.

    address object
    Billing address.
    street_address string

    Street address for billing.

    postal_code string

    Postal code for billing.

    city string

    City for billing.

    country string

    Country code for billing in ISO format.

    shipping object
    Shipping information.
    method string

    Shipping method.

    name string

    Shipping company name.

    first_name string

    Recipient's first name.

    last_name string

    Recipient's last name.

    company string

    Company name, if applicable.

    email string

    Email for shipping notifications.

    address object
    Shipping address.
    street_address string

    Street address for shipping.

    postal_code string

    Postal code for shipping.

    city string

    City for shipping.

    country string

    Country code for shipping in ISO format.

    cart objectrequired
    Cart details.
    currency stringrequired

    Currency of the total cart.

    total_price_with_tax floatrequired

    Total cart price including taxes.

    items object[]required
    List of items in the cart.
  • Array [
    • article objectrequired
    Item details.
    name stringrequired

    Item name.

    type stringrequired

    Item type, for example, 'product'.

    category stringrequired

    Item category, for example, 'physical'.

    reference stringrequired

    Reference identifier for the item.

    brand string

    Item brand.

    mpn string

    Manufacturer Part Number (MPN) of the item.

    url string

    Item URL.

    image_url string

    Item image URL.

    unit_price_with_tax floatrequired

    Item unit price including taxes.

    auto_shipping boolean

    Indicates if automatic shipping applies to the item.

    units integerrequired

    Number of units of the item.

    total_price_with_tax floatrequired

    Total price of the item including taxes.

    auto_shipping booleanrequired

    Indicates if automatic shipping applies to the cart.

  • ]
    • disableFormEdition boolean

    Default value: false

    allows to block the fields informed in the request (from the merchant), so that they cannot be edited in by the customer in UI

Responses
Payment request accepted
Schema
    response object
    message string
    operations object[]
  • Array [
    • amount string

    Payment Amount

    currency Currency

    Possible values: [EUR, AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNH, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPD, XPF, XPT, YER, ZAR, ZMW, ZWL]

    Currency of the transaction.

    • ISO-4217.3 code (EUR, USD, GBP, etc.).
    merchantTransactionId string
    operationType string

    Possible values: [DEBIT, CREDIT]

    Operation Type

    payFrexTransactionId string
    sorted-order string
    status string

    Possible values: [INITIATED, PENDING, TO_CAPTURE, SUCCESS, SUCCESS_WARNING, ERROR, VOIDED, REBATED, REJECTED, REDIRECTED, AWAITING_PAYSOL, SUCCESS3DS, ERROR3DS, FAIL, N/A (Not Applicable)]

    Status of the transaction after being managed by the payment solution or service

    authCode string

    Authorization code of the issuer for card payments.

    • Alphanumeric – 6 characters.
    details string

    Raw response from the payment solution.

    • Alphanumeric – Max. 1024 characters.
    mpi object
    3DSv2 response containing information about authentication in payments with card
    eci string

    Result of the authentication attempt

    paymentCode string

    Original response code of the payment solution.

    • The format and values depend on each payment solution.
    paymentDetails object
    Details of the customer's card or account
    account string

    Portfolio or customer account number

    cardHolderName string

    Card holder

    cardNumber string

    Masked card number

    • Numeric – Max. 19 digits
    • 4907270002222227 → 490727******2227
    cardNumberToken string

    Customer card reference generated by AP.

    • Alphanumeric – 16~20 characters.
    cardType string

    Possible values: [VISA, MASTERCARD, AMEX]

    Brand of the card.

    expDate string

    Expiration date of the card

    • Numeric – 4 digits.
    • Format: MMYY - MM the two digits of the month and YY the last two digits of the year.
    • For example: June 2023 → 0623
    extraDetails object[]
  • Array [
    • key string

    Data key

    value string

    Data value

  • ]
    • issuerBank string

    Name of the bank issuing the card.

    issuerCountry string

    Country of the bank issuing the card.

    paymentMessage string

    Original message of the response of the payment solution or service that has managed the transaction.

    paymentSolution string

    Name of the payment solution that has managed the transaction.

    • When this parameter is received, the “service” parameter will not be received.
    paySolTransactionId string

    Transaction identifier in the payment solution.

    • The format depends on each payment solution.
    rad string

    Additional data from the response.

    • Only available at some card issuers.
    radMessage string

    Message received together with the additional data of the response.

    • Only available at some card issuers.
    redirectionResponse string

    URL to which your e-commerce platform has to redirect the customer to complete the payment.

    respCode object
    AP response code. It maps the different response codes of the different payment services and solutions to a series of unified codes.
    message string

    AP response messages.

    uuid string

    AP internal UUID generated for the transaction.

    service string

    Name of the service that has managed the transaction.

    • When this parameter is received, the “paymentSolution” parameter will not be received
    subscriptionPlan string

    Identifier for recurring payments.

  • ]
    • status string
    workFlowResponse object
    Element that informs about the workflow that has managed the request
    id string

    Internal identifier of the workflow in AP.

    name string

    Name of the workflow.

    version string

    Version of the workflow.

Loading...