Skip to content

Charge request

Acquirers might apply various scenarios and transaction flows to process card payments for your billing scheme. It would make you implement different request types if you work with several acquirers or change your acquiring partner.

Overpay suggests using a single charge request which unifies the process of handling payments by saved card details.

When the Overpay system receives the charge request, it automatically modifies this request either to a payment or to an authorization operation. It depends on what transaction flow is supported by your acquirer which will process a payment. Moreover, if the charge request is modified to the authorization request, Overpay automatically sends the capture request.

In the back office the charge request is reported respectively to the type of the processed transaction, i.e. either as a payment or as an authorization and a capture.

Request

Send the POST request to https://gateway.overpay.io/services/credit_cards/charges with the following parameters:

Parameter Type Description
amount * required
integer An amount in minimal currency units (for example $32.45 must be sent as 3245).
currency * required
string A currency in the ISO-4217 format (for example USD).
description * required
string(255) A short order description.
tracking_id string(255) Your transaction or order ID. Please, use unique values to get the relevant transaction information by query requests. Otherwise, you get informed on the first transaction that matches tracking_id.
expired_at string Date and time till a transaction should be finalized. Use ISO 8601 format: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example 2019), 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 или –hh:mm). If a payment is not paid till the indicated date, the transaction status is set to expired.
duplicate_check boolean true or false. Used to avoid payment duplicates. By default, it is set to true, so requests with the same amount and number or token within 30 seconds will be rejected.
dynamic_billing_descriptor string Dynamic billing descriptor.
language string A language of your checkout page. It also specifies the language of email notifications sent out to your customers, if customer notifications are enabled. English (en) is set by default. Possible values of language parameter.
notification_url string URL where the system should send the notifications about a transaction. The notification request format matches the transaction response format.
verification_url string A URL where the system should send the transaction verification. The verification request format matches to the transaction response format.
return_url * conditionally required
string A URL on the merchant side where Overpay should redirect the customer after 3-D Secure verification is finished. The parameter is mandatory if your merchant account is 3-D Secure enabled. Contact your account manager for more details.
test boolean true or false. The transaction is processed as a test if the parameter is set to true.
credit_card object A section of card credentials.
number * required
string A card number. The length is from 12 to 19 digits.
verification_value * required
string 3- or 4-digit security code (CVC2, CVV2 or CID depending on the credit card brand).
It can be sent along with the token value, Overpay will transmit the card details with the given CVC2/CVV2/CID to your acquirer.
holder * required
string A cardholder name as it appears on the card. The maximal length is 32 characters.
exp_month * required
integer A card expiration month indicated with two digits (for example, 01).
exp_year * required
integer A card expiration year indicated with four digits (for example, 2026).
token * conditionally required
string A card token received earlier. The parameter is mandatory if you do not send card credentials.
If a card token is used, you should specify the additional_data.contract parameter.
skip_three_d_secure_verification boolean The parameter is used when you want your customer skip the 3-D Secure verification. 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 charge requests when a card token is submitted. Set to false, by default.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.
force_three_d_secure_verification boolean The parameter is used when you want your customer obligatory take the 3-D Secure check. Contact the tech support team to check if you can apply this parameter.
If true, Overpay forces the 3-D Secure verification for charge requests when a card token is submitted. Set to false, by default.
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.
additional_data object A section with additional transaction data. Check with the Support Team if you should send any section parameters.
p2p object A parameter section for AFT transactions.
service_id * conditionally required
string Request the parameter value from your manager.
service_extension * conditionally required
string Request the parameter value from your manager.
excluded_gateways array An array for working with cascading payments
masterpass object A Masterpass service section.
params object A section for Masterpass parameters.
session string A user session ID.
receipt_text array Text added to the customer notification. Submit it as an array of strings, for example ["First line", "Second line"].
contract array An array of elements:

recurring - Overpay provides a card token to use for recurrent payments when customers are not required to enter their card data again. Customers indicate their full card details including CVC/CVV codes and pass the 3-D Secure verification only during the initial payment;

