Skip to content

Authorization

The authorization request is used either to check if there are enough funds available on the card to make a payment, or to hold the required amount for a future charge. When the amount is held by the authorization request, the card balance as shown to the cardholder seems to be debited for the amount. However, indeed the amount is not charged.

The authorization transaction should be followed by a capture request to charge the money, or by a void request to cancel the hold.

Info

It is required to be PCI DSS validated to use the operation and send a plain unencrypted card data.

Request

To initiate an authorization transaction, send a POST request to https://gateway.bepaid.by/transactions/authorizations 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 description of the order.
tracking_id string(255) An ID of the transaction or the order in the merchant's system.

Use unique values to get transaction information by a query request. Otherwise, you will get the first transaction with a matching tracking_id value.
expired_at string A date and time till a transaction should be completed, in the 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).
duplicate_check boolean The parameter controls whether the payment gateway will do duplicate check of received requests to authorize a card. By default, it is true and requests sent with the same amount and number or token within 30 seconds will be rejected.
dynamic_billing_descriptor string A dynamic billing descriptor.
language string A language of the checkout page or the customer.

If the parameter is set and transaction notification emails to customers are enabled, bePaid will dispatch those emails in the language locale.

Possible values:
en - English (default)
es - Spanish
tr - Turkish
de - German
it - Italian
ru - Russian
zh - Chinese
fr - French
da - Danish
sv - Swedish
no - Norwegian
fi - Finnish
pl - Polish
ja - Japanese
be - Belarusian
uk - Ukrainian
ka - Georgian
ro - Romanian
notification_url string A URL where a wehook notification about the transaction will be posted to. The notification request format matches a transaction response format.
verification_url string A URL where a transaction verification request will be posted to. The verification request format matches a transaction response format.
return_url * conditionally required
 string A URL on the merchant's side where bePaid will return the customer to after the customer passes the 3-D Secure verification. Required, if your merchant account is 3-D Secure-enabled. Contact your account manager for details, if needed.
test boolean Set to true, if the transaction should be a test one. Otherwise, false (default).
credit_card object
number * conditionally required
 string(19) A card number. The length is from 12 to 19 digits.
Required, if a card token is not submitted in the request.
verification_value * conditionally required
 string A 3- or 4-digit security code (called CVC2, CVV2 or CID depending on a credit card brand).
Required, if a card token is not submitted in the request. It can be sent along with the token parameter. In this case bePaid will submit card details with the given CVC2/CVV2/CID to the acquiring bank.
holder * conditionally required
 string(32) A cardholder name as it appears on the card. Required, if a card token is not submitted in the request.
exp_month * conditionally required
 integer(2) A card expiration month expressed with two digits (for example, 01). Required, if a card token is not submitted in the request.
exp_year * conditionally required
 integer(4) A card expiration year expressed with four digits (for example, 2007). Required, if a card token is not submitted in the request.
token * conditionally required
 string A card token that was received in the transaction response when the card was charged for the first time. Required, if card details are not submitted in the request.
If a card token is used, then the additional_data.contract parameter must be specified.
skip_three_d_secure_verification boolean The parameter enables the option for the customer to skip the 3-D Secure verification check.

Set to true, so bePaid doesn't launch the 3-D Secure verification to authorize the transactions when a card token is submitted. Otherwise, false (default).
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.

Contact the Tech Support Team to check if you can apply this parameter.
force_three_d_secure_verification boolean The parameter enables the option to make the 3-D Secure verification check obligatory for the customer.

Set to true, so bePaid forces the 3-D Secure verification to authorize the transactions when a card token is submitted. Otherwise, false (default).
The force_three_d_secure_verification parameter overrides the skip_three_d_secure_verification parameter, if both are set to true.

