Payment - Overpay API Documentation (2024)

amount * required
bigIntegerA transaction amount in minimal currency units, for example, $32.45 must be sent as 3245.currency * required
stringCurrency in ISO-4217 format, for example, USD.description * required
string (255)The short description of the order.tracking_idstring (255)The ID of your transaction or order. Please, use unique values in order to get the correct transaction information by query request. Otherwise, you will get the first transaction that we will find with the matching tracking_id.expired_atstringTime in the ISO-8601 format until which the transaction payment must be made: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example, 2023), MM – month (for example, 02), DD – day (for example, 09), hh – hours (for example, 18), mm – minutes (for example, 20), ss – seconds (for example, 45), TZD – time zone (+hh:mm or –hh:mm indicating an offset from UTC). If the payment is not made by the specified date and time, expired status is assigned to the transaction.duplicate_checkbooleanThe boolean parameter controls whether the payment gateway will do a duplicate check of the received requests to charge a card. By default, it is true and duplicate requests with the same amount and number or token sent within 30 seconds after the original request will be rejected.dynamic_billing_descriptorstringA dynamic billing descriptor.languagestringLanguage of your checkout page or customer. If the parameter is set and transaction notification emails to customers are enabled, Overpay will dispatch those emails in language locale. English (en) is set by default. Possible values of language parameter.notification_urlstringThe URL where the webhook notification about a transaction will be posted. The notification request format is the same as the transaction response format.verification_urlstringThe URL where the transaction verification request will be posted. The verification request format is the same as the transaction response format.return_url * conditionally required
stringThe URL on the merchant's website to which Overpay will redirect the customer once they complete 3-D verification.

Required, if your merchant account is 3-D Secure enabled.

testbooleanIf set to true, the transaction will be a test one. By default, false.credit_cardobjectnumber * required
string (19)Card number.verification_value * conditionally required
string3- or 4-digit security code (called CVC2, CVV2 or CID depending on the credit card brand).
It can be sent along with token parameter and in this case Overpay will submit the card details with the given CVC2/CVV2/CID to the acquiring bank. The parameter can be required depending on the shop settings and acquirer requirements.holder * conditionally required
string (35)The cardholder name as it appears on the card. The parameter is optional in the Overpay system but can be required by the acquirer.exp_month * required
string (2)Card expiration month. Must be one or two digits (for example, 01).exp_year * required
string (4)Card expiration year. Must be 4 digits (for example, 2026).token * conditionally required
stringInstead of the 5 parameters above you can send the card token you've saved from the transaction response when the card was charged for the first time. If a card token is used, then the additional_data.contract parameter must be specified.skip_three_d_secure_verificationbooleanThe parameter enables the option for the customer to skip the 3-D Secure verification check. Contact the Tech Support Team to check if you can apply this parameter.
If true, Overpay doesn't launch the 3-D Secure verification for payment transactions. By default, false.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.
Overridden by Smart Routing rules with Skip 3ds or Force 3ds actions.force_three_d_secure_verificationbooleanThe parameter enables the option to make the 3-D Secure verification check mandatory for the customer. Contact the Tech Support Team to check if you can apply this parameter.
If true, Overpay forces the 3-D Secure verification for payment transactions. By default, false.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.
Overridden by Smart Routing rules with Skip 3ds or Force 3ds actions.three_d_secureobjectA section with the settings to apply the advanced scenario of payment processing with 3-D Secure 2.0 verification.advancedbooleanSet to true to apply the advanced scenario. Otherwise, set to false.additional_dataobjectA section with additional transaction data.p2pobjectA section for AFT transactions. service_id * conditionally required
stringThe parameter is required for an AFT transaction. Request the parameter value from your manager. service_extension * conditionally required
stringThe parameter is required for an AFT transaction. Request the parameter value from your manager.excluded_gatewaysarrayArray for working with cascading payments.masterpassobjectA section of Masterpass service.paramsobjectA section for Masterpass parameters.sessionstringuser session idreceipt_textarrayA text that will be added to the customer's email. Submit it as an array of strings, for example, ["First line", "Second line"].contractarrayAn array which can contain the following elements:

recurring - Overpay returns a card token to be used in subsequent charges without entering the card data again. Customer agrees to be charged regularly, but initially the customer must make a payment with full card data including CVC/CVV code and pass 3-D Secure verification.

oneclick - Overpay returns a card token to use it in the oneclick payment scheme. It means Overpay will display a payment page with the prefilled card data and the customer will only be asked to enter CVC/CVV code and pass 3-D Secure verification to complete the payment.

credit - Overpay returns a card token to be used for a payout

card_on_file - Overpay returns a card token to be saved to the customer's profile and to be used in time-to-time charges initiated by the customer or by your application. See card_on_file section below to understand what cases the contract type covers. card_on_file option in the payment transaction doesn't work with all acquirers. If you want to use the card_on_file option, please contact your account manager.

