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.freepayment.online/beyag/transactions/authorizations with the following parameters:

Note

The request body must be wrapped in a top-level 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, Freepayment 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.
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 (60)
The customer's first name.
last_name
 string (60)
The customer's last name.
middle_name
 string (60)
The customer's middle name.
email
 string
The customer's email.
country
 string
The customer's billing country in the ISO 3166-1 alpha-2 format.
state
 string (40)
The customer's billing state.
city
 string (120)
The customer's billing city.
zip
 string (40)
The customer's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
address
 string (510)
The customer's billing address.
phone
 string (200)
The customer's phone number.
device_id
 string
The customer's device ID.
taxpayer_id
 string
The customer's taxpayer ID.
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.
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 - Freepayment 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"].
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:
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.
message
 string
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.
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.
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.
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.
object
A section of the customer information.
ip
 string
IP-address.
email
 string
Email.
additional_data
 object
A section with additional transaction data.
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;
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;

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://account.freepayment.online/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://account.freepayment.online/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"
    },
    "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.