Payout
The operation can be used when you need to transfer money to a customer account in the system of the payment method. It doesn't require that the account had to be used before in a payment transaction. The transaction is not supported by all payment systems and the transaction is not available to all merchants.
Request
To make a payout transaction, send a POST
request to https://api.overpay.io/beyag/transactions/payouts
with the following parameters:
Parameter | Type | Description |
---|---|---|
request | object | |
amount * required |
integer | 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 | The order short description. Max length: 255 chars. |
test | boolean | true or false . The transaction will be a test one if it is true |
tracking_id | string (255) | 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. |
ip | string | The IP address of customer making a purchase at your shop. |
language | string | Language of your checkout page or customer. If the parameter is set and transaction notification emails to customers are enabled, Overpay will dispatch those emails in language locale. English (en ) is set by default. Possible values of language parameter. |
notification_url | string | The URL where notification about a transaction will be posted to. |
verification_url | string | URL where transaction verification request will be posted to. The verification request format equals to a transaction response format. |
return_url | string | URL to return Customer when a transaction is completed |
customer * 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. |
string | The email of customer making a purchase at your shop. | |
country | string | The customer's billing country in ISO 3166-1 Alpha-2 format |
city | string (120) | The customer's billing city. Max length: 60 chars. |
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. Max length: 255 chars. |
phone | string (200) | The customer's phone number. Max length: 100 chars. |
device_id | string | The customer's device ID. |
method | object | Section of payment method choice parameters. Set of parameters in this section depends of specific system you plan to use. |
type * required |
string | Brand. |
Example of the request
{
"request":{
"amount":100,
"currency":"USD",
"description":"description",
"test": false,
"tracking_id":"your_uniq_number",
"ip":"127.0.0.1",
"language":"en",
"notification_url":"https://your-notification.url",
"return_url":"https://your-success.url",
"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": "visa"
}
}
}
Response
Parameter | Type | Description |
---|---|---|
transaction | object | |
uid * required |
string | Transaction uid |
type * required |
string | Transaction type. |
status * required |
string | Transaction status. |
amount * required |
integer | 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 | The order short description. Max length: 255 chars. |
created_at * required |
string | Time when transaction was created in ISO 8601 format. |
updated_at * required |
string | Time when transaction was updated in ISO 8601 format. |
method_type * required |
string | A payment method type or payment method name supported by the payment method. |
receipt_url * required |
string | Transaction receipt URL |
payout | object | |
status * required |
string | Transaction status. |
gateway_id * required |
integer | Gateway ID |
ref_id | string | Transaction ID of external system of the payment method. |
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 system of the payment method provider. |
message | string | Message from system. |
tracking_id | string | The ID of your transaction or order. |
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. |
billing_address | 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. |
customer | object | A section of the customer information. |
ip | string | IP-address. |
string | Email. |
Example of the response
{
"transaction":{
"uid":"2-52671c8733",
"type":"payout",
"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",
"payout":{
"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
}
}
}