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.ecomcharge.com/beyag/transactions/payments with the following parameters:
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. 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.
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, eComCharge 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
required
 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.
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 (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.
birth_date
 string
The customer's date of birth in the ISO 8601 format (YYYY-MM-DD).
gender
 string
Possible values: male or female.
device_id
 string
The customer's device ID.
taxpayer_id
 string
The customer's taxpayer ID.
id_number
 string
The customer's identification document number.
external_id
 string (255)
The customer's identifier in the merchant's system.
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.
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 - eComCharge 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"].
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.
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": "2025-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",
        "external_id": "123bh7",
        "taxpayer_id": "010200A9618"
      },
      "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:
object
uid
required
 string
A transaction uid.
type
required
 string
A transaction type.
status
required
 string
A transaction status.
amount
required
 integer
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.
message
 string
A message from the eComCharge 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.
additional_data
 object
Section with additional transaction data.
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.
qr_code
 string
A link to a QR code for 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.
object
A section of the customer's address 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.
object
A section of the customer information.
ip
 string
The customer's IP address.
email
 string
The customer's email.
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;
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:
message
required
 string
Error message;
required
 object
Associative array (object) with keys corresponded types of error (for example system - system 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":"2024-06-11T12:04:59+03:00",
    "updated_at":"2024-06-11T12:04:59+03:00",
    "tracking_id":"tracking_id_000",
    "message":"Successfully processed",
    "test":true,
    "method_type":":method_name",
    "receipt_url": "https://gateway.ecomcharge.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 a form 
{
  "transaction":{
    "status":"pending",
    "type":"payment",        
    "uid":"8759cf84-e56d-44b7-a8ae-62640f6402c4",       
    "amount":1000,
    "currency":"USD",
    "description":"Order #123",
    "tracking_id":"AB8923",
    "created_at":"2024-12-07T14:21:24.420Z",
    "expired_at":"2025-12-07T14:21:240Z",
    "paid_at":"2024-12-07T14:40:120Z",
    "test":true,
    "method_type":":method_name",
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "language": "en",
    "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"
    },
    "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.