Skip to content

Payment

Payment transaction is a combination of authorization and capture processed at a time. This transaction type is generally used when the goods or services can be immediately provided to the customer.

Info

It is required to be PCI DSS validated to use this transaction and send plain unencrypted card data.


Request

To initiate a payment transaction, send a POST request to https://demo-gateway.begateway.com/transactions/payments with the following parameters:

Parameter Type Description
amount * required
bigInteger A transaction amount in minimal currency units, for example, $32.45 must be sent as 3245.
currency * required
string Currency in ISO-4217 format, for example, USD.
description * required
string (255) The short description of the order.
tracking_id string (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_at string Time 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_check boolean The 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_descriptor string A dynamic billing descriptor.
language string Language of your checkout page or customer. If the parameter is set and transaction notification emails to customers are enabled, Demo PSP will dispatch those emails in language locale. English (en) is set by default. Possible values of language parameter.
notification_url string The URL where the webhook notification about a transaction will be posted. The notification request format is the same as the transaction response format.
verification_url string The 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
string The URL on the merchant's website to which Demo PSP will redirect the customer once they complete 3-D verification.

Required, if your merchant account is 3-D Secure enabled.
test boolean If set to true, the transaction will be a test one. By default, false.
credit_card object
number * required
string (19) Card number.
verification_value * conditionally required
string 3- 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 Demo PSP 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 Demo PSP 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
string Instead 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_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 payment transactions 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 can be used 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 payment transactions 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.
three_d_secure object A section with the settings to apply the advanced scenario of payment processing with 3-D Secure 2.0 verification.
advanced boolean Set to true to apply the advanced scenario. Otherwise, set to false.
additional_data object A section with additional transaction data.
p2p object A section for AFT transactions.
service_id * conditionally required
string The parameter is required for an AFT transaction. Request the parameter value from your manager.
service_extension * conditionally required
string The parameter is required for an AFT transaction. Request the parameter value from your manager.
excluded_gateways array Array for working with cascading payments.
masterpass object A section of Masterpass service.
params object A section for Masterpass parameters.
session string user session id
receipt_text array A text that will be added to the customer's email. Submit it as an array of strings, for example, ["First line", "Second line"].
contract array An array which can contain the following elements:

recurring - Demo PSP 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 - Demo PSP returns a card token to use it in the oneclick payment scheme. It means Demo PSP 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 - Demo PSP returns a card token to be used for a payout

card_on_file - Demo PSP 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_verification object A section of AVS/CVC verification check.
card_on_file object A section for parameters related to storing card details for future transactions. If not submitted, default values of initiator and type parameters are applied.
initiator string merchant - (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).
type string Used 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).
browser object Section of customer browser parameters. Used only for 3DS 2.0.
accept_header string Value of Accept request HTTP header sent by the customer's browser.
screen_width integer Screen width in pixels. Equals the screen.width parameter in JavaScript.
screen_height integer Screen height in pixels. Equals the screen.height parameter in JavaScript.
screen_color_depth integer Screen 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_width integer Browser window width in pixels. Equals the document.body.clientWidth parameter in JavaScript.
window_height integer Browser window height in pixels. Equals the document.body.clientHeight parameter in JavaScript.
language string Language of the navigator. Equals the navigator.language parameter in JavaScript.
java_enabled boolean Indicates if the browser is Java-enabled or not. Equals the navigator.javaEnabled() parameter in JavaScript.
user_agent string User agent string for the browser. Equals the navigator.userAgent parameter in JavaScript.
time_zone integer Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the new Date().getTimezoneOffset() parameter in JavaScript.
time_zone_name string Time zone name. Equals the Intl.DateTimeFormat().resolvedOptions().timeZone parameter in JavaScript.
customer * conditionally required
object A section of the customer information.
Contact the Tech Support Team to check if your acquirer requires any of the section parameters.
ip * conditionally required
string The customer's IP address.
email * conditionally required
string The customer's email.
device_id * conditionally required
string The customer's device ID (desktop, smartphone, etc.).
birth_date * conditionally required
string The customer's date of birth in the ISO 8601 format YYYY-MM-DD.
taxpayer_id * conditionally required
string The customer's taxpayer ID. Contact the Tech Support Team to check if you need to submit this parameter.
billing_address * conditionally required
object A 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
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 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.
travel object An optional section with travel related data.
airline object The section with airline ticket data.
agency_code string IATA agency code, for example 03.
agency_name string Name of the agency that sold the ticket, for example, Coral travel.
ticket_number string 14-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_number string For example, DKZVUA.
restricted_ticket_indicator string If the ticket can be returned, the field value is 0, otherwise it is 1.
legs array An array of travel legs. Every leg consists of:
airline_code string 2-letter IATA code, for example B2.
stop_over_code string IATA 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_number string For example, A3 971.
departure_date_time string For example, 2014-05-26T05:15:00.
arrival_date_time string For example, 2014-05-26T07:30:00.
originating_country string For example, RU.
originating_city string For example, Moscow.
originating_airport_code string 3-letter IATA code, for example DME.
destination_country string For example, Greece.
destination_city string For example, Athens.
destination_airport_code string 3-letter IATA code, for example ATH.
coupon string Coupon number if it was applied.
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 First name of the passenger, for example, KONSTANTIN.
last_name string Last name of the passenger, for example, IVANOV.
Example of the request
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "test":true,
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "number":"4200000000000000",
        "verification_value":"123",
        "holder":"John Doe",
        "exp_month":"05",
        "exp_year":"2026"
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}
Example of the request with card token
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "test":true,
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e"
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}
Example of the request with additional receipt text
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "test":true,
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "number":"4200000000000000",
        "verification_value":"123",
        "holder":"John Doe",
        "exp_month":"05",
        "exp_year":"2026"
      },
      "additional_data":{
        "receipt_text": ["First line", "Second Line"]
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}
Example of the request with information about ticket and tour voucher sale
{
  "request":{
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "tracking_id":"your_uniq_number",
    "test":true,
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "country":"US",
      "city":"Denver",
      "state":"CO",
      "zip":"96002",
      "address":"1st Street"
      },
    "credit_card":{
      "token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e"
    },
    "customer":{
      "ip":"127.0.0.1",
      "email":"john@example.com"
    },
    "travel": {
      "airline": {
        "agency_code": "03",
        "agency_name": "Corel travel",
        "ticket_number": "390 5241 025377 1",
        "booking_number": "DKZVUA",
        "restricted_ticket_indicator": "0",
        "legs": [
          {
            "airline_code": "B2",
            "stop_over_code": "X",
            "flight_number": "A3 971",
            "departure_date_time": "2014-05-26T05:15:00",
            "arrival_date_time": "2014-05-26T07:30:00",
            "originating_country": "RU",
            "originating_city": "Moscow",
            "originating_airport_code": "DME",
            "destination_country": "Greece",
            "destination_city": "Athens",
            "destination_airport_code": "ATH",
            "coupon": "coupon code",
            "class": "C"
          }
        ],
        "passengers":[
          {
            "first_name": "KONSTANTIN",
            "last_name": "IVANOV"
          },
          {
            "first_name": "JULIA",
            "last_name": "IVANOVA"
          }
        ]
      }
    }
  }
}
Response