oneclick - Overpay provides a card token for the oneclick payment flow, when the customer is redirected to the checkout page with the pre-filled card details and is just required to enter the CVC/CVV code and pass the 3-D Secure verification to complete the payment;

credit - Overpay provides a card token to use for a payout transaction;

card_on_file - Overpay returns a card token, so you can link it to the customer account and use it for payments initiated by the customer or by your application. See card_on_file section below for use cases. Note! The card_on_file option might not be supported by your acquirer. If you want to use the card_on_file option, please, contact your account manager.
avs_cvc_verification object AVS/CVC verification.
card_on_file object A section specifying the option parameters which are transmitted on to a payment network. If not specified, the initiator and type parameters are set to default values.
initiator string Applicable values:
merchant (default) - the payment is initiated by the merchant, no action by the customer is required (for example a taxi ride cost is charged automatically from the customer's card after the ride is finished);

customer - the payment is initiated by the customer, the payment confirmation by the customer is required (for example the customer pays a bill with the saved card).
type string Used only if additional_data.card_on_file.initiator is set to merchant.

delayed_charge (default) - delayed charge (for example for the additionally rendered service);

increment - you should charge an extra amount (for example in case of the upsale);

resubmission - you re-submit a transaction request due to the payment failure (for example no money on the card);

reauthorization - you want to renew the authorization (for example to keep money reserved on the card for future charges);

no_show - you want to charge the card when the customer didn't use the product or service (for example no visit to a hotel).
browser object A section of client browser details. Section parameters are required for the 3-D Secure 2.0 flow only.
accept_header integer A value of Accept request HTTP header sent by the cardholder browser.
screen_width integer Screen width in pixels. Equals the screen.width parameter of JavaScript.
screen_height integer Screen height in pixels. Equals the screen.height parameter of JavaScript.
screen_color_depth integer Screen color depth in bits per pixel. Equals the screen.colorDepth parameter of 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_width integer Browser window width in pixels. Equals the document.body.clientWidth parameter of JavaScript.
window_height integer Browser window height in pixels. Equals the document.body.clientHeight parameter of JavaScript.
language string Language of the navigator. Equals the navigator.language parameter of JavaScript.
java_enabled boolean Indicates if the browser is Java-enabled or not. Equals the navigator.javaEnabled() parameter of JavaScript.
user_agent string User agent string for the browser. Equals the navigator.userAgent parameter of JavaScript.
time_zone integer Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the new Date().getTimezoneOffset() parameter of JavaScript.
time_zone_name string A time zone name. Equals the Intl.DateTimeFormat().resolvedOptions().timeZone parameter of JavaScript.
customer * conditionally required
object A section of the customer information.
Contact the Tech Support Team to check what section parameters are required.
ip string An IP address of the customer placing an order.
email string A email of the customer placing an order.
device_id string A device ID (desktop, smartphone, etc.) of the customer placing an order.
birth_date string The customer's date of birth in the ISO 8601 format YYYY-MM-DD.
taxpayer_id string The customer's taxpayer ID.
billing_address object A section of parameters related to the customer's billing address.

Contact Tech Support Team to check if your acquirer requires any of the section parameters.
first_name * conditionally required
string The customer's first name. The maximal length is 30 characters.
last_name * conditionally required
string The customer's last name. The maximal length is 30 characters.
country * conditionally required
string The customer's billing country in ISO 3166-1 Alpha-2 format.
city * conditionally required
string The customer's billing city. The maximal length is 60 characters.
state * conditionally required
string The customer's two-letter billing state only if the billing address country is US or CA.
zip string The customer's billing ZIP or postal code. If the country is US, the zip format must be NNNNN or NNNNN-NNNN.
address * conditionally required
string The customer's billing address. The maximal length is 255 characters.
phone * conditionally required
string The customer's phone number. The maximal length is 100 characters.
travel object Section with travel related data.
airline object Section for airline ticket addendum data.
agency_code string IATA agency code (for example 03).
agency_name string Agency name that sold the ticket (for example Coral travel).
ticket_number string 14-digit ticket number. Contains 3-digit ticketing code, 4-digit form number, 6-digit serial number, and the check digit (for example 390 5241 025377 1).
booking_number string Booking code (for example DKZVUA).
restricted_ticked_indicator string Information on ticket returns. 0 - when the ticket can be returned. 1 - when the ticket may not be returned.
legs array Array of travel legs. Every leg consists of:
airline_code string 2-letter IATA code (for example B2).
stop_over_code string IATA stop-over code. If a traveler stays in the originating city more than 24h, then set the field value to O or left it empty. If the originating airport is a transit airport, then set the field value to X.
flight_number string Flight number (for example A3 971).
departure_date_time string Departure date and time (for example 2014-05-26T05:15:00).
arrival_date_time string Arrival date and time (for example2014-05-26T07:30:00).
originating_country string Country of origin (RU).
originating_city string City of origin (for example Moscow)
originating_airport_code string 3-letter IATA code of the airport of origin (for example DME).
destination_country string Country that the traveler goes to (for example Greece).
destination_city string City that the traveler goes to (for example Athens).
destination_airport_code string 3-letter IATA code of the airport that the traveler goes to (for example ATH).
coupon string Coupon number if applicable.
class string Class flight, 1-letter IATA code (for example C).
passengers array List of passengers where every list item consists of
first_name string Passenger's first name (for example KONSTANTIN).
last_name string Passenger's last name (for example IVANOV).
Response

The parameters of the response correspond to the parameters of the charge request and additionally specify the following:

Parameter Type Description
transaction object
type * required
string A transaction type, set to charge.
parent_uid * required
string Transaction ID. Same as uid, if the general request was modified to the payment, or stands for the capture request identifier.
redirect_url * required
string A URL of the page to finalize the transaction.

If the status parameter is set to incomplete, redirect the customer to this URL. It runs the 3-D Secure verification of the cardholder.

Info

At the moment, if you accept payments on the Overpay widget and indicate charge as the transaction_type parameter value, you might not receive values for the rrn or bank_code parameters.

Example of the response to the charge request
{
  "transaction": {
    "uid": "2-a658f32cfc",
    "parent_uid": "1-4ba3b43229",
    "status": "successful",
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "type": "charge",
    "payment_method_type": "credit_card",
    "tracking_id": "tracking_id_000",
    "message": "Successfully processed",
    "test": true,
    "created_at": "2021-12-22T10:20:26.768Z",
    "updated_at": "2021-12-22T10:20:26.810Z",
    "paid_at": "2021-12-22T10:20:26.802Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "http://127.0.0.1:9887/process/2-a658f32cfc",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "1cd7225cfc72c653c06bf40f7b7371d0a947ca8a37796b851e0aa4ece703b7c8",
      "brand": "mir",
      "last_4": "0013",
      "first_1": "2",
      "bin": "220138",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 12,
      "exp_year": 2026,
      "token_provider": null,
      "token": null
    },
    "receipt_url": "default_domain/customer/transactions/2-a658f32cfc/09418c951278567cba5060bfb9f6ea79a0ac255a5c47c2a2bbba8b2954ca62ba",
    "status_code": null,
    "id": "2-a658f32cfc",
    "additional_data": {
      "contract": ["card_on_file"]
    },
    "charge": {
      "message": "Capture was approved",
      "ref_id": "8889912",
      "rrn": null,
      "auth_code": null,
      "gateway_id": 1,
      "status": "successful"
    },
    "authorization": {
      "auth_code": "654321",
      "bank_code": "05",
      "rrn": "999",
      "ref_id": "777888",
      "message": "Authorization was approved",
      "amount": 100,
      "currency": "USD",
      "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
      "gateway_id": 1,
      "status": "successful"
    },
    "avs_cvc_verification": {
      "avs_verification": {
        "result_code": "1"
      },
      "cvc_verification": {
        "result_code": "1"
      }
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "device_id": "12312312321fff67",
      "birth_date": "1980-01-31"
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": null
    }
  }
}