PIX Integration Payouts

PIX Payouts

POST https://api.payretailers.com/payments/v2/payout

For Payouts, customers can only submit the “active” account used for the transaction.

We will maintain the current Payout confirmation webhook.

Example:

{
  "payoutId": 1234567,
  "shopId": 62,
  "beneficiaryFirstName": "John",
  "beneficiaryLastName": "Doe",
  "documentType": "40",
  "documentNumber": "12341234ASD",
  "email": null,
  "currencyCode": "MXN",
  "country": "MX",
  "bankName": "12312",
  "accountAgencyNumber": null,
  "accountNumber": "123123123123",
  "abaSwift": null,
  "amount": 200.08,
  "settlementAmount": 10.2,
  "address": null,
  "city": null,
  "gender": null,
  "paymentReason": "test payout",
  "errorReason": null,
  "statusTypeCode": "PENDING",
  "externalReference": "external1",
  "payoutAccountTypeCode": "0001",
  "phone": null,
  "payoutBatch": {
    "payoutBatchId": 39832,
    "description": "PAYOUT_BATCH_TEST_20220525091740",
    "date": "2022-05-25T09:17:40.337"
  }
}

See https://www.payretailers.dev/reference/notifications#payout-notifications for Payout Notification Flow.

See https://payretailers.readme.io/reference/payout-parameters#bank-name for Payout Parameter definitions.

The structure of the API remains unchanged. However, bank account data must now include the Pix Key to enable account validation. If the Pix Key is not provided, the account data can still be submitted, and the transaction will proceed without validation.

{
 "country": "BR",
 "amount": 100,
 "currencyCode": "BRL",
 "payoutBeneficiaryTypeCode": "person",
 "beneficiaryFirstName": "Jhon",
 "beneficiaryLastName": "Doe",
 "documentType": "1",
 "documentNumber": "1XXXXXXXXXXXX0",
 "email": "[email protected]",
 "bankName": "001",
 "city": "City",
 "address": "Address",
 "recipientPixKey": null,
 "accountNumber": "0123456789",
 "accountAgencyNumber": "0001",
 "payoutAccountTypeCode": "0002",
 "phone": "+55XX9XXXXXXXX",
 "externalReference": "1234567890",
 "notificationUrl": "https://payretailers.com/notifications/result.php",
 "paymentReason": "Test WD",
}

Error Messages

Below are the possible error messages for these payouts:

Error Reason	Description
INVALID_BANK_ACCOUNT	Receiver account is invalid.
BLOCKED_BANK_ACCOUNT	Receiver account is blocked.
CLOSED_BANK_ACCOUNT	Receiver account is closed.
RECEIVER_ACCOUNT_LIMIT_EXCEEDED	Receiver account limit exceeded.
RECEIVER_ACCOUNT_NOT_ALLOWED	Receiver account does not allow this type of payment.
RECEIVER_INSTITUTION_FAILURE	Transaction aborted due to failure on receiver institution.
RECEIVER_INSTITUTION_NOT_ENABLED	Receiver institution is not enabled within the payment system.
RECEIVER_TAX_ID_DIVERGENT	Receiver tax id is divergent with account tax id.
DIVERGENT_ID	Refunded by bank, CPF/CNPJ is divergent.
ACCOUNT_TYPE_INCORRECT	Invalid account type and/or not allowed to receive external payments.
BLOCKED_BANK_ACCOUNT	Receiver account is blocked.
DOCUMENT_ID_DIFFERS_ACCOUNT	The bank account document is not a CPF or CNPJ
INVALID_PIX_KEY_DATA	The Parameter RecipientPixKeyType is not valid.
0_INVALID_PIX_KEY_TYPE (0)	The parameter RecipientPixKeyType is missing, or the value is invalid.
0_PAYOUT_INVALID_EMAIL	The value of email does not respect the formatting rules.
PAYOUT_INVALID_DOCUMENT_NUMBER	The value of DocumentNumber does not respect the formatting rules.