Skip to content

Payout

The request sends (pushes) funds to a 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://demo-gateway.begateway.com/transactions/payouts with the following parameters:

Parameter Type Description
amount * required
 integer С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 payout short description.
tracking_id string Your internal ID of the payout transaction.
duplicate_check boolean true or false. The boolean parameter controls whether the payment gateway will do duplicate check of received requests to make a payout to a card. By default, it is true and 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, 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. The notification request format equals to a transaction response format.
verification_url string The URL where transaction verification request will be posted to. The verification request format equals to a 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
 integer The card expiration month expressed with two digits (for example, 01).
exp_year * conditionally required
 integer The card expiration year expressed with four digits (for example, 2026).
token * conditionally required
 string Instead of the above 4 parameters you can send the card token you've saved from the transaction response when the card was charged for the first time
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 recipient requesting payout.
email * conditionally required
 string The email of 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.
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 and 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 US or CA.
zip 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 US or CA.
zip 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.
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": "EUR",
    "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": 2026
    },
    "additional_data": {
      "document": {
        "type": "PASSPORT",
        "issuer": "Organization name",
        "series": "MP",
        "number": "1234567890",
        "issued_at": "2010-03-12",
        "valid_until": "2025-03-12"
      }
    }
  }
}
Example of the request with card token 
{
  "request": {
    "amount": 100,
    "currency": "EUR",
    "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": "2010-03-12",
        "valid_until": "2025-03-12"
      }
    }
  }
}
Response

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

Parameter Type Description
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.
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 forward 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 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.
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": "EUR",
  "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://demo-gateway.begateway.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://demo-backoffice.begateway.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": "EUR",
    "billing_descriptor": "test descriptor",
    "gateway_id": 3483,
    "status": "successful"
  }
}