Skip to content

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.bepaid.by/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 The ID of your transaction or order. Max length: 255 chars.
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, bePaid will dispatch those emails in language locale. English is set by default. Possible values are:

en - English
es - Spanish
tr - Turkish
de - German
it - Italian
ru - Russian
zh - Chinese
fr - French
da - Danish
sv - Swedish
no - Norwegian
fi - Finnish
pl - Polish
ja - Japanese
be - Belarussian
uk - Ukrainian
ka - Georgian
ro - Romanian
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 The customer's first name.
last_name string The customer's last name.
middle_name string The customer's middle name.
email 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 The customer's billing city. Max length: 60 chars.
zip string The customer's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
address string The customer's billing address. Max length: 255 chars.
phone string 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.
message string A message from the system of the payment method provider.
message Message from system.
tracking_id 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.
email string Email.
be_protected_verification object A section of parameters of the beProtected verification service.
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,
    "receipt_url": "https://merchant.bepaid.by/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "payout":{
      "status":"successful",
      "gateway_id":85,
      "ref_id":"777888",
      "message":"The operation was successfully processed",
    },
    "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 example with beProtected section 
{
  "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,
    "receipt_url": "https://merchant.bepaid.by/customer/transactions/2-52671c8733/11443f39ae75aa1f955a9c9283cd5045bfb0413b65d666f834a9da4e7d3926b5",
    "payout":{
      "status":"successful",
      "gateway_id":85,
      "ref_id":"777888",
      "message":"The operation was successfully processed",
    },
    "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",
      "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":{},
        "bePaid":{}
      }
    }
  }
}