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.ecomcharge.com/beyag/transactions/payouts with the following parameters:

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, eComCharge 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. 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. 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. id_number string The customer's identification document number. taxpayer_id string The customer's taxpayer ID. external_id string (255) The customer's identifier in the merchant's system. method object Section of payout 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",
        "external_id": "123bh7",
        "taxpayer_id": "010200A9618"
      },
      "method":{
        "type": "visa"
      }
  }
}

Response

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. 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 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. 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. 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.

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://gateway.ecomcharge.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
    }
  }
}