Payout

The request sends (pushes) funds to the recipient's card account.

Info

Your acquiring bank might impose limits and restrictions on using this transaction type. For details, contact your manager.

---

Request

To initiate a payout transaction, send a POST request to https://processing.ecomcharge.com/transactions/payouts with the following parameters:

Note

The request body must be wrapped in a top-level request{} object.

amount required bigInteger Сost in minimal currency units, for example $32.45 must be sent as 3245. currency required string Сurrency in ISO-4217 format, for example USD. description required string (255) The short description of the payout. tracking_id string Your internal ID of the payout transaction. 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. duplicate_check boolean true or false. The boolean parameter controls whether the payment gateway will do a duplicate check of received requests to make a payout to a card. By default, it is true and duplicate requests with the same amount and number or token within 30 seconds will be rejected. 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. The notification request format is the same as the transaction response format. verification_url string The URL where transaction verification request will be posted. The verification request format equals the transaction response format. test boolean The transaction will be a test one if it is true. recipient_credit_card object A section of the recipient's card details. Contact Tech Support Team to inquire what parameters your acquirer requires for a payout. number required string (19) Card number. holder conditionally required string (32) The card holder name as it appears in the card. exp_month conditionally required string (2) Card expiration month. Must be one or two digits (for example, 01). exp_year conditionally required string (4) Card expiration year. Must be 4 digits (for example, 2027). token conditionally required string Instead of the above 4 parameters you can send the card token. The token can be obtained in the response to the recipient tokenization request. Alternatively, you can send the payout request with the filled additional_data.contract parameter, for example, "additional_data.contract":["card_on_file"] to receive the token in the response. recipient object A section of the recipient information. Contact Tech Support Team to inquire if your acquirer requires any of the section parameters. ip conditionally required string IP address of the recipient requesting payout. email conditionally required string The email of the recipient requesting payout. device_id conditionally required string Device ID (desktop, smartphone, etc.) of the recipient requesting a payout. birth_date conditionally required string The recipient's birth date in ISO 8601 format (YYYY-MM-DD). taxpayer_id conditionally required string The recipient's taxpayer ID. external_id string (255) The customer's identifier in the merchant's system. sender object A section of the sender information. Contact Tech Support Team to inquire if your acquirer requires any of the section parameters. ip conditionally required string The sender's IP address. email conditionally required string The sender's email. device_id conditionally required string The sender's device ID (desktop, smartphone, etc.). birth_date conditionally required string The sender's birth date in ISO 8601 format YYYY-MM-DD. recipient_billing_address object A section of the recipient's billing address. Contact Tech Support Team to inquire if your acquirer requires any of the section parameters. first_name conditionally required string (30) The recipient's first name. last_name conditionally required string (30) The recipient's last name. country conditionally required string The recipient's billing country in ISO 3166-1 Alpha-2 format. city conditionally required string (60) The recipient's billing city. state conditionally required string The recipient's two-letter billing state only if the billing address country is IN, US or CA. zip conditionally required string The recipient's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN. address conditionally required string (255) The recipient's billing address. phone conditionally required string (100) The recipient's phone number. sender_billing_address object A section of the sender's billing address. Contact Tech Support Team to inquire if your acquirer requires any of the section parameters. first_name conditionally required string (30) The sender's first name. last_name conditionally required string (30) The sender's last name. country conditionally required string The sender's billing country in ISO 3166-1 Alpha-2 format. city conditionally required string (60) The sender's billing city. state conditionally required string The sender's two-letter billing state only if the billing address country is IN, US or CA. zip conditionally required string The sender's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN. address conditionally required string (255) The sender's billing address. phone conditionally required string (100) The sender's phone number. additional_data object A section of additional transaction data. expected_bank_code string If this field contains a processing error, it will be sent as the value of the code parameter in the response. The parameters message and friendly_message will have the values corresponding to the specified error code. This logic applies only to test transactions. p2p object A parameter section for OCT transactions. service_id conditionally required string Request the parameter value from your manager. service_extension conditionally required string Request the parameter value from your manager. document conditionally required object A section of the sender's document information. Contact the Tech Support Team to check if your acquirer requires any of the section parameters. type conditionally required string The sender's document type. Possible values are: PASSPORT - citizen passport; ID - ID card. issuer conditionally required string The sender's document issuer. series conditionally required string The sender's document series. number conditionally required string The sender's document number. issued_at conditionally required string A date and time of issue of the sender's document. Format YYYY-MM-DD. valid_until conditionally required string An expiration date of the sender's document. Format YYYY-MM-DD.

Example of the request

{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "tracking_id": "tracking_id_000",
    "recipient": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "birth_date": "1990-10-20"
    },
    "sender": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "birth_date": "1990-10-20"
    },
    "recipient_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "city": "Denver",
      "state": "CO",
      "zip": "96002",
      "address": "1st Street",
      "phone": "375444444444"
    },
    "sender_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "city": "Denver",
      "state": "CO",
      "zip": "96002",
      "address": "1st Street",
      "phone": "375444444444"
    },
    "recipient_credit_card": {
      "number": "5555555555554444",
      "holder": "John Doe",
      "exp_month": "12",
      "exp_year": "2027"
    },
    "additional_data": {
      "document": {
        "type": "PASSPORT",
        "issuer": "Organization name",
        "series": "MP",
        "number": "1234567890",
        "issued_at": "2010-03-12",
        "valid_until": "2025-03-12"
      },
      "contract": ["card_on_file"]
    }
  }
}

