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.unonapay.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, UnonaPay 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 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.unonapay.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://online.unonapay.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"
}
}