Charge request

Acquirers might apply various scenarios and transaction flows to process card payments for your billing scheme. This 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 according 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:

request object 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 will get an array of up to 10 recent transactions with the matching tracking_id. expired_at string Date and time until 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 until 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 The 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 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, 2028). 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 to 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 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, 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. referer string URL of the resource from which the transaction request is made. 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 prefilled 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 upsell); 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 An 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 the 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 An optional section with travel related data.

Example of the request

{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction",
    "tracking_id": "tracking_id_000",
    "credit_card": {
      "number": "5204240000015003",
      "verification_value": "123",
      "holder": "John Doe",
      "exp_month": "10",
      "exp_year": 2028
    },
    "additional_data": {
      "browser": {
        "screen_width": 1920,
        "screen_height": 1080,
        "screen_color_depth": 24,
        "language": "en",
        "java_enabled": false,
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
        "time_zone": -180,
        "time_zone_name": "Europe/Helskinki",
        "accept_header": "*/*",
        "window_height": 667,
        "window_width": 600
      },
      "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    },
    "three_d_secure": {
      "advanced": false
    },
    "test": true
  }
}

Response

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

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. additional_data object A section with additional transaction data. referer string URL of the resource from which the transaction request is made.

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

{
    "uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "parent_uid": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "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": "2024-06-19T08:53:41.211Z",
    "updated_at": "2024-06-19T08:53:46.217Z",
    "paid_at": "2024-06-19T08:53:46.149Z",
    "expired_at": null,
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://demo-gateway.begateway.com/process/c74e1b00-9b94-4682-82c3-60167ce64841",
    "credit_card": {
        "holder": "John Doe",
        "stamp": "a282993adc1299dacc79248e77e04c2995f79fcc9f82f408bec59ba20ff55739",
        "brand": "master",
        "last_4": "5003",
        "first_1": "5",
        "bin": "520424",
        "bin_8": "52042400",
        "issuer_country": null,
        "issuer_name": null,
        "product": null,
        "exp_month": 10,
        "exp_year": 2028,
        "token_provider": null,
        "token": null
    },
    "status_code": null,
    "gateway": {
        "iframe": true
    },
    "mute_notifications": null,
    "id": "c74e1b00-9b94-4682-82c3-60167ce64841",
    "additional_data": {
      "referer": "https://example.com/server/cs_post/post.php?order_id=5304380&security=949247&currency=USD"
    },
    "links": {
        "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/c74e1b00-9b94-4682-82c3-60167ce64841/33724a6fe94fe937575c6ed18d2ab8abdc34732df17e51be6da88e9b37356101?language=en"
    },
    "code": "S.0000",
    "friendly_message": "The operation is successful.",
    "smart_routing_verification": {
        "status": "successful"
    },
    "charge": {
        "auth_code": "654321",
        "bank_code": "05",
        "rrn": "999",
        "ref_id": "777888",
        "message": "Payment was approved",
        "amount": 100,
        "currency": "USD",
        "billing_descriptor": "test descriptor",
        "gateway_id": 3483,
        "status": "successful"
    },
    "avs_cvc_verification": {
        "avs_verification": {
            "result_code": "1"
        },
        "cvc_verification": {
            "result_code": "1"
        }
    },
    "customer": {
        "ip": null,
        "email": null,
        "device_id": null,
        "birth_date": null,
        "taxpayer_id": null,
        "external_id": null,
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    },
    "billing_address": {
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    }
}