Skip to content

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.overpay.io/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, Overpay 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 - Overpay 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 Overpay 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://backoffice.overpay.io/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://backoffice.overpay.io/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":{},
        "Overpay":{}
      }
    }
  }
}
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://backoffice.overpay.io/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.