Contact the Tech Support Team to check if you can apply this parameter.
three_d_secure object A section with the setting to apply the advanced scenario of payment processing with the 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.
excluded_gateways array An array for working with cascading payments.
masterpass object A section of Masterpass parameters.
params object A section for Masterpass parameters.
session string A user session ID
komplat object A section of ERIP parameters.
pay_code string An ERIP final node code.
di_type string An ERIP node type code.
erip_session_id string An ERIP session ID
sub_brand object A section of detailed information about a credit card brand.
brand string A sub-brand name.

Possible values: halva.
use_points boolean Set to true to use loyalty points. Otherwise, false. The parameter is required for brand with value equal to halva.
receipt_text array Text, that will be added to client's mail. Submit it as an array of strings, for example ["First line", "Second line"].
contract * conditionally required
 array An array, consisting of elements:

recurring - bePaid returns a card token to use it in subsequent charges without to enter a 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 - bePaid returns a card token to use it in the oneclick payment scheme. It means bePaid will open a payment page with pre-filled card data and customer will be forced to enter CVC/CVV code and pass 3-D Secure verification to complete payment.

credit - bePaid returns a card token to use it for a payout

card_on_file - bePaid returns a card token to save it to a customer profile and to use the token in time-to-time charges initiated by a customer or by your application. See card_on_file section below to understand what cases the contract type covers.
Required, if a card token is submitted in the request.
avs_cvc_verification object A section of AVS/CVC verification check.
card_on_file string It sets flags submitted to a payment network why and what you charged a previously saved card for. If the value is not submitted, the default values of initiator and type are in use.
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 and order and wanted to pay by a saved card).
type string Used only in case additional_data.card_on_file.initiator is merchant.

delayed_charge - (default) delayed charge posted to a card

increment - merchant wants to charge additional amount above initially paid order (for instance, in case of upsale)

resubmission - merchant wants to resubmit a transaction due to fail with a previous charge (for instance, no money on a card)

reauthorization - merchant wants to refresh previously authorized amount (for instance, to continue to hold a money reserve on a card for future charges)

no_show - merchant wants to charge a card when customer didn't come (for instance, no visit to a hotel).
browser object A section of browser parameters. Used only for 3DS 2.0.
accept_header string 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 Time zone name. Equals the Intl.DateTimeFormat().resolvedOptions().timeZone parameter of JavaScript.
customer * conditionally required
 object A section of the customer information.
Contact Tech Support Team to inquire 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 ISO 8601 format YYYY-MM-DD.
taxpayer_id * conditionally required
 string The customer's taxpayer ID.
billing_address * conditionally required
 object A section of the customer's address details. Contact Tech Support Team to inquire if your acquirer requires any of the section parameters.
first_name * conditionally required
 string (30) The customer's first name.
last_name * conditionally required
 string (30) The customer's last name.
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 A section with travel related data.
airline object The section contains airline ticket addendum data.
agency_code string IATA agency code, for example 03.
agency_name string Agency name who sold the ticket, for example Corel travel.
ticket_number string 14-digit ticket number. Should 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_ticked_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 left it empty. If the originating airport is 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. Example, C.
passengers array List of passengers where every list item consists of
first_name string First name of passenger, for example KONSTANTIN.
last_name string Last name of passenger, for example IVANOV.
Example of the authorization 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":"2020"
      },
      "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 information about ticket and tour voucher sales 
{
  "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_ticked_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"
          }
        ]
      }
    }
  }
}
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":"2020"
      },
      "additional_data":{
        "receipt_text": ["First line", "Second Line"]
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}
Response

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

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

Possible values:
credit_card.
credit_card * required
 object
brand * required
 string A detected card brand.

Possible values: visa, master, jcb, discover, dinersclub, amex, belkart, unionpay, etc.
product * required
 string A card product.

Possible values: Electron, Classic, Gold, Standard, etc.
sub_brand string A sub-brand name.

Possible values: halva.
last_4 * required
 string The last 4 digits of the card number.
first_1 * required
 string The first digit of the card number.
stamp * required
 string A card hash.

It is constant even if either the expiration date or the cardholder is changed.
token * required
 string A card token.

