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://gateway.pay-cross.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, PayCross will dispatch those emails in `language` locale. English is set by default. Possible values are: `en` - English `es` - Spanish `tr` - Turkish `de` - German `it` - Italian `ru` - Russian `zh` - Chinese `fr` - French `da` - Danish `sv` - Swedish `no` - Norwegian `fi` - Finnish `pl` - Polish `ja` - Japanese `be` - Belarussian `uk` - Ukrainian `ka` - Georgian `ro` - Romanian
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, 2007).
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": "RUB",
    "description": "Test transaction ütf",
    "tracking_id": "tracking_id_000",
    "recipient": {
      "ip": "127.0.0.1",
      "email": "[email protected]",
      "birth_date": "1990-10-20"
    },
    "sender": {
      "ip": "127.0.0.1",
      "email": "[email protected]",
      "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": 2022
    },
    "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": "RUB",
    "description": "Test transaction ütf",
    "tracking_id": "tracking_id_000",
    "recipient": {
      "ip": "127.0.0.1",
      "email": "[email protected]",
      "birth_date": "1990-10-20"
    },
    "sender": {
      "ip": "127.0.0.1",
      "email": "[email protected]",
      "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.
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	Detected card brand: `visa`, `master`, `jcb`, `discover`, `dinersclub`, `amex`, `belkart` and `unionpay`.
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

{
  "transaction": {
    "uid": "1-d43572b244",
    "status": "successful",
    "amount": 100,
    "currency": "RUB",
    "description": "Test transaction ütf",
    "type": "payout",
    "payment_method_type": "credit_card",
    "tracking_id": "tracking_id_000",
    "message": "Successfully processed",
    "test": false,
    "created_at": "2021-07-01T13:44:56.936Z",
    "updated_at": "2021-07-01T13:44:57.228Z",
    "paid_at": "2021-07-01T13:44:57.217Z",
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "http://127.0.0.1:9887/process/1-d43572b244",
    "credit_card": {
      "holder": "John Doe",
      "stamp": "e8a7e0cb4816c2bb608ee9a02f4f091a4982875b750bc7aba893f0ff688e2557",
      "brand": "master",
      "last_4": "4444",
      "first_1": "5",
      "bin": "555555",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 12,
      "exp_year": 2022,
      "token_provider": null,
      "token": null
    },
    "status_code": null,
    "recipient": {
      "ip": "127.0.0.1",
      "email": "[email protected]",
      "device_id": null,
      "birth_date": "1990-10-20"
    },
    "recipient_credit_card": {
      "holder": "John Doe",
      "stamp": "e8a7e0cb4816c2bb608ee9a02f4f091a4982875b750bc7aba893f0ff688e2557",
      "brand": "master",
      "last_4": "4444",
      "first_1": "5",
      "bin": "555555",
      "issuer_country": null,
      "issuer_name": null,
      "product": null,
      "exp_month": 12,
      "exp_year": 2022,
      "token_provider": null,
      "token": null
    },
    "recipient_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": "375444444444"
    },
    "receipt_url": "default_domain/customer/transactions/1-d43572b244/57cc78ebf6d0f22a599bbf039d3ba858fff6e2102f867da09cf3972fe84a8ec8",
    "sender_billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address": "1st Street",
      "country": "US",
      "city": "Denver",
      "zip": "96002",
      "state": "CO",
      "phone": "375444444444"
    },
    "id": "1-d43572b244",
    "additional_data": {
      "document": {
        "type": "PASSPORT",
        "issuer": "Organization name",
        "series": "MP",
        "number": "1234567890",
        "issued_at": "2010-03-12",
        "valid_until": "2025-03-12"
      },
      "payout": {
        "auth_code": null,
        "bank_code": null,
        "rrn": null,
        "ref_id": "1569310086280783205",
        "message": "Successfully processed",
        "amount": 100,
        "currency": "RUB",
        "billing_descriptor": null,
        "gateway_id": 1,
        "status": "successful"
      }
    }
  }
}