Skip to content

Authorization

The request is used to verify funds. It is typically employed when merchants do not fulfill orders immediately.


Request

To make an authorization transaction, send a POST request to https://api.bepaid.by/beyag/transactions/authorizations with the following parameters:

Parameter Type Description
request object
amount * required
integer Cost in minimal currency units, for example $32.45 must be sent as 3245.
currency * required
string A transaction currency in the ISO-4217 alpha-3 code format. For example, USD.
description * required
string (255) The order short description.
test boolean true or false. The transaction will be a test one if it is true.
expired_at string An expired time in ISO 8601 format. By default, infinite. 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), for example +03:00 for Minks. If authorization is not made before this time is up it will turn to status expired
tracking_id string An internal payment identifier (an order number or a customer number) assigned by the merchant. It can be used to find a payment in webhook notifications. If not submitted, it became similar to order_id value.
ip string The IP address of the customer making a purchase at your shop.
language string A language of your checkout page or customer. If the parameter is set and transaction notification emails to customers are enabled, bePaid will dispatch those emails in language locale. English (en) is set by default. Possible values of language parameter.
notification_url string A URL used for payment notifications. If it is not set, the system doesn't send notifications.
verification_url string A URL where transaction verification request will be posted to. The verification request format equals to a transaction response format.
return_url string A URL to return Customer when a transaction is completed.
iframe boolean Set to true if you open payment options at your site in iFrame. An external payment method system will try to return iFrame matched layout.
customer * conditionally required
object A section of the customer information.
Check the description of the payment method to see if any of the section parameters are required.
first_name string The customer's first name.
last_name string The customer's last name. Length: up to 30 symbols.
middle_name string The customer's middle name. Length: up to 30 symbols.
email string The customer's email.
country string The customer's billing country in the ISO 3166-1 alpha-2 format.
city string The customer's billing city. Max length: 60 chars.
zip string The customer's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
address string The customer's billing address. Max length: 255 chars.
phone string The customer's phone number. Max length: 100 chars.
birth_date string The customer's birth date in ISO 8601 format (YYYY-MM-DD).
device_id string The customer's device ID.
method object A section of parameters specific to the payment method that you plan to use.
type * required
string A type or a name of the payment method.
token string A payment method token which has been received earlier in a transaction response.
additional_data * conditionally required
object A section with additional transaction details.
Check the description of the payment method to see if any of the section parameters are required.
contract array An array consisting of elements:

recurring - bePaid returns a payment method token to use it in subsequent charges without to ask customer to re-enter payment method details again.
receipt_text array A text to add to an email notification to the customer. Submit it as an array of strings, for example ["First line", "Second line"].
customer * conditionally required
object A section of additional information about the customer.
Check the description of the payment method to see if any of the section parameters are required.
id string The customer's id. Check the chapter about the payment method to see if any of the section parameters are required.
Example of the request
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"description",
      "test": false,
      "expired_at": "2018-01-01T15:00:00+01:00",
      "tracking_id":"your_uniq_number",
      "ip":"127.0.0.1",
      "language":"en",
      "notification_url":"https://merchant.ltd/notification",
      "return_url":"https://merchant.ltd/return",
      "customer":{
        "first_name":"John",
        "last_name":"Doe",
        "middle_name": "Mid",
        "country":"US",
        "city":"Denver",
        "zip":"96002",
        "address":"1st Street",
        "phone":"17777777777",
        "device_id":"12312312321fff67"
      },
      "method":{
        "type": ":method_name"
      }
  }
}
Response

If authorization request accepted successfully response will contain a JSON message with set of fields. After finishing authorization the same message will send as a notification to the URL from notification_url. Received JSON message (response) has the only key transaction with the object as follows:

Parameter Type Description
transaction object
uid * required
string A unique identifier of the transaction (uid).
type * required
string A transaction type.
status * required
string A transaction status.
amount * required
integer The authorized amount in minimal currency units as it was submitted in the request, for example 3245 stands for $32.45.
currency * required
string A transaction currency in the ISO-4217 alpha-3 code format. For example, USD.
description * required
string (255) The short description of the transaction as it was submitted in the request.
created_at * required
string A date and time when the transaction was created in the ISO 8601 format.
updated_at * required
string Time when transaction was updated in ISO 8601 format.
method_type * required
string The name of the payment method as it was submitted in the request.
receipt_url * required
string A transaction receipt URL.
{method name} object A set of parameters specific to the payment method used to pay.
type * required
string A name of the payment method.
token string A payment method token to use it in subsequent charges.
authorization object
status * required
string Transaction status.
gateway_id * required
integer Gateway ID
ref_id string Transaction ID of external payment method system.
message string Message from payment method system.
message Message from system.
tracking_id string The ID of your transaction or order.
test boolean true or false. The transaction will be a test one if it is true
language string Language of your checkout page or customer.
paid_at string Transaction processing date.
billing_address object A section with information about customer's address.
first_name string First name.
middle_name string Middle name.
last_name string Last name.
country string Country.
city string City.
zip string Postal code or ZIP code.
address string Address.
phone string Phone number.
customer object A section of the customer information.
ip string IP-address.
email string Email.
form object A section of elements and attributes of a HTML form that user must submit to be redirected to online payment method site.
action string action attribute;
method string method attribute;
fields array Data array of form fields details (each element is an object with the keys and values as bellow):
type string Element type;
name string Element name;
id string Element id;
value string Element value;
additional_data object A section with additional transaction data.
be_protected_verification object A section of parameters of the beProtected verification service.