avs_cvc_verificationobjectA section of AVS/CVC verification check.card_on_fileobjectA section for parameters related to storing card details for future transactions. If not submitted, default values of initiator and type parameters are applied.initiatorstringmerchant - (default) merchant initiated a card charge (for instance, for a car ride service)

customer - customer initiated a card charge (for instance, customer confirmed an order and wanted to pay with a saved card).

typestringUsed only in case additional_data.card_on_file.initiator is merchant.

delayed_charge - (default) prepaid expense charged to the customer's card

increment - additional charge beyond the initially charged amount (for example, in the case of an upsell or in the case the product is exchanged for a more expensive one)

resubmission - transaction resubmission after the previous charge has failed (for example, not sufficient funds on the card)

reauthorization - repeat authorization (for example, when the merchant wants to reauthorize the previously authorized amount for future charges)

no_show - a no-show charge (for example, no visit to a hotel).

browserobjectSection of customer browser parameters. Used only for 3DS 2.0.accept_headerstringValue of Accept request HTTP header sent by the customer's browser.screen_widthintegerScreen width in pixels. Equals the screen.width parameter in JavaScript.screen_heightintegerScreen height in pixels. Equals the screen.height parameter in JavaScript.screen_color_depthintegerScreen color depth in bits per pixel. Equals the screen.colorDepth parameter in JavaScript. Applicable values are:

1 - 1 bit
4 - 4 bits
8 - 8 bits
15 - 15 bits
16 - 16 bits
24 - 24 bits
32 - 32 bits
48 - 48 bits.

window_widthintegerBrowser window width in pixels. Equals the document.body.clientWidth parameter in JavaScript.window_heightintegerBrowser window height in pixels. Equals the document.body.clientHeight parameter in JavaScript.languagestringLanguage of the navigator. Equals the navigator.language parameter in JavaScript.java_enabledbooleanIndicates if the browser is Java-enabled or not. Equals the navigator.javaEnabled() parameter in JavaScript.user_agentstringUser agent string for the browser. Equals the navigator.userAgent parameter in JavaScript.time_zoneintegerTime zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the new Date().getTimezoneOffset() parameter in JavaScript.time_zone_namestringTime zone name. Equals the Intl.DateTimeFormat().resolvedOptions().timeZone parameter in JavaScript.customer * conditionally required
objectA section of the customer information.
Contact the Tech Support Team to check if your acquirer requires any of the section parameters.ip * conditionally required
stringThe customer's IP address.email * conditionally required
stringThe customer's email.device_id * conditionally required
stringThe customer's device ID (desktop, smartphone, etc.).birth_date * conditionally required
stringThe customer's date of birth in the ISO 8601 format YYYY-MM-DD.taxpayer_id * conditionally required
stringThe customer's taxpayer ID. Contact the Tech Support Team to check if you need to submit this parameter.billing_address * conditionally required
objectA section of the customer's address details. Contact the Tech Support Team to check if your acquirer requires any of the section parameters.first_name * conditionally required
string (30)The customer's first name. Max length: 30 chars.last_name * conditionally required
string (30)The customer's last name. Max length: 30 chars.country * conditionally required
string (2)The customer's billing country in ISO 3166-1 Alpha-2 format.city * conditionally required
string (60)The customer's billing city.state * conditionally required
stringThe customer's two-letter billing state only if the billing address country is US or CA.zipstringThe customer's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.address * conditionally required
string (255)The customer's billing address.phone * conditionally required
string (100)The customer's phone number.travelobjectAn optional section with travel related data.airlineobjectThe section with airline ticket data.agency_codestringIATA agency code, for example 03.agency_namestringName of the agency that sold the ticket, for example, Coral travel.ticket_numberstring14-digit ticket number. Must contain 3-digit ticketing code, 4-digit form number, 6-digit serial number, and check digit, for example, 390 5241 025377 1.booking_numberstringFor example, DKZVUA.restricted_ticket_indicatorstringIf the ticket can be returned, the field value is 0, otherwise it is 1.legsarrayAn array of travel legs. Every leg consists of:airline_codestring2-letter IATA code, for example B2.stop_over_codestringIATA stopover code. If a traveler stays in the originating city more than 24h, then set the field value to O or leave it empty. If the originating airport is a transit airport, then set the field value to X.flight_numberstringFor example, A3 971.departure_date_timestringFor example, 2014-05-26T05:15:00.arrival_date_timestringFor example, 2014-05-26T07:30:00.originating_countrystringFor example, RU.originating_citystringFor example, Moscow.originating_airport_codestring3-letter IATA code, for example DME.destination_countrystringFor example, Greece.destination_citystringFor example, Athens.destination_airport_codestring3-letter IATA code, for example ATH.couponstringCoupon number if it was applied.classstringClass flight, 1-letter IATA code. For example, C.passengersarrayList of passengers where every list item consists offirst_namestringFirst name of the passenger, for example, KONSTANTIN.last_namestringLast name of the passenger, for example, IVANOV.