Example of the request with card token

{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "tracking_id": "tracking_id_000",
    "recipient": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "birth_date": "1990-10-20"
    },
    "sender": {
      "ip": "127.0.0.1",
      "email": "john@example.com",
      "birth_date": "1990-10-20"
    },
    "recipient_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "city": "Denver",
      "state": "CO",
      "zip": "96002",
      "address": "1st Street",
      "phone": "375444444444"
    },
    "sender_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "city": "Denver",
      "state": "CO",
      "zip": "96002",
      "address": "1st Street",
      "phone": "375444444444"
    },
    "recipient_credit_card": {
      "token": "b4469f38-cec7-4f55-a86d-2ab2dc300e0b"
    },
    "additional_data": {
      "document": {
        "type": "PASSPORT",
        "issuer": "Organization name",
        "series": "MP",
        "number": "1234567890",
        "issued_at": "2024-03-12",
        "valid_until": "2027-03-12"
      }
    }
  }
}

Response

In the transaction section response parameters replicate request parameters except the additional ones:

transaction object uid required string A UID of the processed transaction. code required string Transaction processing code. friendly_message required string code description for the customer. status required string A status of the processed transaction. message required string A processing result message corresponding to the processing code (code). type required string A transaction type. tracking_id required string The tracking_id parameter value sent in the transaction request. language required string The language parameter value sent in a transaction request or en if the parameter was omitted. redirect_url conditionally required string An URL of the provider's payment page to which you should redirect your customer to complete a payout. Applicable for the payment processing flow with redirect. Contact the Tech Support Team to check if your acquirer works under this flow. payment_method_type required string Payment method, used to complete the transaction: credit_card. credit_card object brand required string The detected card brand. last_4 required string The last 4 digits of the card. first_1 required string The first digit of the card. bin required string (6) 6-digit bank identification number (BIN). The first 6 digits of the card number. bin_8 required string (8) 8-digit bank identification number (BIN). The first 8 digits of the card number. The value is returned for Visa, MasterCard, Maestro cards and the corresponding co-branded cards. Otherwise, null is returned. issuer_country required string The country of the card issuing bank. issuer_name required string The name of the card issuing bank. stamp required string The card hash. It is constant even if expiration dates or card holder are changed. token required string The card token. Store the token and charge returning customers or run recurring charges without customers' billing details. The token allows you to save the customer's details and charge them whenever they make new purchases or you renew their services. receipt_url required string A transaction receipt URL. payout object auth_code required string The acquirer's authorization code. bank_code required string A transaction bank code. rrn required string A retrieval reference number. Transaction ID issued by cards processing network. ref_id required string The acquirer's transaction reference ID. message< required string The acquirer's message. status required string A status of the processed transaction in the acquiring bank.

Example of the response

{      
  "uid": "8f2b4e0e-b6e6-41d7-970a-5a506519aa0c",
  "code": "S.0000",
  "friendly_message": "The operation is successful.",
  "status": "successful",
  "amount": 100,
  "currency": "USD",
  "description": "Test transaction ütf",
  "type": "payout",
  "tracking_id": "tracking_id_000",
  "message": "Successfully processed",
  "test": true,
  "created_at": "2024-04-02T14:57:57.638Z",
  "updated_at": "2024-04-02T14:58:04.211Z",
  "paid_at": "2024-04-02T14:58:04.172Z",
  "manually_corrected_at": null,
  "language": "en",
  "redirect_url": "https://processing.ecomcharge.com/process/8f2b4e0e-b6e6-41d7-970a-5a506519aa0c",
  "status_code": null,
  "customer": {
    "ip": "127.0.0.1",
    "email": "john@example.com",
    "device_id": null,
    "birth_date": "1990-10-20",
    "first_name": "John",
    "last_name": "Doe",
    "address": "1st Street",
    "country": "US",
    "city": "Denver",
    "zip": "96002",
    "state": "CO",
    "phone": "375444444444"
  },
  "recipient": {
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": "375444444444"
    },
    "payment_method": {
      "holder": null,
      "stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
      "brand": "visa",
      "last_4": "0000",
      "first_1": "4",
      "bin": "420000",
      "bin_8": "42000000",
      "issuer_country": "US",
      "issuer_name": "VISA Demo Bank",
      "product": "F",
      "exp_month": null,
      "exp_year": null,
      "token_provider": null,
      "token": null,
      "type": "credit_card"
    }
  },
  "links": {
    "receipt_url": "https://gateway.ecomcharge.com/customer/transactions/8f2b4e0e-b6e6-41d7-970a-5a506519aa0c/ef2a8781b3f5de417df0826fc8e371ffd621134b81435f8e2ab02d7123055a89?language=en"
  },
  "smart_routing_verification": {
    "status": "successful"
  },
  "transaction": {
    "auth_code": "654321",
    "bank_code": "00",
    "rrn": "123456789102",
    "ref_id": "777888",
    "message": "Payout was approved",
    "amount": 100,
    "currency": "USD",
    "billing_descriptor": "test descriptor",
    "gateway_id": 3483,
    "status": "successful"
  }      
}