In case of an error, the response contains the following parameters:

Parameter Type Description
message * required
string Error message;
errors object Associative array (object) with keys corresponded types of error (for example system - system error):
error.{key} * required
array Array of error messages of appropriate type. If there was only one error (ex in the example above) - array will include only one element.
Example of the response
{
  "transaction":{
    "uid":"2-52671c8733",
    "type":"authorization",
    "status":"successful",
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "created_at":"2014-06-11T12:04:59+03:00",
    "updated_at":"2014-06-11T12:04:59+03:00",
    "tracking_id":"tracking_id_000",
    "message":"Successfully processed",
    "test":true,
    "method_type":":method_name",
    "receipt_url": "https://merchant.bepaid.by/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    ":method_name":{
      "type":":method_name",
      "token":"55524-1559836037-0-1800"
    },
    "authorization":{
      "status":"successful",
      "gateway_id":85,
      "ref_id":"777888",
      "message":"The operation was successfully processed",
    },
    "customer":{
      "ip":"127.0.0.1",
      "email":"john@example.com"
    },
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "phone":17777777777
    }
  }
}
Example of the response with beProtected section
{
  "transaction":{
    "uid":"2-52671c8733",
    "type":"authorization",
    "status":"successful",
    "amount":100,
    "currency":"USD",
    "description":"Test transaction",
    "created_at":"2014-06-11T12:04:59+03:00",
    "updated_at":"2014-06-11T12:04:59+03:00",
    "tracking_id":"tracking_id_000",
    "message":"Successfully processed",
    "test":true,
    "method_type":":method_name",
    "receipt_url": "https://merchant.bepaid.by/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    ":method_name":{
      "type":":method_name",
    },
    "authorization":{
      "status":"successful",
      "gateway_id":85,
      "ref_id":"777888",
      "message":"The operation was successfully processed",
    },
    "customer":{
      "ip":"127.0.0.1",
      "email":"john@example.com"
    },
    "billing_address":{
      "first_name":"John",
      "last_name":"Doe",
      "address":"1st Street",
      "country":"US",
      "city":"Denver",
      "zip":"96002",
      "phone":17777777777
    },
    "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":{}
      }
    }
  }
}
Example of the response with a form
{
  "transaction":{
    "status":"pending",
    "type":"authorization",
    "id":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
    "uid":"8759cf84-e56d-44b7-a8ae-62640f6402c4",
    "order_id":"100000003495",
    "amount":1000,
    "currency":"USD",
    "description":"Order #123",
    "tracking_id":"AB8923",
    "created_at":"2015-12-07T14:21:24.420Z",
    "expired_at":"2016-12-07T14:21:240Z",
    "paid_at":"2016-12-07T14:40:120Z",
    "test":true,
    "method_type":":method_name",
    "receipt_url": "https://merchant.bepaid.by/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "billing_address":{
        "first_name": "Ivan",
        "middle_name": "M",
        "last_name": "Doe",
        "country": "LV",
        "city": "Riga",
        "zip": "LV1024",
        "address": "Brivibas str, 123",
        "phone": "+372500000000"
    },
    "customer":{
        "email":"ivan@example.com",
        "ip":"127.0.0.7"
    },
    "payment":{
        "ref_id":null,
        "message":null,
        "status":"pending",
        "gateway_id":1
    },
    ":method_name":{
        "type":":method_name",
        "account":"myaccount@example.com"
    },
    "payment_form":{
        "action":"https://pay.method-name.com",
        "method":"GET",
        "fields":[
            {
              "type":"hidden",
              "name":"sid",
              "id":"sid",
              "value":"185737d3d7f665641ab339ea38dc06bc"
            }
        ]
    }
  }
}

Response parameters in case of error
{
  "message": "Unknown 'method_name_new' payment method",
  "errors": {
    "system": [
      "System error."
    ]
  }
}

Build an HTML form based on the response parameters

Based on the response example above, you need construct and show to user for submit the following form:

<form id="payment-form" action="https://pay.method-name.com" accept-charset="UTF-8" method="get">
  <input name="utf8" type="hidden" value="&#x2713;" />
  <input type="hidden" name="sid" id="sid" value="185737d3d7f665641ab339ea38dc06bc" />
  <input type="submit" name="submit" value="Pay">
</form>

Pay attention that there are no input elements in the response for submitting form (<input type="submit" name="submit" value="Pay">). You need to add this input by yourself according to design and language preferences of your site.