Skip to main content

Charge

POST 
/charge/v2 - Charge JS
Submit 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 and, format it in JSON and send it by POST to the AP endpoint enabled for its reception.
    merchantId Integer numeric 4~7 digitsrequired

    Identifier of your business on the AP platform.

    • It is a numeric code provided by Support in the welcome email
    • It has 4 to 7 digits and is common for both environments (test/production).
    merchantKey stringrequired

    Javascript password.

    • Used to verify that the request is legitimate (sent from the merchant).
    • Must match the one stored in AP.
    merchantTransactionId Alphanumeric Max. 45 charactersrequired

    Transaction identifier in your trading platform electronic. It is used for your platform to link the notifications received with the customer's order.

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

    ID. of the customer in your e-commerce platform.

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

    Amount of the transaction.

    • If the amount contains decimals, the period (.) is used as the decimal separator.
    • You cannot include a thousands separator.
    • In transactions that do not generate monetary movement, such as the registration of a customer's card, zero (0) must be sent as the amount.
    • For example, €1,234.56 would be sent 1234.56
    currency Currencyrequired

    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.).
    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 must 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 business in AP for which it must be processed the transaction.

    • It is provided in the welcome email.
    • Has 6 to 11 numerical digits.
    • The product is the one that limits which payment solutions of those activated for commerce are offer to the customer.
    • AP allows businesses to have various products configured to their needs.
    • If it is not sent, AP will use the first product from the business that is marked in the DB as "default"
    • If the merchant does not have any product marked "default" and the parameter is not sent, the request will fail.
      • It can be different depending on the environment (test and production).
    • For example:
      • A business has the card, Bizum and Quix payment solutions activated.
      • The business has two products, one for national customers with all payment solutions activated, and another for international customers with only card payment.
      • The merchant indicates the identifier of one or another product in the request depending on the nationality of your client
      • With this, it avoids offering payment solutions such as Bizum or Quix, which can only operate with national clients, to international clients.
    statusURL Alphabetical ISO 639-1required

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

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

    Highly Recommended Return URL to the merchant's website to which the customer will be redirected if the transaction is authorized.

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

    Highly Recommended Return URL to the merchant's website to which to redirect the customer if the transaction is denied.

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

    Highly Recommended Return URL to the merchant's website to which the customer will be redirected if they cancel the transaction.

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

    Return URL to the merchant's website to which the customer will be redirected if the transaction is pending processing by the payment solution.

    • Alphanumeric – Max. 2048 characters.
    merchantParams Clave1:Valor1;Clave2:Valor2;ClaveN:ValorN Máx. 500 characters

    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 that are sent will be received back in the “optionalTransactionParams” field of the response.
    description Alphanumeric Max. 1000 characters

    Description of the transaction.

    • Max. 1000 characters, Latin-1 code page (ISO-8859-1)
    • It can be useful to locate or identify it later in the AP management panel.
    printReceipt boolean

    Possible values: [true, false]

    Show the end customer a receipt in the optional redirection process.

    forceTokenRequest boolean

    Possible values: [false, true]

    Indicates whether or not to save the customer's card token. If you don't want to save the card, use "false"

    referenceId Alfanumérico 12 caracteres

    Variable reference for businesses that need FB500 reconciliation files.

Responses
Payment Request Accepted
Schema
    response object
    message string
    operations object[]
  • Array [
    • amount Decimal numeric 0~1000000.00

    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 Alphanumeric Max. 45 characters
    operationType string

    Possible values: [ACCOUNT_REGISTRATION, DEBIT, REFUND, REBATE, CREDIT, CANCEL_WITHDRAWAL]

    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...