In the transaction section response parameters replicate request parameters except the additional ones:

Parameter Type Description
transaction object
uid * required
string A UID of the processed transaction.
status * required
string A status of the processed transaction.
message * required
string A processing result message.
type * required
string A transaction type.
tracking_id * required
string The tracking_id parameter value sent in the transaction request.
language * required
string The language parameter value sent in a transaction request or en if the parameter was omitted.
payment_method_type * required
string Payment method used to complete the transaction.

Possible values:
credit_card.
credit_card object
brand * required
string The detected card brand.
product * required
string A card product type code.
last_4 * required
string The last 4 digits of the card.
first_1 * required
string The first digit of the card.
bin * required
string (6) 6-digit bank identification number (BIN). The first 6 digits of the card number.
bin_8 * required
string (8) 8-digit bank identification number (BIN). The first 8 digits of the card number.
issuer_country * required
string (2) The country of the card issuing bank in ISO 3166-1 Alpha-2 format.
issuer_name * required
string The name of the card issuing bank.
stamp * required
string The card hash. It is constant even if expiration dates or cardholder are changed.
token * required
string The card token. Store the token and charge returning customers or run recurring charges without customers' billing details. The token lets you save the customer's details and charge them whenever they make new purchases, or you renew their services.
token_provider * required
string The detected token provider.

