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.

Request

To make a payment transaction, send a POST request to https://api.begateway.com/beyag/transactions/payments with the following parameters:

Parameter	Type	Description
request	object
amount * required	integer	A transaction amount 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)	A short description of the order.
test	boolean	Set to `true` for a test transaction. Otherwise, `false`, used by default.
expired_at	string	Time that the order expires at. Set 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 or –hh:mm). If payment is not made before this time, the payment gets the `expired` status. By default, infinite.
tracking_id	string	An internal payment identifier (an order number or a customer number). The parameter can be used to find the payment in notifications. If the parameter value is missing, the `order_id` value is assigned to it by default.
ip	string	The customer's IP address.
language	string	A language of the checkout page shown to the customer to complete the payment. If the parameter is set and transaction notification emails are enabled, Demo PSP will dispatch those emails in the `language` locale. English (`en`) is set by default. Possible values of `language` parameter.
notification_url	string	A URL to get webhook notifications. If the URL is not set, no notifications are sent out.
verification_url	string	A URL where a transaction verification request is posted to. The verification request format matches a transaction response format.
return_url	string	A URL to return the customer to 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 alternative payment method to see if any of the section parameters are required.
first_name	string(30)	The customer's first name.
last_name	string(30)	The customer's last name.
middle_name	string(30)	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.
city	string(60)	The customer's billing city.
zip	string	The customer's billing ZIP or postal code. If `country=US`, `zip` format must be NNNNN or NNNNN-NNNN.
address	string(255)	The customer's billing address.
phone	string(100)	The customer's phone number.
birth_date	string	The customer's date of birth in the ISO 8601 format (`YYYY-MM-DD`).
device_id	string	The customer's device ID.
id_number	string	The customer's identification document number.
method	object	A section of the payment method parameters. The set of required parameters in this section depends on the payment method that you plan to use.
type * required	string	A payment method type or payment method name supported by the payment method.
token	string	A payment method token which has been obtained earlier from a transaction response.
additional_data	object	A section of additional transaction parameters. The set of required parameters in this section depends on the payment method that you plan to use.
contract	array	An array, consisting of elements: `recurring` - Demo PSP returns a payment method token to use for subsequent charges. The customer will not need to re-enter payment method details again.
receipt_text	array	A text that will be added to an email sent to the customer. Submit as an array of strings, for example `["First line", "Second line"]`.
customer	object	A section of additional information about the customer. The set of required parameters in this section depends on the alternative payment method that you plan to use.
id	string	The customer's ID. Check the description of the alternative payment method to see what value you should submit here.
browser	object	A section of the customer's browser parameters.
user_agent * conditionally required	string	User agent string for the browser. Equals the `navigator.userAgent` parameter of JavaScript. Refer to the description of the alternative payment method to check if the parameter is 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 payment request accepted successfully response will contain a JSON message with set of fields. After finishing payment 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 transaction `uid`.
type * required	string	A transaction type.
status * required	string	A transaction status.
amount * required	integer	A transaction amount 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)	A short description of the order.
created_at * required	string	Time when the transaction was created at in the ISO-8601 format.
updated_at * required	string	Time when transaction was updated at in the ISO-8601 format.
method_type * required	string	A name of the payment method from the request.
receipt_url * required	string	A transaction receipt URL.
{method name}	object	A set of parameters specific to the payment method used by the customer to pay for the order.
type * required	string	A name of the payment method.
token	string	A payment method token. You can use it for subsequent charges.
payment	object
status * required	string	A transaction status.
gateway_id * required	integer	A system ID of the gateway that processed the transaction.
ref_id	string	A transaction ID of the system of the payment method provider.
message	string	A message received from the system of the payment method provider.
bank_code	string	Transaction result code in the provider's system.
rrn	string	Transaction identifier in the provider's system received from the 3rd party.
message	string	A message from the Demo PSP system.
tracking_id	string	An internal payment identifier (an order number or a customer number) that you assigned to the transaction.
test	boolean	`true` if the transaction is a test one. Otherwise, `false`.
language	string	A language of your checkout page shown to the customer to complete the payment.
paid_at	string	Time when the transaction is processed at.
billing_address	object	A section of the customer's addess information.
first_name	string	The customer's first name.
middle_name	string	The customer's middle name.
last_name	string	The customer's last name.
country	string	The customer's country.
city	string	The customer's city.
zip	string	The customer's postal code or ZIP code.
address	string	The customer's address.
phone	string	The customer's phone number.
customer	object	A section of the customer information.
ip	string	The customer's IP address.
email	string	The customer's email.
form	object	A section of elements and attributes of the HTML form that the merchant 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	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 * required	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":"payment",
    "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://demo-backoffice.begateway.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    ":method_name":{
      "type":":method_name",
      "token":"55524-1559836037-0-1800"
    },
    "payment":{
      "status":"successful",
      "gateway_id":85,
      "ref_id":"777888",
      "message":"The operation was successfully processed",
      "bank_code": null,
      "rrn": null
    },
    "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":"payment",
    "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://demo-backoffice.begateway.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    ":method_name":{
      "type":":method_name",
    },
    "payment":{
      "status":"successful",
      "gateway_id":85,
      "ref_id":"777888",
      "message":"The operation was successfully processed",
      "bank_code": null,
      "rrn": null
    },
    "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",
      "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":{}
      }
    }
  }
}

Example of the response with a form

{
  "transaction":{
    "status":"pending",
    "type":"payment",        
    "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://demo-backoffice.begateway.com/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,
        "bank_code": null,
        "rrn": null
    },
    ":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"
            }
        ]
    }
  }
}

Example of the error response

{
  "message": "Unknown 'method_name_new' payment method",
  "errors": {
    "system": [
      "System error."
    ]
  }
}

Build an HTML form based on the response parameters

Use the response parameters to construct and show the following form to your customer:

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