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.

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

When the Demo PSP 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, Demo PSP 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://demo-gateway.begateway.com/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 Demo PSP 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, Demo PSP 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, Demo PSP 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, Demo PSP 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 - Demo PSP 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 - Demo PSP 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 - Demo PSP provides a card token to use for a payout transaction; card_on_file - Demo PSP 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 Demo PSP 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
    }
  }
}