Skip to content

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://gateway.bepaid.by/transactions/payouts with the following parameters:

Parameter Type Description
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, bePaid 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, 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 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.
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 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 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.
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": "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": "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": "2026-03-12"
      }
    }
  }
}
Response

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

Parameter Type Description
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 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, Halva, БЕЛКАРТ, МИР 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://gateway.bepaid.by/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://merchant.bepaid.by/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"
  }      
}