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.pay-cross.com/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, PayCross 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 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.
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 `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.
funding_type	string	Source of funds for the money transfer. Possible values: 01 (credit card), 02 (debit card), 03 (prepaid card).
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": "[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": "2027"
    },
    "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": "[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": "2024-03-12",
        "valid_until": "2027-03-12"
      }
    }
  }
}

Example of the OCT request for SH integration option

{
  "request": {
    "amount": 100,
    "currency": "USD",
    "description": "Test transaction ütf",
    "tracking_id": "tracking_id_000",
    "recipient": {
      "ip": "127.0.0.1"
    },
    "sender": {                    
      "birth_date": "1990-10-20" //Required
    },
    "recipient_billing_address": {
      "first_name": "John", //Required
      "last_name": "Doe", //Required
      "country": "US", //Required if the recipient's country is Canada (CA), USA (US),
      //Colombia (CO) or Nicaragua (NI)
      "city": "Denver", //Required if the recipient's country is Canada (CA), USA (US),
      //Colombia (CO) or Nicaragua (NI)
      "state": "CO", //Required if the recipient's country is Canada (CA) or USA (US)          
      "address": "1st Street", //Required if the recipient's country is Canada (CA), USA (US),
      //Colombia (CO) or Nicaragua (NI)         
    },
    "sender_billing_address": {//Sender's data, the object is required if sender ≠ recipient
      "first_name": "John",
      "last_name": "Doe",
      "address": "1 First Str.",
      "country": "US",
      "city": "Denver",
      "state": "CO",//Only for US and CA                  
    },
    "recipient_credit_card": {
      "number": "5555555555554444",          
      "exp_month": "12",
      "exp_year": "2027"
    },
    "additional_data": {
      "funding_type": "01" //Optional          
    }
  }
}

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 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://gateway.pay-cross.com/process/8f2b4e0e-b6e6-41d7-970a-5a506519aa0c",
  "status_code": null,
  "customer": {
    "ip": "127.0.0.1",
    "email": "[email protected]",
    "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://admin.pay-cross.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"
  }      
}