Possible values or null.
receipt_url * required
string A transaction receipt URL.
additional_data object A section of detailed information about the payment.
masterpass object A Masterpass service section.
params object A section for Masterpass parameters.
session string A user session ID.
result object A section for the result of a transaction in Masterpass.
status string A response status.

Possible values: successful, failed.
message string A message about Masterpass operation result generated by Demo PSP.
error string A message about an error reason in Masterpass generated by Demo PSP. Returned in case of an error.
error_message string An error message generated by Masterpass. Returned in case there is an error.
error_code string An error code generated by Masterpass. Returned in case there is an error.
token string A Masterpass card token. Returned in case the card is saved.
receipt_text array Text that will be added to the email sent to the customer.
payment object
auth_code * required
string An authorization code provided by the acquirer.
bank_code * required
string A transaction bank code.
rrn * required
string A retrieval reference number. A transaction ID issued by the card processing service.
ref_id * required
string A transaction reference ID provided by the acquirer.
message * required
string A processing result message provided by the acquirer.
billing_descriptor * required
string A billing descriptor assigned to the transaction.
status * required
string A status of the processed transaction in the acquiring bank.
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.
be_protected_verification object A section of parameters of the beProtected verification service.
avs_cvc_verification object An optional section with AVS/CVC verification results.
Example of the response
{
  "transaction":{
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      },
      "credit_card":{
        "holder":"John Doe",
        "stamp":"3709786942408b77017a3aac8390d46d77d181e34554df527a71919a856d0f28",
        "token":"40bd001563085fc35165329ea1ff5c5ecbdbbeef40bd001563085fc35165329e",
        "brand":"visa",
        "product":"F",
        "last_4":"0000",
        "first_1":"4",
        "bin": "411111",
        "bin_8": "41111100",
        "issuer_country": "US",
        "issuer_name": "VISA Demo Bank",
        "exp_month":5,
        "exp_year":2026,
        "token_provider":"apple_pay"
      },
      "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/4107-310b0da80b/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
      "additional_data":{
        "receipt_text":["First line", "Second line"]
      },
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "address":"1st Street",
        "country":"US",
        "city":"Denver",
        "zip":"96002",
        "state":"CO",
        "phone":null
      },
      "payment":{
        "auth_code":"654321",
        "bank_code":"00",
        "rrn":"999",
        "ref_id":"777888",
        "message":"The operation was successfully processed.",
        "gateway_id":317,
        "billing_descriptor":"TEST GATEWAY BILLING DESCRIPTOR",
        "status":"successful"
      },
      "uid":"4107-310b0da80b",
      "status":"successful",
      "message":"Successfully processed",
      "amount":100,
      "currency":"USD",
      "description":"Test order",
      "type":"payment",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "payment_method_type":"credit_card"
  }
}
Example of the response with incomplete 3-D Secure verification
{
    "transaction": {
        "amount": 100,
        "billing_address": {
            "address": "1st Street",
            "city": "Riga",
            "country": "LV",
            "first_name": "John",
            "last_name": "Doe",
            "phone": null,
            "state": null,
            "zip": "96002"
        },
        "created_at": "2015-05-12T15:32:43+03:00",
        "credit_card": {
            "brand": "visa",
            "product":"F",
            "exp_month": 6,
            "exp_year": 2026,
            "last_4":"0000",
            "first_1":"4",
            "bin": "411111",
            "bin_8": "41111100",
            "issuer_country": "US",
            "issuer_name": "VISA Demo Bank",
            "holder": "TESTING CARD",                
            "stamp": "6d9e060e3c91db74d0a0ba791cb78dd2de30f47944709841749eb15da66d05e4",
            "token": "12fc4d054e8242f1a1457dfe88bdfb32c5fd605e7660d59116dff00a91e3297b",
            "token_provider": null
        },
        "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/1-68bf762e1f/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
        "currency": "USD",
        "customer": {
            "device_id": "12312312321fff67",
            "email": "john@example.com",
            "ip": "127.0.0.1"
        },
        "description": "Test transaction",
        "id": "1-68bf762e1f",
        "language": "en",
        "message": null,
        "redirect_url": "https://demo-gateway.begateway.com/process/1-68bf762e1f",
        "status": "incomplete",
        "test": null,
        "tracking_id": "tracking_id_000",
        "payment_method_type":"credit_card",
        "type": "payment",
        "uid": "1-68bf762e1f",
        "updated_at": "2015-05-12T15:32:49+03:00"
    }
}
Example of the response with failed beProtected verification
{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
        "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "product":"F",
      "last_4":"0000",
      "first_1":"4",
      "bin": "411111",
      "bin_8": "41111100",
      "issuer_country": "US",
      "issuer_name": "VISA Demo Bank",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "token_provider": null,
      "exp_month":1,
      "exp_year":2026
    },
    "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/1-2d4b20c72a/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "state":"CO",
      "phone":null
    },
    "be_protected_verification":{
      "status":"failed",
      "message":"Transaction didn't pass risk management system.",
      "limit":{
        "volume":false,
        "count":false,
        "max":true,
        "current_volume":100,
        "current_count":1
      },
      "white_black_list":{
        "card_number":"black",
        "ip":"absent",
        "email":"absent"
      },
      "rules":{
        "1_123_My Shop":{
          "more_100_eur" : {"Transaction amount more than 100 AND Transaction currency is EUR": "passed"}
        },
        "1_John Doe":{},
        "Demo PSP":{}
      }
    },
    "uid":"1-2d4b20c72a",
    "status":"failed",
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "type":"payment",
    "tracking_id":"tracking_id_000",
    "payment_method_type":"credit_card",
    "message":"Merchant terminal limits exceeded (maximum transaction amount). Transaction didn't pass anti-fraud checks.",
    "test":true,
    "created_at":"2014-06-11T12:05:54+03:00",
    "updated_at":"2014-06-11T12:05:54+03:00",
    "id":"1-2d4b20c72a"
  }
}
Example of the response with successful beProtected verification
{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
      "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "product":"F",
      "last_4":"0000",
      "first_1":"4",
      "bin": "411111",
      "bin_8": "41111100",
      "issuer_country": "US",
      "issuer_name": "VISA Demo Bank",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "token_provider": null,
      "exp_month":1,
      "exp_year":2026
    },
    "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "state":"CO",
      "phone":null
    },
    "be_protected_verification":{
      "status":"successful",
      "limit":{
        "volume":false,
        "count":false,
        "max":false,
        "current_volume":90,
        "current_count":1
      },
      "white_black_list":{
        "card_number":"absent",
        "ip":"absent",
        "email":"absent"
      },
      "rules":{
        "1_123_My Shop":{
          "more_100_eur" : {"Transaction amount more than 100 AND Transaction currency is EUR": "passed"}
        },
        "1_John Doe":{},
        "Demo PSP":{}
      }
    },
    "payment":{
      "auth_code":"654321",
      "bank_code":"00",
      "rrn":"999",
      "ref_id":"777888",
      "message":"Payment was approved",
      "gateway_id":85,
      "billing_descriptor":"TEST GATEWAY BILLING DESCRIPTOR",
      "status":"successful"
    },
    "uid":"2-52671c8733",
    "status":"successful",
    "amount":90,
    "currency":"USD",
    "description":"Test transaction",
    "type":"payment",
    "tracking_id":"tracking_id_000",
    "payment_method_type":"credit_card",
    "message":"Successfully processed",
    "test":true,
    "created_at":"2014-06-11T12:04:59+03:00",
    "updated_at":"2014-06-11T12:04:59+03:00",
    "avs_cvc_verification": {
      "cvc_verification" : {
        "result_code": "M"
      },
      "avs_verification" : {
        "result_code": "M"
      }
    }
  }
}