API Reference

PIX - Cash Out

This endpoint allows the creation of a PIX cash out request

Reference Endpoint

  • POST /accounts/pix/cashout

Success Scenario

The request payload is composed of three inner objects: payment, transaction and webhook, as seen in this example request.

{
  "payment": {
    "recipient": {
      "name": "ISADORA STEPHANY",
      "cpf": "13600642650"
    },
    "key": {
      "type": "CPF",
      "value": "13600642650"
    }, 
    "value": "10.50"
  },
  "transaction": {
    "orderId": "in-01901847474-560183477261001736",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • The Request Fields
FieldTypeRequiredDescription
payment.recipient.namestringtrueThe end-user (recipient) name
payment.recipient.cpfstringtrueThe end-user (recipient) CPF
payment.key.typestringtrueOne of the valid PIX key types, such as: CPF, EMAIL, PHONE or EVP (a Randomly Generated Key)
payment.key.valuestringtrueThe key value
payment.valuestringtrueThe effective value to be paid
transaction.orderIdstringfalseA custom order id the integrator need to provide for idempotency counter-check when the response arrives
transaction.orderDescriptionstringfalseA custom description the integrator might want to provide for counter-check when the response arrives
webhook.urlstringtrueAn absolute URL to recieve webhook notification events
webhook.customHeaderNamestringfalseA custom header name for counter-check when the webhook message arrives
webhook.customHeaderValuestringfalseA custom header value for counter-check when the webhook message arrives

In the example request, notice that the CPF value (14435549603) appears twice because the first one identifies the PIX key, that maps to a bank account where the payment will be transferred to, and the other identifies the end user itself, the recipient.

  • Success Response (201 - Created)
{
  "statusCode": "Done",
  "data": {
    "transaction": {
      "id": "95c0f371-bc71-4c06-823e-74cf5bc308fa",
      "orderId": "in-1409184409-98758761847691",
      "date": "2023-07-29T11:09:21.851Z",
      "state": "Created",
      "amount": "10.50"
    }
  }
}
  • The Response Fields
FieldTypeDescription
transaction.idStringAn Unique Identifier (UID)
transaction.orderIdStringAn ID provided by the integrator in the transaction request for counter-validation
transaction.dateStringThe transaction request creation date
transaction.stateStringThe transaction initial state. It starts as Created, which means it is still to be registered in a bank
transaction.amountStringThe original transaction request value

📘

CPF Validation

PayBrokers validates the CPF and denies requests for fake CPFs. While integrating, please use one of these real world CPFs for test: 13600642650, 10777438666.

Failure Scenarios (Useful Examples)

Scenario 1: Missing required field payment.value.

{
  "payment": {
    "recipient": {
      "name": "ISADORA STEPHANY",
      "cpf": "13600642650"
    },
    "key": {
      "type": "CPF",
      "value": "13600642650"
    }
  },
  "transaction": {
    "orderId": "in-1409184409-98758761847691",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • Failure Response (400 - Bad Request)
{
  "statusCode": "Error",
  "error": {
    "name": "InvalidRequestFormatError",
    "message": "The request body is invalid. See error object `details` property for more info",
    "details": [
      {
        "path": "/payment",
        "code": "required",
        "message": "must have required property 'value'",
        "info": {
          "missingProperty": "value"
        }
      }
    ]
  }
}

Scenario 2: Invalid value for payment.key.type (e-mail).

{
  "payment": {
    "key": {
      "type": "e-mail",
      "value": "[email protected]"
    },
    "value": "10"
  },
  "transaction": {
    "orderId": "in-1409184409-98758761847691",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • Failure Response (400 - Bad Request)
{
  "statusCode": "Error",
  "error": {
    "name": "InvalidRequestFormatError",
    "message": "The request body is invalid. See error object `details` property for more info",
    "details": [
      {
        "path": "/payment/key/type",
        "code": "enum",
        "message": "must be equal to one of the allowed values",
        "info": {
          "allowedValues": [
            "CPF",
            "EMAIL",
            "PHONE",
            "EVP"
          ]
        }
      }
    ]
  }
}

Scenario 3: Authentication Failure

If a request include an expired or invalid authentication token, the following error will be returned.

  • Failure Response (401 Unauthorized)
{
  "statusCode": "Error",
  "error": {
    "name": "AuthenticationError",
    "message": "The authorization token is invalid",
    "details": {
      "reason": "AuthenticationTokenInvalid"
    }
  }
}

Scenario 4: Missing required field payment.key.type

{
  "payment": {
    "recipient": {
      "name": "ISADORA STEPHANY",
      "cpf": "13600642650"
    },
    "key": {
      "value": "13600642650"
    }, 
    "value": "10.53"
  },
  "transaction": {
    "orderId": "in-1409184409-98758761847691",
    "orderDescription": "Created via postman"
  },
  "webhook": {
    "url": "https://postman-echo.com/post?test=1",
    "customHeaderName": "Authorization",
    "customHeaderValue": "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiI2YTZjYjY2NC03NzI4LTRjMGQtODI1My"
  }
}
  • Failure Response (409 - Conflict)
{
  "statusCode": "Error",
  "error": {
    "name": "OperationError",
    "code": "OperationError",
    "details": {
      "reason": "PixKeyTypeNotAllowed",
      "message": "This operation is not available for the PIX key of type 'undefined'"
    }
  }
}

❗️

Malformed requests

During tests, it is possible that integrators provide some incomplete or malformed request that cause a response an error 500 - Internal Server Error.