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.begateway.com/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, Demo PSP 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	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.
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.
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,
    "method_type":":method_name",
    "receipt_url": "https://demo-backoffice.begateway.com/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
    }
  }
}

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://demo-backoffice.begateway.com/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
    },
    "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":{},
        "Demo PSP":{}
      }
    }
  }
}