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": "CHRISTINE IGNACIO",
      "cpf": "14435549603"
    },
    "key": {
      "type": "CPF",
      "value": "14435549603"
    }, 
    "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.orderIdstringtrueA custom order id the integrator need to provide for idempotency, and 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 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": "CHRISTINE IGNACIO",
      "cpf": "14435549603"
    },
    "key": {
      "type": "CPF",
      "value": "14435549603"
    }
  },
  "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": "CHRISTINE IGNACIO",
      "cpf": "14435549603"
    },
    "key": {
      "value": "14435549603"
    }, 
    "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.