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. 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, 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 * 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. |
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 (60) | The customer's first name. |
last_name | string (60) | The customer's last name. |
middle_name | string (60) | The customer's middle name. |
string | The customer's email. | |
country | string | The customer's billing country in the ISO 3166-1 Alpha-2 format. |
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 ). |
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": "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"
},
"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. |
qr_code | string | A link to a QR code for payment. |
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. |
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. |
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":"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://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 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":"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://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="✓" />
<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.