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