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. Can be multiple values separated with semicolons. For example, `"cbe59142-90af-4aea-b5a5-5bf3f66cf3da;f7883cb9-0e26-43a7-beb7-4027cb55d1a6;4a6a89d5-6950-400f"`. If multiple values are sent in the request, the transaction search in the back office system can be performed by any of them.
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.

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 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.