The token allows you to save the customer's details and run recurring payments or charge the customer whenever s/he makes a new purchase.
token_provider * required
 string A detected token provider.

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

Possible values: successful, failed.
message string A message about a result of a Masterpass operation generated by bePaid.
error string A message about an error reason in Masterpass generated by bePaid. Returned in case of an error.
error_message string An error message generated by Masterpass. Returned in case of an error.
error_code string An error code generated by Masterpass. Returned in case of an error.
token string A Masterpass card token. Returned if the card is saved in Masterpass.
sub_brand object A section of detailed information about a credit card brand.
brand string A sub-brand name.

Possible values are: halva.
use_points boolean true, if loyalty points are used. Otherwise, false.

The parameter is required for brand with the halva value.
receipt_text array Text that will be added to the customer email.
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.
authorization * required
 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 cards processing network.
ref_id * required
 string A transaction reference ID issued by the acquirer.
message * required
 string A message provided by the acquirer.
billing_descriptor * required
 string A billing descriptor assigned to the transaction.
status * required
 string A transaction status in the acquiring bank.
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":"Gold",
        "last_4":"0000",
        "first_1":"4",
        "exp_month":5,
        "exp_year":2015,
        "token_provider":"apple_pay"// if txn was processed via Apple Pay or null if not
      },
      "receipt_url": "https://merchant.bepaid.by/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
      },
      "authorization":{
        "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":"authorization",
      "tracking_id":"your_uniq_number",
      "language":"en"
  }
}
Example of the response with failed beProtected section 
{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
        "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "product":"Gold",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2020
    },
    "receipt_url": "https://merchant.bepaid.by/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.",
      "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":{},
        "bePaid":{}
      }
    },
    "uid":"1-2d4b20c72a",
    "status":"failed",
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "type":"authorization",
    "tracking_id":"tracking_id_000",
    "message":"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 on incomplete 3-D Secure transaction 
{
  "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":"Gold",
          "exp_month": 6,
          "exp_year": 2016,
          "first_1": "4",
          "holder": "TESTING CARD",
          "last_4": "1112",
          "stamp": "6d9e060e3c91db74d0a0ba791cb78dd2de30f47944709841749eb15da66d05e4",
          "token": "12fc4d054e8242f1a1457dfe88bdfb32c5fd605e7660d59116dff00a91e3297b"
      },
      "receipt_url": "https://merchant.bepaid.by/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://gateway.bepaid.by/process/1-68bf762e1f",
      "status": "incomplete",
      "test": null,
      "tracking_id": "tracking_id_000",
      "type": "payment",
      "uid": "1-68bf762e1f",
      "updated_at": "2015-05-12T15:32:49+03:00"
  }
}
Example of the response with successful beProtected section 
{
  "transaction":{
    "customer":{
      "ip":"127.0.0.1",
      "email":"john@example.com"
    },
    "credit_card":{
      "holder":"Johnathan Doe",
      "stamp":"a825df7faba8804619aef7a6d5a5821ec292fce04e3e43933ca33d0692df90b4",
      "brand":"visa",
      "product":"Gold",
      "last_4":"0000",
      "first_1":"4",
      "token":"2bbd9fb7307dace37a9c2db1b4cca6f0c0dd143eac17294daab769224bff6ae2",
      "exp_month":1,
      "exp_year":2020
    },
    "receipt_url": "https://merchant.bepaid.by/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",
      "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":{},
        "bePaid":{}
      }
    },
    "authorization":{
      "auth_code":"654321",
      "bank_code":"00",
      "rrn":"999",
      "ref_id":"777888",
      "message":"The operation was successfully processed.",
      "gateway_id":85,
      "billing_descriptor":"TEST GATEWAY BILLING DESCRIPTOR",
      "status":"successful"
    },
    "uid":"2-52671c8733",
    "status":"successful",
    "amount":90,
    "currency":"USD",
    "description":"Test transaction",
    "type":"authorization",
    "tracking_id":"tracking_id_000",
    "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"
      }
    }
  }
}